EXTRACT copies globals from the current database to a sequential output file in one of three formats–GO, BINARY, or ZWR. Use EXTRACT to backup specific globals or to extract data from the database for use by another system. EXTRACT uses the Global Directory to determine which database files to use. In addition, EXTRACT supports user collation routines. EXTRACT may operate concurrently with normal GT.M database access.

To ensure that an EXTRACT reflects a consistent application state, you must:

The format of the EXTRACT command is:

        EXTR[ACT] [/qualifier[...]] file-specification
        
         

The optional qualifiers are:

EXTRACT places its output in the file defined by the file-specification . EXTRACT may output to an RMS file on any device that supports such files, including magnetic tapes.

	Note
	Magnetic tapes may have a smaller maximum file size than disks.When directing the output file to a magnetic tape, use DCL to MOUNT the tape /INITIALIZE=CONTINUATION. This causes automatic handling of multiple volumes. When mounting a volume to tape for an EXTRACT, specify a blocksize that is eight (8) bytes larger than the size of the blocks in the database to accommodate RMS overhead.

For information on extracting globals with the %GO utility, refer to the "M Utility Routines" chapter of the GT.M Programmer's Guide. EXTRACT is typically faster, but %GO can be customized.

<CTRL-Y> or <CTRL-C> produces a status message from EXTRACT. Entering <CTRL-C> twice in quick succession terminates EXTRACT. An EXTRACT terminated abnormally by operator action or error produces incomplete output.

/FO[RMAT]=GO|B[INARY] | Z[WR]

Specifies the format of the output file.

The format codes are:

/FORMAT=GO stores the data in record pairs. Each global node produces one record for the key and one for the data. /FORMAT=GO has two header records.

EXTRACT /FORMAT=BINARY works much faster than EXTRACT /FORMAT=GO and EXTRACT /FORMAT=ZWR. However, it cannot be used to transport binary data from one computer architecture to another. EXTRACT /FORMAT=ZWR can be used to transport text (binary data from GT.M on one platform to GT.M on another platform.) EXTRACT /FORMAT=GO can be used to transport text and data from one M implementation to another.

	Note
	There is no defined standard to transport binary data from one GT.M implementation to another.

By default, EXTRACT uses /FORMAT=ZWR.

/FR[EEZE]

Prevents database updates to all database files from which the EXTRACT is copying records. /FREEZE ensures that the EXTRACT captures a "sharp" image of the globals, rather than one "blurred" by updates occurring while the copy is in progress.

By default, EXTRACT does not freeze regions during operation.

/LA[BEL]=text

Specifies the text string that becomes the first record in the output file. Enclose labels containing punctuation marks or lowercase characters in quotation marks (" "). EXTRACT /FORMAT=BINARY truncates the label text to 32 characters.

By default, EXTRACT uses the label "GT.M MUPIP EXTRACT."

For more detailed information about the /FORMAT=BINARY header label, refer to the description of EXTRACT /FORMAT=BINARY.

/[NO]LO[G]

For each global extracted, this qualifier specifies whether or not to display a message on SYS$OUTPUT. The message displays the number of global nodes, the maximum subscript length and maximum data length for each global.

By default, EXTRACT operates /LOG.

/S[ELECT]=global-name

Global specification can be a parenthetical list, such as (a,B,C). In this case, EXTRACT selects all globals except ^A, ^B, and ^C.

/S[ELECT]=global-name-list

Specifies the global(s) to extract. The caret symbol (^) in the specification of the global name is optional. Enclose lowercase global names in quotation marks (" ").

The global-specification can be:

By default, EXTRACT selects all globals, as if it had the qualifier /SELECT=*

	Note
	If the rules for selection are complex, it may be easier to construct an ad hoc Global Directory that maps the global variables to be extracted to the database file. This is not permissible if the database file is part of a replicated instance. If this is the case, work with a backup of the database.