Retrieves a generation of one or more source modules from the current VDE library.

Format

FETCH gen-spec [, gen-spec...] ["remark"]

Parameter

gen-spec

Specifies a generation of a source module in the default stream to be retrieved from the library. A generation specification consists of the following in order:

• an optional facility name enclosed in square brackets
• a module name
• an optional type name preceded by a period
• an optional generation number preceded by a semicolon

An example of a generation specification is [RMS]MOD1.MAR;5.

If you omit the facility name, modules from the default facility are fetched. If you omit the type name, all source modules with the specified module name in the specified facility are fetched. If you omit the generation number, the most recent generation of the module in the requested development stream is fetched. This is either the stream specified with the /STREAM qualifier or the default development stream.

If you specify a zero or negative generation number, that number is relative to the most recent generation of the module in the requested development stream. For example, if the most recent generation is generation 5, then generation 0 is the same as generation 5 and generation --1 is the same as generation 4.

If you specify the /GENERATION qualifier, VDE fetches the generation with the given CMS generation expression and ignores the generation number on the gen-spec parameter.

You can fetch more than one module by using wildcard characters in the facility name, module name, or type name. (Wildcard characters are not allowed in the generation number.) The percent sign (%) in a name matches any single character in the position it occupies and the asterisk (*) matches zero or more characters in the position it occupies. Those source modules whose names match the wildcard pattern are fetched.

You can also fetch multiple modules by specifying the name of a source group instead of a generation expression. Source groups are created with the CREATE GROUP command. If you specify a group name, the latest generation of each module that is a member of the group is copied to your directory.

"remark"

Specifies a remark string to be logged in the history file with this command, usually to explain why the command was entered. Specifying the remark parameter is equivalent to specifying the /REMARK qualifier after the FETCH keyword.

Description

The FETCH command copies the specified generation of a module from the VDE library to a file in your default directory or the directory specified with the /OUTPUT qualifier. The module is not reserved from the library nor can it be replaced into the VDE library. You can fetch a module whether or not it is reserved.

The presence or absence of a remark determines whether the FETCH transaction is recorded in the CMS history file for the facility. If you enter a remark, VDE records the transaction in the history file. If you enter a null remark, VDE does not record the transaction in the history file.

When you fetch a generation of a module from a VDE library, VDE restores the file's creation time, revision time, record format, and record attributes. The file that is placed in your directory has the same creation and revision times as the file that created the generation that you are fetching.

Qualifiers

/CONFIRM

/NOCONFIRM (default)

Controls whether VDE asks you to confirm that you want each module fetched. The /CONFIRM qualifier causes VDE to print a message for each module generation that you have specified asking whether you want to fetch that generation. If you answer YES (or Y), the module is fetched. If you answer NO (or N), the module is not fetched. The /NOCONFIRM qualifier causes VDE to fetch each specified module generation without asking for confirmation.

/GENERATION=gen-expr

Specifies that the module generation with the CMS generation expression given by the gen-expr parameter be fetched from the VDE library. When this qualifier is specified, the generation number specified on the gen-spec parameter is ignored.

/HISTORY[="string"]

Specifies that history information is to be included in the file placed in your directory. The history of the module lists the generations that preceded the current generation of the module. Each generation produces one line of history information in the output file. This line gives the CMS generation number, user name, date, time, and remark associated with the generation.

The quoted string specifies the format of the history line. The quoted string must contain the characters #H or #B (lower case is allowed) and can contain other printing characters (such as comment delimiters). Each history line is formed by inserting the history information where you specify #H or #B in the history string. If you specify #H, the history information is inserted at the end of the file and if you specify #B it is inserted at the beginning of the file. To include a quotation mark in the output history string, type it twice (""). To include a number sign (#) in the output history string, type it twice (##). If the string parameter is omitted, VDE uses the module's default history string.

If the /HISTORY and /NOHISTORY qualifiers are both omitted, the FETCH command generates history information only if the history attribute is enabled for the module. This attribute is set with the CREATE MODULE or MODIFY MODULE command.

/NOHISTORY

Specifies that history information is not to be appended to the output file placed in your directory.

/LOG (default)

/NOLOG

Controls whether log messages are printed after each module generation is fetched. The /LOG qualifier causes such messages to be printed and /NOLOG suppresses them. The messages indicate that the modules have been fetched and that the database transaction has successfully committed.

