Creates an output file that contains an annotated listing of the
changes made to each specified element generation and places it
in your current default directory or a specified directory.
Format:
ANNOTATE element-expression
1 – Command Parameters
element-expression
Specifies one or more elements. 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 a group name, CMS
annotates each element in the group. If you use wildcards, CMS
produces one annotated listing file for each matching element. By
default, the most recent generation of an element on the main line
of descent is annotated.
2 – Description
The ANNOTATE command documents the development of an element. This
command creates an output file that contains an annotated listing;
by default, the file name is the same as the element name and the
file type is .ANN. The annotated listing file contains two parts:
o A history
o A source file listing
The history includes the generation number, date, time, user,
and remark associated with each generation of the element (and
other file-related information when you use the /FULL qualifier).
The generations are listed in reverse chronological order. The
generation numbers of the specified generation and its ancestors
are marked with an asterisk (*).
The source file listing contains all the lines inserted or
modified from generation 1 to the specified generation. The
listing does not show lines deleted from the file. CMS inserts
consecutive line numbers in the listing unless editor-assigned
line numbers already exist. (The line numbers start with 1 for the
first line and increase by 1 for each line.) The generation field
starts at the first character position of each line. It contains
the generation number of the most recent generation in which the
line was inserted or modified. The generation field is blank if a
line is unchanged since generation 1.
3 – Qualifiers
3.1 /APPEND
Controls whether CMS appends the history and source file listing
to an existing file, or creates a new file. If you specify /APPEND
and the output file does not exist, CMS creates a new file. If you
do not provide an output file specification (see the description
for /OUTPUT), CMS searches your default directory for a file with
the element file name and the file type .ANN.
3.2 /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.3 /FORMAT=(data-format,data-partition)
Controls whether the history and source file listing is formatted,
and specifies the type of formatting. You can specify one or both
formatting parameters in any order.
data-format
Specifies the type of format. Possible values for data formats
include: ASCII (Default), DECIMAL, HEXADECIMAL, and OCTAL.
data-partition
Specifies the type of data partition. Possible values for data
partitions include: BYTE, LONGWORD, RECORDS (Default), and WORD.
3.4 /FULL
Directs CMS to include the following information about the file
used to create each generation:
o Creation time
o Revision time
o Revision number
o Record format
o Record attributes
CMS also indicates deleted lines in the source listing. Each
set of one or more deleted lines is identified by a count of the
deleted lines.
3.5 /GENERATION[=generation-expression]
Specifies a particular generation of the element to be annotated.
If you omit /GENERATION, CMS annotates the most recent generation
on the main line of descent.
The history contains a description of every generation of the
element, including those created after the specified generation.
(Generations created after the specified generation are not marked
with an asterisk.)
3.6 /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.7 /MERGE=generation-expression
Combines two generations of an element and creates a single
file that contains the annotated listing. The parameter on the
/MERGE qualifier specifies the generation that is merged into the
retrieved generation. This command creates a file that contains
the text common to both generations and the changes made to both
generations. When changes that are not identical are made in
the same position of the common ancestor, the changes from both
generations are included in the resulting file and are marked as a
conflict. By default, generations are not merged.
3.8 /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.9 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file. CMS creates a
new file if you do not specify /APPEND. If you omit the /OUTPUT
qualifier (or if you specify /OUTPUT but do not provide a file
specification), CMS creates a file with the element file name and
the file type .ANN. Wildcards are allowed.
If you annotate 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.
4 – Example
CMS> ANNOTATE TIMECVT.BAS/GENERATION=3
%CMS-S-ANNOTATED, element DISKX:[WORK.CMSLIB]TIMECVT.BAS annotated
This command produces a file named TIMECVT.ANN, which contains
the annotated listing of generation 3 of TIMECVT.BAS. The
contents of TIMECVT.ANN are as follows:
Annotated listing for element TIMECVT.BAS in CMS Library
DISKX:[WORK.CMSLIB] 25-APR-1988 15:50:29
4 15-APR-1988 10:01:55 JAMES "additional error checks"
*3 12-APR-1988 15:49:01 JAMES "add check for invalid delta time"
*2 27-MAR-1988 12:39:58 JAMES "jp - fixed length string required"
*1 25-MAR-1988 15:37:11 JAMES "time conversion program"
Annotated listing for element TIMECVT.BAS in CMS Library
DISKX:[WORK.CMSLIB] 25-APR-1988 15:50:29
1 10 rem Program to compute an absolute time given the
present time
2 rem and a delta time. The result is written to a file.
3
4 20 OPTION TYPE = EXPLICIT
5 DECLARE STRING DELTA_TIME
2 6 MAP (STRING_LEN) STRING ASC_TIME = 80
7 DECLARE LONG RETCODE
8 DIM LONG BINARY_DELTA(1)
9 DIM LONG NOW(1)
10 DIM LONG BINARY_CVT_TIME(1)
11
12 100 EXTERNAL LONG CONSTANT SS$_NORMAL
3 13 EXTERNAL LONG CONSTANT SS$_IVTIME
14 EXTERNAL LONG FUNCTION LIB$ADDX
15 EXTERNAL LONG FUNCTION LIB$SUBX
16 EXTERNAL LONG FUNCTION LIB$INT_OVER
17 EXTERNAL INTEGER FUNCTION SYS$BINTIM (STRING
BY DESC, LONG BY REF)
18 EXTERNAL INTEGER FUNCTION SYS$GETTIM (LONG
BY REF)
19 EXTERNAL INTEGER FUNCTION SYS$ASCTIM (LONG
BY REF, STRING BY DESC, &
20 LONG BY REF,
LONG BY REF)
21 150 LET RETCODE = LIB$INT_OVER(0)
22 PRINT "Input delta time"
23 INPUT DELTA_TIME
24 LET RETCODE = SYS$BINTIM ( DELTA_TIME,
BINARY_DELTA(0) )
3 25 175 IF (RETCODE = SS$_NORMAL) THEN GOTO 200
3 26 ELSE IF RETCODE = SS$_IVTIME THEN &
3 27 PRINT ,"INVALID TIME"
3 28 GOTO DONE
3 29 END IF
3 30 END IF
3 31 200 LET retcode = SYS$GETTIM(NOW(0))
3 32 IF (VAL( DELTA_TIME ) > 0 ) THEN &
33 retcode=LIB$ADDX(NOW(0),BINARY_DELTA (0) ,
BINARY_CVT_TIME(0))
34 END IF
35 LET retcode = SYS$ASCTIM(,ASC_TIME,BINARY_
CVT_TIME(0),)
36 OPEN "TIME.TMP" FOR OUTPUT AS FILE #1
37 PRINT #1,ASC_TIME
38 CLOSE #1
39 32767 Done: END
40
The element's history appears at the beginning of the
file TIMECVT.ANN. The history lists the records of the
transactions that created each of the four generations.
However, because the third generation was annotated (ANNOTATE
TIMECVT.BAS/GENERATION=3), changes made after generation 3
are not shown in the annotated listing. Generation 3 and its
ancestors are marked with an asterisk in the history.
The source file listing shows each line of the file, including
line numbers. The numbers farthest to the left are the
generation numbers in which the line was most recently inserted
or modified; the lines with no generation numbers have not
changed since generation 1. The next column of numbers is
assigned by CMS. The third column of numbers is included in
the program itself.