Return-Path: 
 <derby-commits-return-2543-apmail-db-derby-commits-archive=db.apache.org@db.apache.org>
Delivered-To: apmail-db-derby-commits-archive@www.apache.org
Received: (qmail 59807 invoked from network); 8 Mar 2006 01:26:00 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur.apache.org with SMTP; 8 Mar 2006 01:26:00 -0000
Received: (qmail 94078 invoked by uid 500); 8 Mar 2006 01:25:59 -0000
Delivered-To: apmail-db-derby-commits-archive@db.apache.org
Received: (qmail 94049 invoked by uid 500); 8 Mar 2006 01:25:59 -0000
Mailing-List: contact derby-commits-help@db.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:derby-commits-help@db.apache.org>
list-unsubscribe: <mailto:derby-commits-unsubscribe@db.apache.org>
List-Post: <mailto:derby-commits@db.apache.org>
Reply-To: "Derby Development" <derby-dev@db.apache.org>
List-Id: <derby-commits.db.apache.org>
Delivered-To: mailing list derby-commits@db.apache.org
Received: (qmail 94038 invoked by uid 99); 8 Mar 2006 01:25:59 -0000
Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 07 Mar 2006 17:25:59 -0800
X-ASF-Spam-Status: No, hits=-9.4 required=10.0
	tests=ALL_TRUSTED,NO_REAL_NAME
X-Spam-Check-By: apache.org
Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194)
    by apache.org (qpsmtpd/0.29) with SMTP; Tue, 07 Mar 2006 17:25:58 -0800
Received: (qmail 59627 invoked by uid 65534); 8 Mar 2006 01:25:37 -0000
Message-ID: <20060308012537.59626.qmail@minotaur.apache.org>
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r384085 - in /db/derby/docs/trunk/src:
 adminguide/cadminhubbkup01.dita adminguide/cadminhubbkup63476.dita
 adminguide/cadminhubbkup75469.dita adminguide/cadminhubbkup98797.dita
 adminguide/cadminrollforward.dita ref/refderby.ditamap
Date: Wed, 08 Mar 2006 01:25:36 -0000
To: derby-commits@db.apache.org
From: fuzzylogic@apache.org
X-Mailer: svnmailer-1.0.7
X-Virus-Checked: Checked by ClamAV on apache.org
X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N

Author: fuzzylogic
Date: Tue Mar  7 17:25:35 2006
New Revision: 384085

URL: http://svn.apache.org/viewcvs?rev=384085&view=rev
Log:
DERBY-916: Document DERBY-239, online backup.

Committed for Jeff Levitt <derby@mylevita.com>

Modified:
    db/derby/docs/trunk/src/adminguide/cadminhubbkup01.dita
    db/derby/docs/trunk/src/adminguide/cadminhubbkup63476.dita
    db/derby/docs/trunk/src/adminguide/cadminhubbkup75469.dita
    db/derby/docs/trunk/src/adminguide/cadminhubbkup98797.dita
    db/derby/docs/trunk/src/adminguide/cadminrollforward.dita
    db/derby/docs/trunk/src/ref/refderby.ditamap

Modified: db/derby/docs/trunk/src/adminguide/cadminhubbkup01.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/adminguide/cadminhubbkup01.dita?rev=384085&r1=384084&r2=384085&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/cadminhubbkup01.dita (original)
+++ db/derby/docs/trunk/src/adminguide/cadminhubbkup01.dita Tue Mar  7 17:25:35 2006
@@ -1,4 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
+
 <!DOCTYPE concept PUBLIC "-//IBM//DTD DITA Concept//EN"
  "../dtd/concept.dtd">
 <!-- 
@@ -18,25 +19,28 @@
 -->
 <concept id="cadminhubbkup01" xml:lang="en-us">
 <title>Using the backup procedure to perform an online backup</title>
-<shortdesc>The SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure locks the database so that any connection trying to write to the database will be frozen until the backup completes. Database reads can continue while the backup is running.</shortdesc>
+<shortdesc>Use the SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure to perform an
+online backup of a database to a specified location.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>Backup procedure</indexterm><indexterm>SYSCS_BACKUP_DATABASE()
 system procedure</indexterm></keywords>
 </metadata></prolog>
 <conbody>