/MERGE=stream-name

/MERGE=(gen-expr)

Controls whether another generation of the module (called the merge generation) is to be merged with the generation that is being fetched (called the retrieved generation). If you specify the /MERGE qualifier with the stream-name parameter, the merge generation is the latest generation of the module in the specified stream. If you specify the /MERGE qualifier with the gen-expr parameter enclosed in parentheses, the merge generation is the generation with the specified generation expression (for example, "2A3").

When you specify the /MERGE qualifier, VDE merges the lines of the retrieved generation with the lines of the merge generation and delivers the merged text as a single file to your output directory. The file that is placed in your directory has the current creation and revision times. The merge generation cannot be on the same line of descent as the retrieved generation. When there is a conflict between blocks of one or more lines, VDE includes the conflicting lines and flags the conflict.

VDE uses the callable interface to CMS to provide the merge capability. For a detailed explanation of how two generations are merged and how CMS (and therefore VDE) treats conflicts between the generations, see the CMS documentation.

/NOTES[="string"]

Specifies that CMS notes are to be appended to the lines of the output file. CMS notes indicate in what module generation each source line was created.

The quoted string specifies the format of the note. The quoted string can contain text (including the appropriate comment delimiter) and the characters #G or #g. The CMS generation expression of the generation in which the line first appeared in inserted where you specify #G or #g. The resulting string is appended to the end of the output line. To include a quotation mark in the output notes string, type it twice (""). To include a number sign (#) in the output notes string, type it twice (##). If the string parameter is omitted, VDE uses the module's default notes string. (You set the default notes string with the CREATE MODULE or MODIFY MODULE command.)

If the /NOTES and /NONOTES qualifiers are both omitted, the FETCH command generates CMS notes only if the notes attribute is enabled for the module. This attribute is set with the CREATE MODULE or MODIFY MODULE command.

/NONOTES

Specifies that CMS notes are not to be appended to the lines of the file placed in your directory.

/NOOUTPUT

Specifies that the fetch operation is to be performed along with any history processing and error checking but that no output file is to be created.

/OUTPUT=file-specification

Directs VDE to write the fetched module to the specified file. If you omit the directory from the file specification, VDE writes the file to your default directory. If you omit the file name or file type, VDE uses the module name and type by default. If you omit the /OUTPUT and /NOOUTPUT qualifiers entirely, VDE creates a file in your current default directory with the same name as the module.

If you fetch more than one module with the same /OUTPUT qualifier (by using either wildcards or a group name in the module-name parameter) and you do not specify wildcards in the output file specification, VDE creates successive versions of the file indicated by the /OUTPUT qualifier.

/POSITION=column-number

Specifies the column in which CMS notes are to be placed. The column number must be an integer in the range 1 to 511. If the length of an output line is less than the specified column number, the note appears at the specified column number. If the length of the line is greater than or equal to the column number, the note is placed at the next tab stop after the end of the line. (Tab stops are at position 9 and every 8 characters thereafter.)

If the /POSITION qualifier is omitted, the default notes position for the module is used. The default notes position is set with the CREATE MODULE or MODIFY MODULE command. The /POSITION qualifier has no effect unless the /NOTES qualifier is specified or the notes attribute is set for the module.

/REMARK="string"

Specifies a remark string to be logged in the CMS history file by this command, usually to explain why the command was entered. The remark is enclosed in quotation marks. If no remark is entered, the fetch operation is not logged.

/STREAM=stream-name

Specifies that the modules be fetched from the development stream given by the stream-name parameter. If this qualifier is omitted, the modules are fetched from the default development stream. If this qualifier is omitted and no default stream is defined, VDE prompts you for the stream name.

Examples

VDE„ FETCH [FACIL]MODNAM.MAR/REMARK="Just curious"
%VDE-I-FETCHED, module generation [FACIL]MODNAM.MAR;17(15A2) fetched from library
%VDE-I-OUTFILE, output file is DEV$:[MYDIR]MODNAM.MAR;
VDE„
      

This FETCH command retrieves the most recent generation of module [FACIL]MODNAM.MAR in the default development stream. The log message shows that the most recent generation is generation 17. Its CMS generation expression is 15A2. The file MODNAM.MAR is created in the user's default directory.

