The BACKUP command allows you to save the contents of the database. Unless used with the / ONLINE qualifier, BACKUP suspends updates to all regions specified by the BACKUP command from the time it starts the first region until it finishes the last region. BACKUP ensures a consistent application state across all database regions involved in the backup. Even with the /NOONLINE qualifier, BACKUP does not suspend processes that only read from the database.

BACKUP ONLINE creates a backup of the database at the time the backup command is issued. If the running processes subsequently update the database, the backup does not reflect those updates. Since the state of the database at the start of the backup is well defined, (whereas the state of the database at the backup completion is not well defined when the backup command is issued), a MUPIP BACKUP /ONLINE has the advantage that a meaningful name such as "beginning of processing day" can be associated with the backup.

The format of the BACKUP command is:

            
        B[ACKUP] [/qualifier[...]] region-name[,...] FILE-SPECIFICATION
         

Example:

        
        
            $ BACKUP /BYTESTREAM ACN,HIST [.BKUP]
        
         

The optional qualifiers are:

By default, BACKUP is /DATABASE/ONLINE.

If any region name does not map to an existing accessible file, or if any element of the destination list is invalid, BACKUP rejects the command.

The BACKUP command may specify more than one region of the current Global Directory in a list. Regions are separated by commas. Any region-name may include the DCL wildcard characters * and %.

To BACKUP only one region, the output-specification can resolve to either an RMS file or directory name. To BACKUP several regions, the output-specification can either resolve to one of the following:

If the output-specification is a directory, MUPIP assigns each backup file the same name as the file associated with the segment of the corresponding region. Therefore, the target directory must not contain any of the database files to be backed up, and all regions to be backed up must have unique database file names (violating either requirement implies two or more files with the same name in the same directory).

When BACKUP is /BYTESTREAM, and output-specification is not a directory, output is not limited to VMS files. A TCP socket can also be specified as a destination for the backup of a region. The syntax is: TCP://<machine-name>:<port>. There must be an active listener at the specified destination. Note that since MUPIP RESTORE can listen at a TCP socket and the combination of BACKUP on one machine with a RESTORE on another may well be the most efficient way to create remote backups.

When individual file names or TCP sockets are specified for backup (as opposed to specifying a directory), there is a one-to-one, left-to-right mapping of region names to the output-specification names. Any wild card in the region names or the backup file names is expanded in the same order in which VMS expands that wild card. The number of regions must match the number of files, and the regions are mapped to the files from left to right in each list. For example, if the Global Directory has regions ACN, HIST, UBG1 and UBG2:

        MUPIP BACK /BYTE * FILE1.BCK,FILE2,BCK,
        TCP://file3.offsite.com:5986,FILE4.BCK

        Region ACN maps to FILE1.BCK, HIST maps to
        FILE2.BCK, UBG1 maps to a listener at port
        5986 at file3.offsite.com, and UBG2 maps
        to FILE4.BCK.

        MUPIP BACK /BYTE ACN,UBG*,HIST
        FILE1.BCK,FILE2,BCK,TCP://FILE3.OFFSITE.COM:5986,FILE4 .BCK

        Region ACN maps to FILE1.BCK, UBG1 maps to
        FILE2.BCK, UBG2 maps to a listener at port
        5986 at file3.offsite.com, and HIST maps to
        FILE4.BCK.

        MUPIP BACK /BYTE "*" FILE1.BCK,FILE2,BCK,
        TCP://file3.offsite.com:5986,FILE4.BCK

        Region ACN maps to FILE1.BCK, HIST maps to
        FILE2.BCK, UBG1 maps to a listener at port
        5986 at file3.offsite.com, and UBG2 maps to
        FILE4.BCK.

        MUPIP BACK /BYTE "ACN,UBG*,HIST" FILE1.BCK,FILE2,BCK,
        TCP://FILE3.OFFSITE.COM:5986,FILE4.BCK

        Region ACN maps to FILE1.BCK, UBG1 maps to
        FILE2.BCK, UBG2 maps to a listener at port
        5986 at file3.offsite.com, and HIST maps to
        FILE4.BCK.
        

	Caution
	BACKUP protects against overwriting an existing file. If a file with the name exists already, BACKUP will complete successfully to a file with a higher version number.