-<p>The SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure
-takes a string argument that represents the location in which to back up the
-database. Typically, you provide the full path to the backup directory. (Relative
-paths are interpreted as relative to the current directory, not to the derby.system.home directory.)</p>
-<p>For example, to specify a backup location of <filepath>c:/mybackups/2005-06-01</filepath> for a database that is currently open, use the following statement (forward slashes are used as path separators in SQL commands):</p>
+<p>The SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure takes a string argument
+that represents the location in which to back up the database. Typically,
+you provide the full path to the backup directory. (Relative paths are interpreted
+as relative to the current directory, not to the derby.system.home directory.)</p>
+<p>For example, to specify a backup location of <filepath>c:/mybackups/2005-06-01</filepath> for
+a database that is currently open, use the following statement (forward slashes
+are used as path separators in SQL commands):</p>
 <codeblock><b>CALL SYSCS_UTIL.SYSCS_BACKUP_DATABASE('c:/mybackups/2005-06-01')</b></codeblock>
 <p>The <i>SYSCS_UTIL.SYSCS_BACKUP_DATABASE()</i> procedure puts the database
 into a state in which it can be safely copied, then copies the entire original
 database directory (including data files, online transaction log files, and
-jar files) to the specified backup directory. Files that are not within the original
-database directory (for example, <i>derby.properties</i>) are <i>not</i> copied.</p>
-<p>The following example shows how to back up a database to a directory with a name
-that reflects the current date:</p>
+jar files) to the specified backup directory. Files that are not within the
+original database directory (for example, <i>derby.properties</i>) are <i>not</i> copied.</p>
+<p>The following example shows how to back up a database to a directory with
+a name that reflects the current date:</p>
 <codeblock>public static void backUpDatabase(Connection conn)throws SQLException
 {
 <b>// Get today's date as a string:</b>
@@ -51,11 +55,25 @@
 cs.close();
 System.out.println("backed up database to "+backupdirectory);
 }</codeblock>
-<p>For a database that was backed up on 2005-06-01, the previous commands copy the current
-database to a directory of the same name in <i>c:/mybackups/2005-06-01</i>.</p>
+<p>For a database that was backed up on 2005-06-01, the previous commands
+copy the current database to a directory of the same name in <i>c:/mybackups/2005-06-01</i>.</p>
 <p>Uncommitted transactions do not appear in the backed-up database.</p>
 <note>Do not back up different databases with the same name to the same backup
 directory. If a database of the same name already exists in the backup directory,
 it is assumed to be an older version and is overwritten.</note>
+<p>The SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure will issue an error if there
+are any unlogged operations in the same transaction as the backup procedure.</p>
+<p>If any unlogged operations are in progress in other transactions in the
+system when the backup starts, this procedure will block until those transactions
+are complete before performing the backup.</p>
+<p>Derby automatically converts unlogged operations to logged mode if they
+are started while the backup is in progress (except operations that maintain
+application jar files in the database). Procedures to install, replace, and
+remove jar files in a database are blocked while the backup is in progress.</p>
+<p>If you do not want backup to block until unlogged operations in other transactions
+are complete, use the SYSCS_UTIL.SYSCS_BACKUP_DATABASE_NOWAIT procedure. 
+This procedure issues an error immediately at the start of the backup if there
+are any transactions in progress with unlogged operations, instead of waiting
+for those transactions to complete.</p>
 </conbody>
 </concept>

Modified: db/derby/docs/trunk/src/adminguide/cadminhubbkup63476.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/adminguide/cadminhubbkup63476.dita?rev=384085&r1=384084&r2=384085&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/cadminhubbkup63476.dita (original)
+++ db/derby/docs/trunk/src/adminguide/cadminhubbkup63476.dita Tue Mar  7 17:25:35 2006
@@ -1,4 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//IBM//DTD DITA Concept//EN"
+ "../dtd/concept.dtd">
 <!-- 
 Copyright 1997, 2005 The Apache Software Foundation or its licensors, as applicable.  
 
@@ -14,14 +17,13 @@
 See the License for the specific language governing permissions and  
 limitations under the License.
 -->
-<!DOCTYPE concept PUBLIC "-//IBM//DTD DITA Concept//EN" "../dtd/concept.dtd">
-<concept xml:lang="en-us" id="cadminhubbkup63476">
+<concept id="cadminhubbkup63476" xml:lang="en-us">
 <title>Online backups</title>
-<prolog>
-</prolog>
+<prolog></prolog>
 <conbody>