VDE„ FETCH FOO.BAR;5
%VDE-I-FETCHED, module generation [CODE]FOO.BAR;5(5) fetched from library
%VDE-I-OUTFILE, output file is DEV$:[MYDIR]FOO.BAR;
VDE„
      

This example fetches generation 5 of module FOO.BAR in the default stream. Generation 5 is not necessarily the most recent generation of the module in the default stream. Since no facility name is specified, the module is assumed to be in the default facility, facility CODE.

VDE„ FETCH FOO.BAR;-1
%VDE-I-FETCHED, module generation [CODE]FOO.BAR;5(5) fetched from library
%VDE-I-OUTFILE, output file is DEV$:[MYDIR]FOO.BAR;
VDE„
      

This example is the same as the previous example except that the user specifies a relative generation number, --1. This generation number causes VDE to fetch the generation before the most recent generation. In this case, generation 6 is the most recent generation. As a result, the FETCH command retrieves generation 5, as the log message shows.

VDE„ FETCH MOD1, MOD2, MOD3, X*
%VDE-I-FETCHED, module generation [CODE]MOD1.C;4(4) fetched from library
%VDE-I-OUTFILE, output file is DEV$:[MYDIR]MOD1.C;
%VDE-I-FETCHED, module generation [CODE]MOD2.C;8(7C1) fetched from library
%VDE-I-OUTFILE, output file is DEV$:[MYDIR]MOD2.C;
%VDE-I-FETCHED, module generation [CODE]MOD3.C;1(1) fetched from library
%VDE-I-OUTFILE, output file is DEV$:[MYDIR]MOD3.C;
%VDE-I-FETCHED, module generation [CODE]MOD3.PLI;1(1) fetched from library
%VDE-I-OUTFILE, output file is DEV$:[MYDIR]MOD3.PLI;
%VDE-I-FETCHED, module generation [CODE]XAVIER.PAS;25(5A2B8) fetched from library
%VDE-I-OUTFILE, output file is DEV$:[MYDIR]XAVIER.PAS;
%VDE-I-FETCHED, module generation [CODE]XERXES.FOR;5(5) fetched from library
%VDE-I-OUTFILE, output file is DEV$:[MYDIR]XERXES.FOR;
VDE„
      

In this example, the FETCH command retrieves the latest generations of modules MOD1.C, MOD2.C, MOD3.C, and MOD3.PLI, along with all source modules whose names begin with the letter X. The module type defaults to the wildcard string that matches all module types (*). Hence the command fetches both MOD3.C and MOD3.PLI.

The HELP command allows users to obtain command syntax and functional information about the VDE and the VSC utilities.

Format

HELP [topic]

Parameter

topic

Specifies the topic or command name about which you want information.

Description

To display the list of all available VDE commands and topics, enter the HELP command without a parameter. To obtain information about individual commands or topics, enter HELP followed by the command or topic name.

Qualifiers

None.

Examples

VDE„ HELP
      

This command causes VDE to list all commands and topics for which you can request help text.

VDE„ HELP BUILD
      

This command causes VDE to display help text explaining the BUILD command.

VDE„ HELP CREATE MODULE/REMARK
      

This command causes VDE to display help text explaining the /REMARK qualifier to the CREATE MODULE command.

VDE„ HELP LOGICAL_NAMES
      

This command causes VDE to display help text explaining logical names and how they are used by VDE.

Inserts a module generation into a specified development stream, making it the latest generation of the module in that stream.

Requires PERFREP privilege.

Format

INSERT GENERATION gen-spec [, gen-spec...] targ-stream-name ["remark"]

Parameter

gen-spec

Specifies a module generation in a specified development stream that should be inserted into the stream given by the stream-name parameter. A generation specification consists of the following in order:

• an optional facility name enclosed in square brackets
• a module name
• an optional type name preceded by a period
• an optional generation number preceded by a semicolon

An example of a generation specification is [RMS]MOD1.MAR;5.

If you omit the facility name, the default facility is assumed. If you omit the type name, generations for all source modules with the specified module name in the specified facility are inserted into the given stream. If you omit the generation number, the most recent generation of the module in the stream specified with the /STREAM qualifier is inserted into the given stream.

If you specify a zero or negative generation number, that number is relative to the most recent generation of the module in the stream given by the /STREAM qualifier. For example, if the most recent generation is generation 5, then generation 0 is the same as generation 5 and generation --1 is the same as generation 4.

