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- name
        

The optional qualifiers are:

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

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.

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

-FORMAT=ZWR stores data as one record per global node. /FORMAT=ZWR has two header records.

EXTRACT -FORMAT=BINARY works much faster than EXTRACT -FORMAT=GO and EXTRACT -FORMAT=ZWR.

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

The global-specification can be:

In the first case, EXTRACT selects only global ^MEF. In the second case, EXTRACT selects all global names between ^A7 and ^B6, inclusive. In the third case, EXTRACT selects globals ^A, ^B, and ^C. In the fourth case, EXTRACT selects all global names from ^TMP through ^TMPzzzzz.

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