<CTRL-C> or <CTRL-Y> terminates BACKUP. If a BACKUP terminates due to operator intervention or an error, the backup of the region in process at the time of the termination is not valid. If the termination was due to operator intervention, BACKUP attempts to delete any partially complete files. With both types of backups, previously processed regions are structurally valid, but may be of limited usefulness since some regions are backed up and others are not. This implies that the overall backup lacks application consistency; therefore, only trust backups that complete normally.

When BACKUP /BYTESTREAM delivers its output to a magnetic tape or across DECnet, DCL commands preceding the BACKUP must establish an appropriate blocksize. When the output is a magnetic tape, the MOUNT command should specify /BLOCKSIZE= as a multiple of the GDS database blocksize + 12 bytes for overhead. When the output file is on a different DECnet node, SET RMS should specify NET= as at least the GDS database blocksize + 12 bytes for overhead. BACKUP uses the overhead for /BYTESTREAM operations, but not for /DATABASE operations. When directing the output file to a magnetic tape, use DCL to MOUNT the tape /INITIALIZE=CONTINUATION. This causes automatic handling of multiple volumes. If the block size is too small, the BACKUP fails when it encounters a full block.

/B[YTESTREAM]

The /B[YTESTREAM] qualifier specifies that BACKUP only include blocks from the databases that have changed since a prior point specified by the /SINCE or /TRANSACTION qualifiers. BACKUP may output to a file on any device that supports files, including magnetic tapes. MUPIP RESTORE integrates the results of a BACKUP /BYTESTREAM into a database.

When the /BYTESTREAM qualifier is used with the /ONLINE qualifier, you may send the output to a TCP/IP connection.

Example:

            
        $MUPIP BACKUP /BYTESTREAM /REG REGA
        TCP://192.168.109.81:2453
        
         

The /BYTESTREAM qualifier is not compatible with the /COMPREHENSIVE or /DATABASE qualifiers.

/C[OMPREHENSIVE]

The /COMPREHENSIVE qualifier has been replaced by the /DATABASE qualifier. For upward compatibility, MUPIP temporarily continues to support the COMPREHENSIVE qualifier. The function of the COMPREHENSIVE qualifier is the same as the /DATABASE qualifier. Refer to the description of the /DATABASE qualifier for details.

/DATABASE

Instructs the BACKUP utility to copy the files of all selected regions from disk to disk. When complete, the backup copy is ready for use as a GT.M database. This option does not support backup to magnetic tape or TCP sockets (the target device must support random access to files).

The /DATABASE qualifier ensures all the information buffered in cache is first flushed to the disk. The /DATABASE qualifier is only compatible with the /JOURNAL, /[NO]NEW[JNLFILES], /ONLINE, and /RECORD qualifiers.

BACKUP /DATABASE produces a result similar to the result produced by a DCL COPY command or some variations of the DCL BACKUP command, except that consistency of the database is ensured with MUPIP, but must be separately implemented (e.g., with a FREEZE and a FLUSH) if the DCL commands are used.

By default, BACKUP is /DATABASE/ONLINE.

/I[NCREMENTAL]

The /INCREMENTAL qualifier has been replaced by the /BYTESTREAM qualifier. For upward compatibility, MUPIP temporarily continues to support the /INCREMENTAL qualifier. The function of the /INCREMENTAL qualifier is the same as the /BYTESTREAM qualifier. Refer to the description of the /BYTESTREAM qualifier for details.

/[NO]J[OURNAL][=options...]

When used in conjunction with /DATABASE /NEWJNLFILES, this qualifier specifies journaling information to be recorded into the file header of the backup of the database file(s).