If you specify the /GENERATION qualifier, VDE inserts the generation with the given CMS generation expression and ignores the generation number on the gen-spec parameter.

You can insert more than one generation by using wildcard characters in the facility name, module name, or type name. The percent sign (%) in a name matches any single character in the position it occupies and the asterisk (*) matches zero or more characters in the position it occupies. Wildcard characters are not allowed in the generation number. Those module generations whose names match the wildcard pattern are inserted into the stream-name stream.

Unless the WILD_INS_GEN library attribute is enabled, VDE does not allow wildcard characters in the generation specification when you use the /GENERATION qualifier. It seldom makes sense to select generations with the same CMS generation expression from different modules. For the same reason, VDE does not allow you to use wildcard characters and a non-zero generation number in the same generation specification (as in *.*;--2), again unless the WILD_INS_GEN library attribute is set.

targ-stream-name

Specifies the development stream into which the generations given by the gen-spec parameters should be inserted.

One can specify the source generation for the operation in several ways, one of which is based on the generation in a specified source stream---see the /STREAM qualifier.

"remark"

Specifies a remark string that explains why you inserted the generation into the specified stream. The quoted remark string can be up to 132 characters long. Specifying the remark parameter is equivalent to specifying the /REMARK qualifier after the INSERT GENERATION keywords.

Description

The INSERT GENERATION command inserts the module generations you specify with the gen-spec parameters into the development stream you specify with the stream-name parameter. Each such generation becomes the latest generation of the corresponding module in the stream-name stream. The command thus lets you move module generations from one stream to another stream.

If the specified module is currently reserved in the specified stream, VDE terminates that reservation since it is based on a module generation that no longer is the latest generation for the stream. VDE sends a mail message to notify the owner of the reservation that the reservation is lost.

Note that there are two stream specifications possible on this command. The destination stream---specified by the target stream name parameter---and the optional source stream qualifier.

Qualifiers

/CONFIRM

/NOCONFIRM (default)

Controls whether VDE asks you to confirm that you want each generation inserted into the specified stream. The /CONFIRM qualifier causes VDE to print a message for each generation giving the name of the generation and asking whether you want to insert the generation into the stream. If you answer YES (or Y), the generation is inserted into the stream. If you answer NO (or N), the generation is not inserted into the stream. The /NOCONFIRM qualifier causes VDE to insert each generation into the specified stream without asking for confirmation.

/NOCMS_CLASS

Prevents the inserted generations from being inserted into the CMS class for the specified stream, even if a CMS class is normally maintained for the stream. The INSERT GENERATION command executes faster than otherwise if CMS class memberships are not updated.

/GENERATION=gen-expr

Specifies that the generation with the CMS generation expression given by the gen-expr parameter be inserted into the specified stream. When this qualifier is specified, the generation number specified on the gen-spec parameter is ignored.

/LOG (default)

/NOLOG

Controls whether log messages are printed after the generations are inserted into the stream. The /LOG qualifier causes such messages to be printed and /NOLOG suppresses them. The messages indicate that the generations have been inserted into the specified stream and that the database transaction has successfully committed.

/REMARK="string"

Specifies a remark string that explains why you inserted the generation into the specified stream. The quoted remark string can be up to 132 characters long.

/STREAM=stream-name

Specifies the stream in which the generation should be looked up if you omit the /GENERATION qualifier. This qualifier thus affects the interpretation of the generation number in the command-level gen-spec parameter when the /GENERATION qualifier is omitted. If you omit both the /STREAM qualifier and the /GENERATION qualifier, VDE prompts you for the name of the stream in which to look up the generation number.

Examples

VDE„ INSERT GENERATION [FACIL]MODNAM.C;4/STREAM=V2.0 BL-22
%VDE-I-GENINSERT, generation [FACIL]MODNAM.C;4(4) inserted into stream BL-22
%VDE-I-COMMIT, database transaction has successfully committed
VDE„
VDE„ SET STREAM BL-22
VDE„ SHOW GENERATION [FACIL]MODNAM.C
Generation [FACIL]MODNAM.C;4(4)       by user JONES        on  9-MAY-1990 19:43
VDE„
      

This example inserts generation 4 of module [FACIL]MODNAM.C from stream V2.0 into stream BL-22, making that generation the latest generation in stream BL-22.