Retrieves a copy of a generation of one or more elements from a
CMS library.
Format:
FETCH element-expression "remark"
1 – Command Parameters
element-expression
Specifies one or more generations of an element to be retrieved
from the library. An element expression can be an element name, a
group name, a wildcard expression, or a list of these separated by
commas. By default, the most recent generation on the main line of
descent is fetched.
remark
Specifies a character string to be logged in the history file
with this command, usually used to explain why the command was
entered. The remark is enclosed in quotation marks. If no remark
was entered, a null remark ("") is logged.
2 – Description
The FETCH command delivers a copy of the specified element
generation to your current default directory. The element is not
reserved, and CMS does not allow you to replace a fetched element.
CMS allows you to fetch an element that is reserved, and notifies
you of any current reservations for the element.
The presence or absence of a remark determines whether the FETCH
transaction is recorded in the library history. If you enter a
remark, CMS records the transaction in the history file. If you
enter a null remark, CMS does not record the transaction in the
history file.
If a version of a file with the same name as the element already
exists in your current default directory when you execute the
fetch transaction, CMS notifies you. A new version is then created
with the next higher version number.
When you fetch a generation of an element from a CMS library, CMS
restores the file creation time, revision time, revision number,
and record format and attributes. The file that is placed in your
directory has the same creation and revision times as the file
that was used to create the generation that you are fetching.
3 – Qualifiers
3.1 /CONFIRM
Controls whether CMS prompts you for confirmation before each
transaction.
When you specify /CONFIRM and run CMS in interactive mode, CMS
prompts you for confirmation. If you type YES, ALL, TRUE, or 1,
CMS executes the transaction. If you type NO, QUIT, FALSE, 0,
or press RETURN or CTRL/Z, no action is performed. If you type
any other character, CMS continues to prompt until you type an
acceptable response.
CMS does not prompt for confirmation in batch mode.
3.2 /GENERATION[=generation-expression]
Specifies a particular generation of the element that is to be
retrieved. If you omit /GENERATION, CMS fetches the most recent
generation on the main line of descent.
3.3 /HISTORY="string"
Specifies that history is to be included in the retrieved file.
The quoted string specifies the format of the history. The quoted
string must contain the characters #H or #B (lowercase is allowed)
and can contain other printing characters. 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
(##).
3.4 /NOHISTORY
Prevents CMS from appending the element history to the file. If
you omit /NOHISTORY, and the retrieved element has the history
attribute, the element history is included in the file when it is
delivered to your current default directory. An element has the
history attribute if you specified the /HISTORY qualifier on the
CREATE ELEMENT or MODIFY ELEMENT command.
3.5 /LOG (D)
Controls whether CMS displays success and informational messages
on the default output device. By default, if the command executes
successfully, CMS displays a success message. If you specify
/NOLOG, success and informational messages are suppressed. Any
warning, error, or fatal error messages are displayed regardless
of whether /LOG or /NOLOG is specified.
3.6 /MERGE=generation-expression
Controls whether another generation of the element (called the
merge generation) is to be merged with the generation that is
being fetched (called the retrieved generation).
When you specify the /MERGE qualifier, CMS merges the lines of
the two generations and delivers a single copy to your default
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, CMS
includes the conflicting lines and flags the conflict.
3.7 /NOTES="string"
Temporarily establishes the notes attribute for the element,
regardless of whether the element previously had the notes
attribute enabled. If neither the /NOTES or /NONOTES qualifier is
specified for an element, but the element has the notes attribute
enabled, notes are appended to the lines of the file when it is
retrieved by the FETCH or RESERVE command.
The quoted string specifies the format of the note. The quoted
string can contain text or the characters #G (or #g), or both.
If you specify /NOTES for an element that does not have the notes
attribute enabled, then you must also specify /POSITION.
3.8 /NONOTES
Specifies that notes are not to be embedded in the output file.
If you omit /NONOTES, and the retrieved element has the notes
attribute, CMS embeds notes in the output file. An element has
the notes attribute if you specified the /NOTES qualifier on the
CREATE ELEMENT or MODIFY ELEMENT command.
3.9 /OCCLUDE[=option,...]
Controls whether CMS selects the first instance of the specified
object, or all instances of the specified object in the library
search list. The options field contains one or more keywords
associated with the name of the object. The options field can
contain the following keywords:
ALL--equivalent to (ELEMENT, GROUP, CLASS)
ELEMENT (D)
NOELEMENT
GROUP (D)
NOGROUP
CLASS (D)
NOCLASS
NONE--equivalent to (NOELEMENT, NOGROUP, NOCLASS)
You can specify either ALL or NONE, or any combination of the
[NO]ELEMENT, [NO]GROUP, and [NO]CLASS keywords.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
3.10 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file. If you omit the
/OUTPUT qualifier (or if you specify /OUTPUT but do not provide a
file specification), CMS creates a file with the same name as the
element.
If you fetch more than one element (by specifying wildcards or a
group name for the element expression parameter), and you do not
specify wildcards in the output file specification, CMS creates
successive versions of the file indicated by /OUTPUT.
3.11 /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. By default, an output file with the same name as
the element is created.
3.12 /POSITION=column-number
Specifies the column in which the note is to be placed. The column
number is required and must be an integer in the range 1 to 511.
The notes attribute or the /NOTES qualifier is required with the
/POSITION qualifier.
If the length of the line is less than the specified column
number, the note appears at the 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.)
4 – Example
CMS> FETCH INIT.FOR "check for correct spelling"
Element INIT.FOR currently reserved by:
(1) SMITH 2 30-APR-1988 15:48:35.65 "to add new routine"
%CMS-S-FETCHED, generation 2 of element DISKX:[PROJECT.CMSLIB]INIT.FOR
fetched
This command fetches the latest generation on the main line of
descent of element INIT.FOR. CMS indicates that the element is
reserved, then continues with the fetch transaction.