The database file header stores the journaling options for the current database, including the journal file name. The default behavior, if this qualifier is not specified, is for the journaling options in the backup to be identical to those of the database. This is appropriate behavior if the backup is to be restored and used as a replacement for the database, (e.g., in the event of failure of the I/O subsystem on which the database is stored). However, if the backup copy of the database is used on the same machine for other purposes, such as report generation or for development and testing of new software, the journaling information in the database file header could lead to a corrupt journal file since updates to the original database and the copy would write over each other. Using this qualifier can protect against this outcome.

Also, when new journal files are created for the database files being backed up, the new journal files have a "backchain" pointer to the previous journal file. MUPIP RECOVER and ROLLBACK will automatically follow these backchain pointers as needed to perform their tasks. This qualifier can also be used to create new journal files with no backchain pointer.

/NOJOURNAL creates a backup with all journaling options cleared.

/JOURNAL=OFF creates a backup with journaling turned OFF (equivalent to executing a MUPIP SET /JOURNAL=OFF on the backup database)

/JOURNAL=DISABLE creates a backup with journaling disabled (equivalent to executing MUPIP SET /JOURNAL=DISABLE on the backup database. /NOJOURNAL is equivalent to /JOURNAL=DISABLE. Both clear journaling options in a backup database.

/[NO]JOURNAL=NOPREVJNLFILES to create new journal files with no backchain pointer. /NOJOURNAL cannot have a value.

Multiple options can be specified by including them in a parenthesized list, e.g., /JOURNAL=(DISABLE, NOPREVJNLFILES).

/NET[TIMEOUT]=seconds

Specifies the timeout period when BACKUP data is sent over a TCP/IP connection. This qualifier is meaningful only with the /ONLINE and /BYTESTREAM qualifiers, otherwise GT.M ignores the command. The default value is 30 seconds.

The /NET[TIMEOUT] qualifier is not compatible with the /DATABASE and /COMPREHENSIVE qualifiers.

/[NO]NEW[JNLFILES]

Specifies whether or not GT.M switches journal files for updates occurring after the start of the backup.

/[NO]O[NLINE]

Specifies that while the backup is active, other processes can read from, and update, the database without affecting the result of the backup. By default, BACKUP is /ONLINE.

BACKUP -ONLINE allows continued operation of the application using the database. The -BYTESTREAM form is able to transfer to output to a TCP/IP connection or a pipe.

/R[ECORD]

Instructs the BACKUP utility to record this backup as a reference point for subsequent /BYTESTREAM backups. For more information about using the /RECORD qualifier with the /SINCE qualifier, refer to the /SINCE qualifier section below.

Each time a BACKUP specifies /RECORD, that backup, relative to the time stamp or transaction number, replaces the previously recorded backup timestamp as the /RECORD reference point for the file.

/S[INCE]=keyword

A BACKUP /BYTESTREAM backs up those blocks that have changed since a specified point in the state of the database.

/SINCE accepts the following keywords:

The SINCE qualifier is incompatible with the /COMPREHENSIVE, /DATABASE, and /TRANSACTION qualifiers.

By default, BACKUP /BYTESTREAM operates as /S[INCE]=DATABASE.

/T[RANSACTION]=transaction-number

Specifies a starting transaction that causes BACKUP /BYTESTREAM to copy all blocks that have been changed by the specified transaction and all subsequent transactions. Transaction numbers are hexadecimal. They appear in a DSE DUMP /FILEHEADER with a "Current TN" label. If the transaction number is invalid, BACKUP reports an error and rejects the command.

BACKUP /BYTESTREAM /TRANSACTION=1 copies all in-use blocks, and produces a result similar to the result produced by BACKUP /DATABASE. However:

A point in time that is consistent from an application perspective is unlikely to have the same transaction number in all database regions. Therefore, except for /TRANSACTION=1, this qualifier is not likely to be useful for backup involving multiple regions, or where a previous /BYTESTREAM backup file is inadvertently deleted and a new backup is required to replace it.

The /TRANSACTION qualifier is incompatible with the /COMPREHENSIVE, /DATABASE, and /SINCE qualifiers.