Returns each specified element reservation to the library and
creates a new generation of the element.
Format:
REPLACE element-expression "remark"
1 – Command Parameters
element-expression
Specifies one or more reserved generations of an element to
be replaced. An element expression can be an element name, a
group name, a wildcard expression, or a list of these separated
by commas. If you specify more than one element (with either a
group name or a wildcard expression), each file indicated by the
element expression must exist in the same directory. When you use
wildcards, CMS creates an input element list based on the list of
element generations that you have reserved.
remark
Specifies a character string to be associated with the newly
created generations, to be logged in the history file with this
command. The remark is enclosed in quotation marks. If no remark
was entered, then the remark from the corresponding reservation is
used for the new generation and the replacement transaction in the
history file.
2 – Description
The REPLACE command transfers a file from your default directory
to the current CMS library, thus creating a new generation. You
can direct CMS to use a file other than the one located in your
default directory by specifying the /INPUT qualifier. After the
reserved generation is replaced, CMS deletes the file used to
create the new generation (and any earlier versions of the file
in the same directory). If you specify either the /KEEP or the
/RESERVE qualifier, CMS does not delete the file. You cannot
replace a reserved generation held by another user unless you hold
BYPASS process privilege or unless you are granted BYPASS access
to the element by an access control entry. After the replace
transaction is completed, the reservation is ended.
By default, the number of the new generation is the number of
its predecessor with the rightmost level number increased by 1.
For example, if you reserved generation 1A1, CMS would create
generation 1A2 when you replaced it. CMS also stores the creation
date and time, the revision date and time, and the file revision
number of the file used to create the new generation. When you
fetch or reserve a generation of an element, CMS restores the
times and file revision number associated with the file used
to create the element generation. You can also display this
information by using the SHOW GENERATION/FULL command.
CMS reports an error if you attempt to create a generation that
is already in the library (see the description of the /VARIANT
qualifier).
The REPLACE command checks for other current reservations and
concurrent replacements of the element, and whether you are
replacing another user's reservation. If any of these situations
occur, CMS prompts whether you want to proceed with the command.
If you type NO or press RETURN, the command is not executed. If
you type YES, CMS executes the command and records the transaction
as an unusual occurrence.
If you have more than one reservation of an element, or if
you are replacing a concurrent reservation made by another user,
(that is, if there is any ambiguity), you must specify the exact
reservation to be replaced. You do this by using either the
/GENERATION qualifier or the /IDENTIFICATON_NUMBER qualifier.
You can use /GENERATION as long as the concurrent reservations are
not on the same generation. If you have more than one concurrent
reservation for the same generation, you must identify the
specific reservation to be replaced. Each reservation is assigned
an identification number. Use the SHOW RESERVATIONS command to
determine the identification number of each reservation. The
identification number appears in parentheses at the beginning
of each line. If you use the /IDENTIFICATION_NUMBER qualifier, you
do not need to also use the /GENERATION qualifier; when both are
used, CMS ignores the /GENERATION qualifier.
If the reference copy attribute is enabled for an element and
REPLACE creates the new generation on the main line of descent,
CMS creates a new reference copy in the reference copy directory
for the element and deletes the old copy from the reference copy
directory.
Replacing an Element with Defined Attributes
If you reserve a generation of an element with an embedded history
and then replace it, the REPLACE command ignores the history; that
is, CMS does not copy the history into your CMS library. If you
add text to the file in or above the history (relative to #B),
or in or below the history (relative to #H), the REPLACE command
issues an error message and the command is not executed.
If you reserve a file with embedded notes and then replace it,
the REPLACE command does not copy the notes to the CMS library.
If, while editing the file, you insert text that looks like an
embedded note, it is deleted when the file is replaced.
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.
The /NOCONFIRM qualifier does not override the confirmation prompt
issued when you make a concurrent replacement or when you replace
another user's reservation.
3.2 /GENERATION=generation-expression
Specifies which reserved generation of the element is to be
replaced. If you have more than one reservation of the same
element generation, you must use the /IDENTIFICATION_NUMBER
qualifier to replace the reservation.
3.3 /IDENTIFICATION_NUMBER=n
Specifies which reservation is to be replaced. This qualifier
is required when you have multiple reservations of the same
generation of an element. This qualifier is also required
when multiple users have reserved the same generation of an
element and you have BYPASS privilege or have been granted
BYPASS access to the element by an access control list entry.
/IDENTIFICATION_NUMBER can be used instead of /GENERATION
when you have multiple reservations. Use the SHOW RESERVATIONS
command to determine the identification number of each
reservation. The identification number appears in
parentheses at the beginning of each line.
3.4 /IF_CHANGED
Specifies that a new generation is to be created only if the
input file is different from the generation that was reserved.
If this qualifier is omitted, a new generation is always created.
3.5 /INPUT[=file-specification]
Specifies a file to be used as input for the replacement
transaction. If you use the /INPUT qualifier but you do not supply
a file specification, CMS searches your current default directory
for a file with the same name as the element specified on the
command line. When you specify /INPUT, CMS deletes the input file
from the specified location after the new generation is created
(unless you specify the /KEEP or /RESERVE qualifier).
CMS must be able to match the input element list with the list of
elements indicated by the element expression parameter. Thus, if
you use wildcards in the /INPUT file specification to generate
more than one input file, you must also use wildcards in the
element expression parameter.
3.6 /INSERT_INTO_CLASS=(class_expression)
Specifies one or more classes into which newly created generations
are to be inserted. The class expression can be a class name, a
wildcard expression, or a list of these separated by commas. If a
list is not used, the parentheses can be omitted.
The new generation of each element replaced is inserted into the
specified classes. If no new generation is created, no insertion
takes place.
This qualifier effectively combines the REPLACE and INSERT
GENERATION commands. It ensures that the new generation is inserted
into the specified class of classes, avoiding the potential problem
of other users updating the library between a REPLACE command and a
subsequent INSERT GENERATION command. It also deals effectively with
variants.
For each of the specified classes, provided there is INSERT access
to the class and it is not set to READ_ONLY, new generations are
always inserted, irrespective of whether or not the class already
contains a generation of the element. Any old generation is removed
from the class before the new generation is inserted. This is like
using the /ALWAYS qualifier in an INSERT GENERATION command.
If other insertion modes, for example /SUPERSEDE, are required,
create a temporary class and use that in the REPLACE command. Then
use the temporary class as the value of the /GENERATION qualifier in
an INSERT GENERATION command with the required mode.
The insert operation takes place in the library where the new
generation was created, so class occlusion does not apply to
classes specified in this qualifier (class occlusion applies to a
class specified in the /GENERATION qualifier).
Any actions specified in access control entries associated with the
INSERT GENERATION command, or with the classes into which
generations are inserted, will be executed after any actions
associated with the REPLACE command or with elements being replaced.
Use of this qualifier requires execute access to the INSERT
GENERATION command.
3.7 /KEEP
Controls whether the file used to create the new element
generation is deleted from your directory. If you omit both /KEEP
and /RESERVE, the files are deleted.
3.8 /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.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 /RESERVE
Controls whether the new generation of the element created by the
replacement is reserved. If you specify the /RESERVE qualifier,
the generation is reserved and the element files are not deleted
from your current default directory. The list of concurrent
replacements is updated as if /RESERVE had been omitted.
3.11 /VARIANT=variant-name
Controls whether a variant generation is created. If you specify
the /VARIANT=variant-name qualifier, the number of the created
generation is the predecessor's number, followed by the variant
name, followed by the number 1.
The Variant Generation Names are limited to
alphabetic characters (A through Z) and underscore
characters with a maximum length of 255 characters.
If two or more users have concurrently reserved the same element
generation, the replaced generations cannot be on the same line of
descent. Thus, one can be replaced as a main line generation and
the rest must be replaced as variants.
4 – Example
CMS> REPLACE FILEIO.BLI
_Remark: descriptor bug fixed
%CMS-S-GENCREATED, generation 14 of element
DISKX:[PROJECT.CMSLIB]FILEIO.BLI created
This command creates a new generation on the main line of
descent of element FILEIO.BLI.