EXTRACT Command

Function

Copies the dictionary definition of one or more dictionary objects from your cur-rent dictionary to a command file.

Format

EXTRACT [ON] file-spec object-name [, ... ]

Arguments

file-spec

Is the specification of the RMS file to contain the definition or definitions in the following format:

For RSTS/E systems: dev:[PPN]file-name.type

For RSX systems: dev:[UIC]file-name.type;ver

You must specify at least one field in the file specification. On RSTS/E sys-tems, you must specify a file name. DA T ATRIEVE uses the following defaults for fields not specified:

Field

dev:

[UIC/PPN]

file-name .type

;ver object-name

Default

SY: (the system device) Your default UIC/PPN No default

.CMD

1 or next higher version (non -RSTS/E systems only)

Is the name of the dictionary object you want to extract.

Restrictions

• To extract the definition of a dictionary object from the dictionary, you must have read access privilege to the domain, record, procedure, or table .

• An ON file-spec clause must precede the list of dictionary object names.

EXTRACT

Continued

Results

• DATATRIEVE creates a command file with the file specification you provide.

DATATRIEVE enters into the command file a DELETE command and a DEFINE command for each dictionary object specified in the EXTRACT com-mand. The DEFINE command contains a copy of the object specified by the dic-tionary name.

• The EXTRACT command copies the text of the definition exactly as it was entered in the dictionary by DATATRIEVE. For example, when you extract a domain definition, the specification for the data file is extracted just as it was originally entered. Ifonly the file name (and not the device, directory, type, or version number) was stored in the dictionary, the EXTRACT command copies only the file name into the new DEFINE command.

• When the EXTRACT command copies the definition into the command file, DATATRIEVE does not delete the definition from the dictionary.

• When you invoke the command file, DELETE command in that file causes DATATRIEVE to delete from the dictionary the definition of any dictionary object with the same name as that of the extracted dictionary object.

Usage Notes

• The EXTRACT command enables you to create backup copies of your diction-ary objects and to transport data definitions to other dictionaries.

• To invoke the command file, type @ and the command file name in response to the DTR> prompt. If the file type is not .CMD, you must include the file type in the file specification.

• When you are moving a definition from one dictionary to another, use a SHOW object-name command to see ifan object with the same name as that in the DELETE and DEFINE commands exists in the new dictionary.

If the object exists, you must decide whether or not you want it deleted when you invoke the command file. If you do not want that object deleted, you must edit the command file to change the names in the DELETE and DEFINE commands.

Be sure to anticipate the problems that might arise when you change current dictionaries. No two objects in the same dictionary can have the same name. If you shift to a new current dictionary, however, that new one may legitimately contain an object with the same name.

For example, you extract the definition of procedure ABC from the dictionary WIDGETS.DIC. You then set your current dictionary to THINGS.DIC, which contains a dictionary table called ABC. If you invoke the command file, the DELETE ABC command in the command file deletes the table definition from THINGS.DIC, and the DEFINE PROCEDURE ABC command enters the pro-cedure definition.

EXTRACT

Continued

• To invoke a command file produced by the EXTRACT command, you must have system read access privilege to the file and you must have DATATRIEVE C (control) access to any dictionary objects to be deleted from the command file.

• The EXTRACT command does not copy the ACL of the dictionary object. After you invoke the command file, the ACL for the dictionary object is the default ACL assigned by the dictionary. Use the DEFINEP command to add other entries to the ACL .

• To extract all objects in a dictionary, use the QXTR utility provided with your DATATRIEVE-l1 installation kit. Run it at system command level by typing RUN $QXTR, then answer the on-line questions. The QXTR utility:

- Provides a backup of the whole dictionary

- Creates DEFINEP commands to reproduce the ACL of each object

- Gives you the option of extracting an object in a form suitable for using with VAX-II DATATRIEVE

See Chapter 21 in the DATATRIEVE-ll User's Guide for information on using QXTR.

Example

Extract the definitions of the domain YACHTS and the record YACHT from the dictionary OLDDIC.DIC. Change the current dictionary to a new dictionary, NEWDIC.DIC, and use the SHOW command to check for objects with the names YACHTS and YACHT in NEWDIC. Then invoke the command file created with the EXTRACT command to copy the YACHTS and YACHT definitions to

NEWDIC:

DTR} Ei-(TRACT ON MOt)ING YACHTS ^t YACHTOO DTR} SET DICTIONARY NEWDICm

DTR> SHOW DICTIONARym

The current dictionary is SY:[150t150JNEWDIC.DIC DTR> SHOW DOMAINS, RECORDS(6TI)

DOfTlains:

Records:

(continued on next page)

EXTRACT

Continued

DTR> @MOt.JING ([ill DELETE YACHTS;

IIYACHTS" has not been defined in the dictionar}' DEFINE DOMAIN YACHTS

USING YACHT ON YACHT.DAT;

DELETE YACHT;

II Y A C H T " has not bee n d e f in e din the d i c t ion a r}' DEFINE RECORD YACHT

USING

ALLOCATION IS LEFT_RIGHT 01 BOAT.

03 TYPE.

06 MANUFACTURER PIC X(10) QUERY_NAME IS BUILDER.

06 MODEL PIC X(10).

03 SPECIFICATIONS QUERY_NAME SPECS.

06 RIG PIC }-{(6)

{jALID IF RIG EQ IISLOOplI fIlKETCH" f"MSII tIlYAWLII.

06 LENGTH_OVER_ALL PIC XXX

VALID IF LOA BETWEEN 15 AND 50 QUERY_NAME IS LOA.

06 DISPLACEMENT PIC 99999 QUERY_HEADER IS IIWEIGHT II EDIT_STRING IS ZZtZZ9 QUERY_NAME IS DISP.

06 BEAM PIC 99.

06 PRICE PIC 99999

VALID IF PRICE>DISP*1.3 OR PRICE EQ 0 EDIT_STRING IS $$$t$$$.

[Record YACHT is al bytes 10ngJ DTR> SHOW DOMAINSt RECORDS([ill Domains:

YACHTS Records,:

YACHT DTR>

FIND