-<p>Use online backups to back up a database while it is running. During the
-interval that the backup is running, the database can be read, but writes to the
-database are blocked. </p>
-<p>You can perform online backups by using the backup procedure or by using operating systems commands with the freeze and unfreeze system procedures.</p>
-</conbody></concept>
+<p>Use online backups to back up a database while it is running.</p>
+<p>You can perform online backups by using several types of backup procedures
+or by using operating systems commands with the freeze and unfreeze system
+procedures.</p>
+</conbody>
+</concept>

Modified: db/derby/docs/trunk/src/adminguide/cadminhubbkup75469.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/adminguide/cadminhubbkup75469.dita?rev=384085&r1=384084&r2=384085&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/cadminhubbkup75469.dita (original)
+++ db/derby/docs/trunk/src/adminguide/cadminhubbkup75469.dita Tue Mar  7 17:25:35 2006
@@ -1,4 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
+
 <!DOCTYPE concept PUBLIC "-//IBM//DTD DITA Concept//EN"
  "../dtd/concept.dtd">
 <!-- 
@@ -20,31 +21,33 @@
 <title>Using operating system commands with the freeze and unfreeze system
 procedures to perform an online backup</title>
 <prolog><metadata>
-<keywords><indexterm>SYSCS_FREEZE_DATABASE system procedure</indexterm>
-<indexterm>SYSCS_UNFREEZE_DATABASE system procedure</indexterm>
-</keywords>
+<keywords><indexterm>SYSCS_FREEZE_DATABASE system procedure</indexterm><indexterm>SYSCS_UNFREEZE_DATABASE
+system procedure</indexterm></keywords>
 </metadata></prolog>
 <conbody>
 <p>Typically, these procedures are used to speed up the copy operation involved
-in an online backup. In this scenario, <ph conref="adminconrefs.dita#prod/productshortname"></ph> does not perform the copy operation for you. You use the SYSCS_UTIL.SYSCS_FREEZE_DATABASE procedure
-to lock the database, and then you explicitly copy the database directory by using
-operating system commands. </p>
-<p>For example, because the UNIX tar command uses operating system
-file-copying routines, and <ph conref="adminconrefs.dita#prod/productshortname"></ph> uses
-the IBM Application Developer Kit file-copying routines, the tar command might provide
-faster backups than the SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure.</p>
-<p>To use operating system commands for online database backups, call the SYSCS_UTIL.SYSCS_FREEZE_DATABASE system
-procedure. The SYSCS_UTIL.SYSCS_FREEZE_DATABASE system procedure
-puts the database into a state in which it can be safely copied. After the
-database has been copied, use the SYSCS_UTIL.SYSCS_UNFREEZE_DATABASE system
-procedure to continue working with the database. Only after SYSCS_UTIL.SYSCS_UNFREEZE_DATABASE has
-been specified can transactions once again write to the database. Read operations
-can proceed while the database is "frozen."</p>
+in an online backup. In this scenario, <ph conref="adminconrefs.dita#prod/productshortname"></ph> does
+not perform the copy operation for you. You use the SYSCS_UTIL.SYSCS_FREEZE_DATABASE
+procedure to lock the database, and then you explicitly copy the database
+directory by using operating system commands. </p>
+<p>For example, because the UNIX tar command uses operating system file-copying
+routines, and the SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure uses java I/O
+calls with additional internal synchronization that allow updates during the
+backup, the tar command might provide faster backups than the SYSCS_UTIL.SYSCS_BACKUP_DATABASE
+procedure.</p>
+<p>To use operating system commands for online database backups, call the
+SYSCS_UTIL.SYSCS_FREEZE_DATABASE system procedure. The SYSCS_UTIL.SYSCS_FREEZE_DATABASE
+system procedure puts the database into a state in which it can be safely
+copied. After the database has been copied, use the SYSCS_UTIL.SYSCS_UNFREEZE_DATABASE
+system procedure to continue working with the database. Only after SYSCS_UTIL.SYSCS_UNFREEZE_DATABASE
+has been specified can transactions once again write to the database. Read
+operations can proceed while the database is "frozen."</p>
 <note>To ensure a consistent backup of the database, <ph conref="adminconrefs.dita#prod/productshortname"></ph> might
