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. BACKUP does not suspend processes that only read from the database.

BACKUP ONLINE extends MUPIP BACKUP. 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.

The format of the BACKUP command is:

        
        B[ACKUP] [-qualifier[...]] region-list[,...] destination-list
      

Example:

        $ BACKUP -BYTESTREAM acn,hist bkup
        
        

The optional qualifiers are:

By default, BACKUP is -DATABASEONLINE.

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 %.

The first argument may specify more than once region of the current Global Directory in a list. Each region is separated by a comma.

-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 -reg REGA tcp://<machine name>:<port>
        
        

This command establishes a TCP/IP connection. The <machine name > must either be an IP address or resolve to an IP address. The backup output passes through this connection to a port that is ready to accept the data stream.

-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

BACKUP -DATABASE does not require exclusive access to the file. When an application uses multiple database files, the backup is consistent from an application point of view.

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.

By default, BACKUP is -DATABASE.

-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...]

Specifies journal actions as a part of the BACKUP process. For descriptions of journal options, refer to the GT.M Journaling Chapter.

-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

Specifies that a BACKUP -BYTESTREAM includes blocks changed since the last specified backup.

-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 allows the following:

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.

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