Format
{COLLECTION }
{FIELD }
RESERVE {RECORD } [qualifier] ... element-name ,...
{FILE_ELEMENT type-name}
{GENERIC type-name }
[AUDIT IS /*text*/]
1 – Parameters
1.1 – type-name
Specifies the type of the file or generic element you are
reserving.
1.2 – element-name
Specifies the element you are reserving. You can substitute
an asterisk (*) wildcard character for this parameter. If the
element is uncontrolled, you must reserve the highest version.
1.3 – text
Adds information to the history list entry. Valid delimiters are
/* */ or double quotation marks (" ").
You can use Japanese to document comments in the AUDIT clause for
a field. To do this, use the SET CHARACTER_SET command, and set
the character_set of the session to DEC_KANJI.
2 – Qualifiers
2.1 /BRANCH
Format options:
/BRANCH=branchname
/NOBRANCH (default)
Specifies whether CDO creates a version on a new branch line or
on an existing line of descent. The element must be controlled to
use the /BRANCH qualifier.
2.2 /CLOSURE
Format options:
/CLOSURE=keyword
/NOCLOSURE (default)
Specifies whether CDO reserves additional elements. A CLOSURE
operation fails if any element is a child of an element outside
the area defined by the CLOSURE keyword.
CLOSURE takes one of the following keywords:
CLOSURE
Keyword Behavior
TO_BOTH Reserves the element specified and all owners and
members.
TO_BOTTOM Reserves the element specified and all members.
TO_CLOSURE Reserves the element specified, all owners, and any
element under the top collection that depends on the
element specified.
TO_TOP Reserves the element specified and all owners.
In most cases, you can specify the TO_BOTH, TO_TOP, or TO_BOTTOM
keywords. The TO_CLOSURE keyword is useful when you are working
with the source and derived files common in system building
applications.
If you specify TO_BOTH, TO_CLOSURE, or TO_TOP, CDO ignores owners
of the top collection.
2.3 /LOG
Format options:
/LOG
/NOLOG (default)
Specifies whether CDO displays text identifying each element as
the element is reserved.
2.4 /OUTPUT
Format options:
/OUTPUT (default)
/NOOUTPUT
The /NOOUTPUT qualifier lets you reserve a FILE_ELEMENT of type
MCS_BINARY without copying the file into the current context
directory. This capability is useful for using the repository
to manage binary files that are superseded each time they are
reserved. It lets you reserve the file element without incurrring
the processing time to create the binary file in the context
directory.
If you use the /NOOUTPUT qualifier in a RESERVE command, you
must update the context directory with the latest binary file to
be replaced. If you do not update the current context directory
with a new file, the REPLACE command will fail. When the REPLACE
command fails, CDO displays an error message containing the
full directory specification of the reserved file that CDO was
attempting to replace. Refer to this error message and place a
new copy of the specified file in the context directory.
If you reserve a file with the /NOOUTPUT qualifier, CDO does not
create the file in the context directory. If you manually place
a file in the context directory and then issue the UNRESERVE
command, the reserved file is unreserved and any copies of the
file in the context directory are deleted. This occurs even if
you manually superseded any files in the context directory.
NOTE
If you use the VERIFY/FIX command on a repository, any
files reserved with the /NOOUTPUT qualifier are created
in the context directory, because the VERIFY command cannot
find reserved files. This performance cost has always been
associated with the VERIFY/FIX command when it cannot find
reserved files.
3 – Description
The RESERVE command checks out a version of a controlled element.
A controlled element is one of the following:
o An element you created using Oracle CDD/Repository inside a
context
o An element you have controlled with the CONSTRAIN command
You must have a context set to issue the RESERVE command.
If you are issuing the RESERVE command in a distributed
environment, you must issue the ENTER command before issuing
the RESERVE command.
The RESERVE command creates a copy of the immutable version that
is stored in the base partition associated with your context.
This copy is called a ghost; it is reserved to your context and
you can modify it.
In general, the ghost has a version number that is one number
higher than that of the original version in the partition. For
example, if you reserve PRODUCT(1), the ghost of this version is
called PRODUCT(2).
If, however, you specify the creation of a parallel line of
development (or branch), the ghost becomes the first version
in that branch line. For example, if you reserve PRODUCT(2) with
a /BRANCH=AUDITOR qualifier, the ghost copy of this version is
called PRODUCT(2:AUDITOR:1).
If you specify the /BRANCH qualifier, you can reserve any version
of a controlled element in a line of descent that is available
for reservation. If an element is uncontrolled, an error occurs
if you attempt to reserve any version but the latest version in a
line of descent.
An error occurs if you issue the /BRANCH qualifier with a branch
name already in use.
An error occurs if you attempt to reserve a child without
previously reserving its owners. Use the /CLOSURE qualifier to
reserve as many elements as necessary.
An error occurs if you attempt to reserve a version of an
uncontrolled element that has already been reserved. An element
can have only one outstanding reservation.
When you finish modifying your working copy of a version, you use
the REPLACE command to check in the new version to the partition
or the repository.
If you decide to discard the changes you have made to your
working copy, use the UNRESERVE command to cancel your
reservation and destroy your copy.
If you decide to merge a branch line that you have created back
into the main line of descent, use the MERGE command.
When reserve is invoked with a branch name specified, the new
ghost version is created with a name that incorporates the branch
name and is properly linked to the element from which the branch
line originates.
If the target of a reserve notice is involved in one or more
correspondence relationships, those relationships may be
propagated to the new version.
4 – Examples
1.CDO> RESERVE FIELD /CLOSURE=TO_TOP FIRST_NAME
In this example, the RESERVE command with the /CLOSURE=TO_TOP
qualifier reserves the FIRST_NAME field element and all owners
to the top collection.
2.CDO> RESERVE FIELD /CLOSURE=TO_TOP /BRANCH=AUDITOR PRODUCT_NUMBER
In this example, the RESERVE command with the /CLOSURE=TO_TOP
qualifier reserves all elements on the path between the top
collection and field PRODUCT_NUMBER; the /BRANCH qualifier
creates a branch line AUDITOR descending from PRODUCT_NUMBER.
3.CDO> RESERVE FIELD /CLOSURE=TO_TOP PRODUCT_NUMBER(1:AUDITOR:1)
In this example, the RESERVE command reserves the first version
in the AUDITOR branch line.
4.SYSTEM collection
SOURCE_FILES collection
FIRST_FILE.C
SECOND_FILE.C
INC.H
DERIVED_FILES collection
FIRST_FILE.OBJ
SECOND_FILE.OBJ
IMAGE_FILE.EXE
In this example, the code shows a collection hierarchy with
SYSTEM defined as the top collection. The dependencies in
SYSTEM are as follows:
o IMAGE_FILE.EXE depends on FIRST_FILE.OBJ and SECOND_
FILE.OBJ.
o FIRST_FILE.OBJ depends on FIRST_FILE.C and INC.H.
o SECOND_FILE.OBJ depends on SECOND_FILE.C and INC.H.
5.CDO> RESERVE FILE_ELEMENT MCS_BINARY /CLOSURE=TO_CLOSURE INC.H
In this example, the RESERVE command reserves the following
elements:
o Element INC.H
o Owners of the element specified, SOURCE_FILES and SYSTEM
o Elements that directly or indirectly depend on the element,
FIRST_FILE.OBJ, SECOND_FILE.OBJ, IMAGE_FILE.EXE
6.CDO> RESERVE FILE_ELEMENT MCS_BINARY /NOOUTPUT "/ISAM_FILE.DAT"
In this example, ISAM_FILE.DAT is reserved using the /NOOUTPUT
qualifier, but the file is not copied into the current context
directory.