-block applications that attempt to write to a frozen database until the
-backup is completed and the SYSCS_UTIL.SYSCS_UNFREEZE_DATABASE system
-procedure is called.</note>
-<p>The following example demonstrates how the freeze and unfreeze procedures are used to surround an operating system copy command:</p>
+block applications that attempt to write to a frozen database until the backup
+is completed and the SYSCS_UTIL.SYSCS_UNFREEZE_DATABASE system procedure is
+called.</note>
+<p>The following example demonstrates how the freeze and unfreeze procedures
+are used to surround an operating system copy command:</p>
 <codeblock>public static void backUpDatabaseWithFreeze(Connection conn)
 	throws SQLException
 {

Modified: db/derby/docs/trunk/src/adminguide/cadminhubbkup98797.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/adminguide/cadminhubbkup98797.dita?rev=384085&r1=384084&r2=384085&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/cadminhubbkup98797.dita (original)
+++ db/derby/docs/trunk/src/adminguide/cadminhubbkup98797.dita Tue Mar  7 17:25:35 2006
@@ -1,4 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
+
 <!DOCTYPE concept PUBLIC "-//IBM//DTD DITA Concept//EN"
  "../dtd/concept.dtd">
 <!-- 
@@ -24,8 +25,5 @@
 <prolog><metadata>
 <keywords><indexterm>Backing up databases</indexterm></keywords>
 </metadata></prolog>
-<conbody>
-<p>While the backup is in progress, update operations are temporarily blocked,
-but read operations can still proceed.</p>
-</conbody>
+<conbody></conbody>
 </concept>

Modified: db/derby/docs/trunk/src/adminguide/cadminrollforward.dita
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/adminguide/cadminrollforward.dita?rev=384085&r1=384084&r2=384085&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/cadminrollforward.dita (original)
+++ db/derby/docs/trunk/src/adminguide/cadminrollforward.dita Tue Mar  7 17:25:35 2006
@@ -1,4 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
+
 <!DOCTYPE concept PUBLIC "-//IBM//DTD DITA Concept//EN"
  "../dtd/concept.dtd">
 <!-- 
@@ -78,6 +79,21 @@
 is non-zero. The log files are deleted only after a successful backup. <note>Make
 sure to store the backup database in a safe place when you choose the log
 file removal option.</note></p>
+<p>The SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE procedure
+will issue an error if there are any unlogged operations in the same transaction
+as backup procedure.</p>
+<p>If any unlogged operations are in progress in other transactions in the
+system when the backup starts, this procedure will block until those transactions
+are complete before performing the backup. Derby automatically converts unlogged
+operations to logged mode if they are started while the backup is in progress
+(except operations that maintain application jar files in the database). Procedures
+to install, replace, and remove jar files in a database are blocked while
+the backup is in progress.</p>
+<p>If you do not want backup to block until unlogged operations in other transactions
+are complete, use the SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE_NOWAIT
+procedure. This procedure issues an error immediately at the start of the
+backup if there are any transactions in progress with unlogged operations,
+instead of waiting for those transactions to complete.</p>
 <p><b>Disabling log archival mode:</b></p>
 <p>After you enable log archival mode, the database will always have the log
 archival mode enabled even if it is subsequently booted or backed up. The

Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewcvs/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=384085&r1=384084&r2=384085&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Tue Mar  7 17:25:35 2006
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE map PUBLIC "-//IBM//DTD DITA Map//EN"
- "../dtd/map.dtd">
+<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
+ "map.dtd">
 <!-- 
 Copyright 1997, 2005 The Apache Software Foundation or its licensors, as applicable.  
 
@@ -230,6 +230,14 @@
 <topicref href="rrefcheckpointdbproc.dita" navtitle="SYSCS_UTIL.SYSCS_CHECKPOINT_DATABASE">
 </topicref>
 <topicref href="rrefbackupdbproc.dita" navtitle="SYSCS_UTIL.SYSCS_BACKUP_DATABASE">
+</topicref>
+<topicref href="rrefonlinebackupdbnowaitproc.dita" navtitle="SYSC_UTIL.SYSCS_ONLINE_BACKUP_DATABASE_NOWAIT">
+</topicref>
+<topicref href="rrefbackupdbenablelogproc.dita" navtitle="SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE">
+</topicref>
+<topicref href="rrefbackupdbenablelognowaitproc.dita" navtitle="SYSC_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE_NOWAIT">
+</topicref>
+<topicref href="rrefdisablelogproc.dita" navtitle="SYSCS_UTIL.SYSCS_DISABLE_LOG_ARCHIVE_MODE">
 </topicref>
 <topicref href="rrefexportproc.dita" navtitle="SYSCS_UTIL.SYSCS_EXPORT_TABLE">
 </topicref>