Retrieves a copy of each specified element generation from a CMS
library and marks it as reserved.
Format:
RESERVE element-expression "remark"
1 – Command Parameters
element-expression
Specifies the element or elements from which a generation is
to be reserved. An element expression can be an element name,
a group name, a wildcard expression, or a list of these separated
by commas. By default, CMS reserves the most recent generation
on the main line of descent of each element designated by the
element-expression.
remark
Specifies a character string to be associated with the reservation
and logged in the history file with this command. The remark is
enclosed in quotation marks. If no remark was entered, a null
remark ("") is logged.
2 – Description
The RESERVE command sends a copy of the specified generation of
each specified element to your current default directory (or to
another location if you specified the /OUTPUT qualifier). Each
element is marked as reserved. Usually, after you have modified
the file, you return your changes to the library with the REPLACE
command. Alternatively, you can cancel the reservation with the
UNRESERVE command.
You can reserve more than one generation of the same element if
concurrent reservations are allowed. If a generation of an
element is reserved by you or another user, or a
generation of the element is under review or has been rejected,
CMS displays the current reservations and review comments, and
prompts whether you want to proceed with the command. If you
type YES, you are added to the list of current reservers. The
transaction is recorded as an unusual occurrence.
If you type NO or press RETURN, no action is taken.
If a version of the output file exists in your default directory
when you issue the RESERVE command, CMS notifies you. A new
version is then created with the next higher version number.
When you retrieve a generation of an element from a CMS library,
CMS restores the file creation and revision times. 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 reserving. If you specify /MERGE, the file placed in your
default directory has the current creation and revision times.
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.
You cannot use /NOCONFIRM to override the prompt generated when
you attempt to reserve a generation of an element that is already
reserved by you or by another user.
3.2 /GENERATION[=generation-expression]
Specifies a particular generation of the element that is to be
reserved. If you omit /GENERATION, CMS reserves 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 including the element history in the file. If
you omit /NOHISTORY, and the retrieved element has the history
attribute, CMS includes the element history in the output file. An
element has the history attribute if the /HISTORY qualifier was
specified 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 reserved (called the retrieved generation).
If you specify the /MERGE qualifier, CMS merges the lines of the
two generations and delivers a single copy of the file 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 /NOCONCURRENT
Specifies that the element cannot be reserved by another user
while you have it reserved. You must replace or unreserve the
element before others can reserve it. By default, CMS allows
concurrent reservations if the element has the concurrent
attribute set.
3.8 /NOTES="string"
Specifies that notes are to be appended to the lines of the
file as it is retrieved by the RESERVE operation. This qualifier
overrides the element's nonotes attribute, if one was established.
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.9 /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 the /NOTES qualifier was specified on the
CREATE ELEMENT or MODIFY ELEMENT command.
3.10 /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.11 /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 in your default directory.
If you reserve 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.12 /NOOUTPUT
Specifies that the generation is to be reserved, but that no
output file is to be created.
3.13 /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 positions 9 and every 8 characters thereafter.)
4 – Examples
(1) CMS> RESERVE FILEIO.BLI
_Remark: fix temporary descriptor bug
%CMS-S-RESERVED, generation 13 of element
DISKX:[PROJECT.CMSLIB]FILEIO.BLI reserved
This command reserves generation 13 of the element FILEIO.BLI.
When the element is replaced, a successor generation is
created.
(2) CMS> RESERVE SYNTAX.PAS
_Remark: add syntax for RECORD declaration
Element SYNTAX.PAS currently reserved by:
(1) JERRYH 1 24-JUL-1988 16:17:45 "implement FOR
loop syntax"
Proceed? [Y/N] (N): YES
%CMS-S-RESERVED, generation 1 of element
DISKX:[PROJECT.CMSLIB]SYNTAX.PAS reserved
This example creates a concurrent reservation for the element
SYNTAX.PAS. Because you type YES in response to the Proceed
prompt, generation 1 of the element is reserved.
(3) CMS> RESERVE COPY.BLI/GENERATION=12/MERGE=11A1
_Remark:merging new I/O routines with library self checking
%CMS-W-MERGECONFLICT, 31 changes successfully merged
with 3 conflicts
%CMS-S-RESERVED, generation 12 of element
DISKX:[PROJECT.CMSLIB]COPY.BLI reserved and merged with
generation 11A1
This command merges generation 11A1 into generation 12 of the
element COPY.BLI and reserves generation 12. The version that
is delivered to the user directory contains the changes from
both generations. Thirty-one changes were successfully merged.
There were three conflicts between the two generations. These
conflicts must be resolved by editing the file.