UPDATE CMS User Area command
Use the UPDATE command to modify program source files. The UPDATE command
accepts a source input file and one or more files containing UPDATE control
statements, updated source records, and requisite information; then it creates
an updated source output file, an update log file indicating what changes, if
any, were made, and an update record file if more than a single update file is
applied to the input file. The format of the UPDATE command is:
+----------+------------------------------------------------------------------+
| Update | fn1 [ASSEMBLE|ft1 [A1|fm1 [fn2 [ft2 [fm2]]] [(options...[)]] |
| | options: |
| | NOREP|REP SEQ8|NOSEQ8 NOINC|INC NOCTL|CTL |
| | NOSTK|STK TERM|NOTERM DISK|PRINT STOR|NOSTOR |
+----------+------------------------------------------------------------------+
where:
fn1 [ft1 [fm1]]
is the file identifier of the source input file. The file must
consist of 80-character card image records with sequence fields in
positions 73 through 80 or 76 through 80. If the filetype or filemode
are omitted, ASSEMBLE and A1 are assumed, respectively.
fn2 [ft2 [fm2]]
is the file identifier of the update file. If the NOCTL option is in
effect, this file must contain UPDATE control statements and updated
source records. The default file identifier is fn1 UPDATE A1. If the
CTL option is specified, this file must be a control file that lists
the update files to be applied; the default file identifier is fn1
CNTRL A1.
Options:
REP creates an output source file with the same filename as the input
source file. If the output file is placed on the same disk as the
input file, the input file is erased.
NOREP retains the old file in its original form, and assigns a different
filename to the new file, consisting of a dollar sign ($) plus the
first seven characters of the input filename (fn1).
SEQ8 specifies that the entire sequence field (columns 73 through 80)
contains an eight-digit sequence number on every record of source
input.
NOSEQ8 specifies that columns 73-75 contain a three-character label field,
and that the sequence number is a five-digit value in columns 76-80.
INC increments sequence numbers in columns 73 through 80 in each record
inserted into the updated output file, according to specifications in
UPDATE control statements.
NOINC puts asterisks (********) in the sequence number field of each updated
record inserted from the update file.
CTL specifies that fn2, ft2, and fm2 describe an update control file for
applying multiple update files to the source input file.
Note: The CTL option implies the INC option.
NOCTL specifies that a single update file is to be applied to the source
input file.
STK stacks information from the control file in the CMS console stack.
STK is valid only if the CTL option is also specified and is useful
only when the UPDATE command is executed in an EXEC procedure.
NOSTK does not stack control file information in the console stack.
TERM displays warning messages at the terminal whenever a sequence or
update control card error is discovered. (Such warning messages
appear in the update log, whether they are displayed at the terminal
or not.)
NOTERM suppresses the display of warning messages at the terminal. However,
error messages that terminate the entire update procedure are
displayed at the terminal.
DISK places the update log file on disk. This file has a file identifier
"fn UPDLOG," where "fn" is the filename of the file being updated.
PRINT prints the update log file directly on the virtual printer.
STOR specifies that the source input file is to be read into storage and
the updates performed in storage prior to placing the updated source
file on disk. This option is meaningful only when used with the CTL
option since the benefit of increased processing speed is realized
when processing multiple updates. STOR is the default when CTL is
specified.
NOSTOR specifies that no updating is to take place in storage. NOSTOR is the
default when single updates are being applied (CTL is omitted from the
command line).
Update Control Statements
The UPDATE control statements let you insert, delete, and replace source
records, as well as resequence the output file.
All references to the sequence field of an input record refer to the numeric
data in columns 73-80 of the source record, or columns 76-80 if NOSEQ8 is
specified. Leading zeros in sequence fields are not required. If no sequence
numbers exist in an input file, a preliminary UPDATE with only the './ S'
control statement can be used to establish file sequencing.
Sequence numbers are checked while updates are being applied; an error
condition results if any sequence errors occur in the update control
statements, and warnings are issued if an error is detected in the sequencing
of the input file. Any source input records with a sequence field of eight
blanks are skipped, without any indication of a sequence error. Such records
may be replaced or deleted only if they occur within a range of records that
are being replaced or deleted entirely and if that range has limits with valid
sequence numbers. There is no means provided for specifying a sequence field
of blanks on an UPDATE control statement.
Control Statement Formats:
All UPDATE control statements are identified by the characters './' in columns
1 and 2 of the 80-byte record, followed by one or more blanks and additional,
blank-delimited fields. Control statement data must not extend beyond column
50.
SEQUENCE Control Statement
This statement resequences the updated source output file in columns 73-80 (if
SEQ8 is specified), or in columns 76-80 with the label placed in columns 73-75
(if NOSEQ8 is specified). The format of the SEQUENCE control statement is:
+-----------------------------------------------------------------------------+
| ./ S [seqstrt [seqincr [label]]] |
+-----------------------------------------------------------------------------+
where:
seqstrt is a 1- to 8-digit numeric field specifying the first decimal sequence
number to be used. The default value is 1000 if SEQ8 is specified and
10 if NOSEQ8 is specified.
seqincr is a 1- to 8-digit numeric field specifying the decimal increment for
resequencing the output file. The default is the "seqstrt" value.
label is a 3-character field to be duplicated in columns 73-75 of each
source record if NOSEQ8 is specified. The default value is the first
3 characters of the input filename (fn1).
If you use the SEQUENCE statement, it must be the first statement in the update
file. If any valid control statement precedes it, the resequence operation is
suppressed.
When the sequence control statement is the first statement processed, the
sequence numbers in the source file are checked and warning message DMSUPD210W
is issued for any errors. If the sequence control statement is processed after
updates have been applied, no warning messages will be issued.
Each source record is resequenced in columns 73-80 as it is written onto the
output file, including unchanged records from the source file and records
inserted from the update file.
INSERT Control Statement
This statement inserts all records following it, up to the next control
statement, into the output file. The format of the INSERT control statement
is:
+-----------------------------------------------------------------------------+
| ./ I seqno [$ [seqstrt [seqincr]]] |
+-----------------------------------------------------------------------------+
where:
seqno is the sequence number of the record in the source input file
following which new records are to be added.
$ is an optional delimiter indicating that the inserted records are to
be sequenced by increments.
seqstrt is a 1- to 8-digit numeric field specifying the first decimal number
to be used for sequencing the inserted records.
seqincr is a 1- to 8-digit numeric field specifying the decimal increment for
sequencing the inserted records.
All records following the "./ I" statement, up to the next control statement,
are inserted in the output file following the record identified by the "seqno"
field. If the NOINC option is specified, each inserted record is identified
with asterisks (********) in columns 73-80. If either the INC or CTL option is
specified, the records are inserted unchanged in the output file, or they are
sequenced according to the "seqstrt" and "seqincr" fields, if the dollar sign
($) key is specified.
The default sequence increment, if the dollar sign is included, is determined
by using one tenth of the least significant, nonzero digit in the seqno field,
with a maximum of 100. The default seqstrt is computed as seqno plus the
default seqincr. For example, the control statement:
./ I 2600 $ 2610
causes the inserted records to be sequenced XXX02610, XXX02620, and so forth
(NOSEQ8 assumed here). For the control statement:
./ I 240000 $
the defaulted seqincr is the maximum, 100, and the starting sequence number is
240100. SEQ8 is assumed, so the inserted records are sequenced 00240100,
00240200, and so forth.
If either INC or CTL is specified but the dollar sign is not included, whatever
sequence number appears on the inserted records in the update file is included
in the output file.
DELETE Control Statement
This statement deletes one or more records from the source file. The format of
the DELETE control statement is:
+-----------------------------------------------------------------------------+
| ./ D seqno1 [seqno2] [$] |
+-----------------------------------------------------------------------------+
where:
seqno1 is the sequence number identifying the first or only record to be
deleted.
seqno2 is the sequence number of the last record to be deleted.
$ is an optional delimiter indicating the end of the control fields.
All records of the input file, beginning at seqno1, up to and including the
seqno2 record, are deleted from the output file. If the seqno2 field is
omitted, only a single record is deleted.
REPLACE Control Statement
This statement replaces one or more input records with updated records from the
update file. The format of the REPLACE control statement is:
+-----------------------------------------------------------------------------+
| ./ R seqno1 [seqno2] [$ [seqstrt [seqincr]]] |
+-----------------------------------------------------------------------------+
where:
seqno1 is the sequence number of the first input record to be replaced.
seqno2 is the sequence number of the last record to be replaced.
$ is an optional delimiter key indicating that the substituted records
are to be sequenced incrementally.
seqstrt is a 1- to 8-digit numeric field specifying the first decimal number
to be used for sequencing the substituted records.
seqincr is a 1- to 8-digit numeric field specifying the decimal increment for
sequencing the substituted records.
All records of the input file, beginning with the seqno1 record, up to and
including the seqno2 record, are replaced in the output file by the records
following the "./ R" statement in the update file, up to the next control
statement. As with the "./ D" (delete) function, if the seqno2 field is
omitted, only a single record is replaced, but it may be replaced by more than
a single inserted record. The "./ R" (replace) function is performed as a
delete followed by an insert: thus, the number of statements inserted need not
match the number deleted. The dollar sign ($), seqstrt, and seqincr processing
is identical to that for the insert function.
COMMENT Statement
This statement allows inserting supplemental information that the user may
want. Note that the COMMENT statement is treated as a control statement when
it appears within a sequence of records to be applied in an update. The format
of the COMMENT statement is:
+-----------------------------------------------------------------------------+
| ./ * [comment] |
+-----------------------------------------------------------------------------+
where:
* indicates that this is a comment statement. and is to be ignored,
except that it is copied into the log file.
Summary of Files Used by the UPDATE Command
The following discussion shows input and output files used by the UPDATE
command for a:
o Single-level update.
o Multilevel update.
o Multilevel update with an auxiliary control file.
Disk Mode of Output Files: The following steps are taken to determine the disk
upon which the output files are to be placed (the search stops as soon as one
of the following steps is successful):
1. If the OUTMODE option is specified, then the output files are placed on the
disk specified, if it is a read/write disk. If the specified disk is
accessed as read/only extension, then the following message is displayed:
DMSUPD037E DISK 'mode' IS READ/ONLY
2. If the disk on which the original source file resides is read/write, then
the output files are placed on that disk.
3. If that disk is a read-only extension of a read/write disk, then the output
files are placed on that particular read/write disk.
4. If neither of the other steps is successful, the output files are placed on
the primary read/write disk (the A-disk).
Single-Level Update
fn ASSEMBLE ---> update fn ---> $fn ASSEMBLE
fn UPDATE fn UPDLOG
In the above diagram, fn ASSEMBLE is the source input file. fn UPDATE contains
UPDATE control statements and updated source input records. $fn ASSEMBLE is
the updated source file, incorporating changes, additions, and deletions
specified in the update file. The output filetype is always the same as the
filetype of the input file. These default filetypes and filemodes can be
overridden on the command line; for example:
update testprog cobol b fix cobol b (rep
results in a source file TESTPROG COBOL B being updated with control statements
contained in the file FIX COBOL B. The output file replaces the existing
TESTPROG COBOL B. fn UPDLOG contains a record of updates applied. If you do
not want this file written on disk, specify the PRINT option.
Multilevel Update
fn ASSEMBLE ---> update fn (ctl ---> $fn ASSEMBLE
fn CNTRL fn UPDLOG
fn UPDTABC fn UPDATES
fn UPDTXYZ
In the above diagram, fn ASSEMBLE is the source input file. fn CNTRL is the
control file that lists updates to be applied to the source file. These
default filetypes and filemodes can be overridden on the command line; for
example:
update acct pliopt a test cntrl a (ctl
results in the file TEST CNTRL being used by the UPDATE command to locate the
update files for ACCT PLIOPT.
fn UPDTABC and fn UPDTXYZ are update files containing UPDATE control statements
and new source records. These files can also contain PREREQ, CO-REQ, and
IF-REQ comments that specify dependencies for applying the updates. The update
files must have filenames that are the same as the source input file. The
first four characters of the filetype must be 'UPDT'. The UPDATE command
searches all accessed disks to locate the update files.
$fn ASSEMBLE is the updated source file, incorporating changes, additions, and
deletions specified in the update files. The filetype is always the same as
the filetype of the source input file.
fn UPDLOG contains a record of updates applied. If you do not want this file
written on disk, specify the PRINT option. fn UPDATES summarizes the updates
applied to the source file and includes all requisite information from the
update files. The CONTROL FILE (fn CNTRL) may not contain UPDATE control
statements. It may only list the filetypes of the files that contain UPDATE
control statements. This control file contains the records:
TEXT MACS CMSLIB
TWO UPDTABC
ONE UPDTXYZ
where UPDTABC and UPDTXYZ are the filetypes of the update files. The UPDATE
command applies these updates to the source file beginning with the last record
in the control file. Thus, the updates in fn UPDTXYZ are applied before the
updates in fn UPDTABC.
When you create update files whose filetypes begin with 'UPDT', you may omit
these characters when you list the updates in the control file; thus, the CNTRL
file may be written:
TEXT MACS CMSLIB
TWO ABC
ONE XYZ
TEXT, TWO, ONE: The first column of the control file consists of an update
level identifier, which may be from one to five characters long. These
identifiers are used by VM/SP updating procedures, like the VMFASM EXEC, to
locate and identify text decks produced by multilevel updates.
MACS: The first record in the control file must be a MACS record that contains
an update level identifier (TEXT) and, optionally, lists up to 29 macro library
(MACLIB) filenames (subject to the record length of the line). The length of
the MACS record may not exceed 80, the record length of the control file.
UPDATE uses the information provided in the MACS card and the update level
identifier only when the STK option is specified. This information is,
however, required in the CNTRL file.
Multilevel Update with Auxiliary Control File
fn ASSEMBLE ---> update fn (ctl ---> $fn ASSEMBLE
fn CNTRL fn UPDLOG
fn UPDTABC fn UPDATES
fn UPDTXYZ
fn AUXLIST
fn FIX01
fn FIX02
fn ASSEMBLE, fn CNTRL, fn UPDTABC, fn UPDTXYZ, $fn ASSEMBLE, fn UPDLOG, and fn
UPDATES are used as described, for "Multilevel Update," except that the CNTRL
file contains:
TEXT MACS CMSLIB
TWO UPDTABC
ONE UPDTXYZ
TEXT AUXLIST
AUX in the filetype AUXLIST indicates that this is the filetype of an auxiliary
control file that contains an additional list of updates. The first three
characters of the filetype of an auxiliary control file must be "AUX"; the
remaining character(s) (to a maximum of 5) may be anything. The filename must
be the same as the source input file. An auxiliary file may also be specified
as:
xxxxx AUX
in the control file. For example, the record:
FIX TEST AUX
identifies the auxiliary file fn AUXTEST.
Note that if you give an auxiliary control file the filetype AUXPTF or an
update level identifier of AUX, the UPDATE command assumes that it is a simple
update file and does not treat it as an auxiliary file.
Preferred AUX File
A preferred AUX file may be specified. A preferred AUX file contains the
version of an update that applies to your version of the source file. (There
may be more than one version of the same update if there is more than one
version of the source file. For example, you need one version for the source
file that has a system extension licensed program installed, and you need
another version for the source file that does not have a licensed program
installed.)
When you specify an auxiliary control file, you can specify more than one
filetype. The first filetype indicates a file that UPDATE uses only on one
condition: the files that the second and subsequent filetypes indicate do not
exist. If they do exist, this AUX file entry is ignored and no updating is
done. The files that the second and subsequent filetypes indicate are
preferred because, if they exist, UPDATE does not use the file that the first
filetype indicates. For example, assume that the file 'fn ASSEMBLE' does
exist. The control file MYMODS CNTRL:
TEXT MACS MYMACS CMSLIB OSMACRO
MY2 AUXTEST
MY1 AUXMINE AUXTEST
and the command:
UPDATE fn ASSEMBLE * MYMODS CNTRL (CTL
would result in UPDATE finding the preferred auxiliary control file 'fn
AUXTEST', and therefore not using 'fn AUXMINE' to update 'fn ASSEMBLE'. UPDATE
would then proceed to the MY2 AUXTEST entry and update 'fn ASSEMBLE' with the
updates listed in 'fn AUXTEST.' It is assumed that AUXTEST and AUXMINE list
similar but mutually exclusive updates.
The search for a "preferred" auxfile will continue until one is found or until
the token is an invalid filetype; that is, less than four or more than eight
characters. This token and the remainder of the line are considered a comment.
fn FIX01 and fn FIX02 are update files containing UPDATE control statements and
new source records to be incorporated into the input file. These files can
also contain PREREQ, CO-REQ, and IF-REQ comments that specify dependencies for
applying the updates. When update files are listed in an auxiliary control
file, they can have any filetype you choose but the filename must be the same
as the source input file. The update files, as well as the AUX file, may be on
any accessed disk. These are indicated in fn AUXLIST as follows:
FIX02
FIX01
The updates are applied from the bottom of the auxiliary file. Thus, fn FIX01
is applied to the source file before fn FIX02. Since the auxiliary file is
listed at the bottom of the control file, these updates are applied before
UPDTXYZ and UPDTABC.
Additional Control File Records
In addition to the MACS record, the filetypes of update (UPDT) files, and the
filetypes of auxiliary control (AUX) files, a control file may also contain:
o Comments. These records begin with an asterisk (*) in column 1. Comments
are also valid in AUX files.
o PTF records. If the characters PTF appear in the update level identifier
field, the UPDATE command expects the second field to contain the filetype
of an update file. The filetype may be anything; the filename must be the
same as the source input file.
o Update level identifiers not associated with update files.
The following example of a control file shows all the valid types of
records:
* Example of a control file
ABC MACS MYLIB
TEXT
004 UPDTABC
003 XYZ
002 AUXLIST1
001 LIST2 AUX
PTF TESTFIX
The STK Option
The STK (stack) option is valid only with the CTL option and is meaningful only
when the UPDATE command is invoked within an EXEC procedure.
When the STK option is specified, UPDATE stacks the following data lines in the
console stack:
first line: * update level identifier
second line: * library list from MACS record
The update level identifier is the identifier of the most recent update file
that was found and applied. For example, if a control file contains
TEXT MACS CMSLIB OSMACRO TESTMAC
OFA UPDTOFA
PFA UPDTOFA
and the UPDATE command appears in an EXEC as follows:
UPDATE SAMPLE (CTL STK
&READ VARS &STAR &TEXT
&READ VARS &STAR &LIB1 &LIB2 &LIB3 &LIB4
then the variable symbols set by the &READ VARS statements have the following
values if the file SAMPLE UPDTOFA is found and applied to the file SAMPLE
ASSEMBLE:
Symbol Value &STAR * &TEXT OFA &LIB1 CMSLIB &LIB2
OSMACRO &LIB3 TESTMAC &LIB4 null
The library list may be useful to establish macro libraries in a subsequent
GLOBAL command within the EXEC procedure. If no update files are found, UPDATE
stacks the update level identifier on the MACS record.
Responses:
FILE 'fn ft fm,' REC #n = update control statement
This message is displayed when the TERM option is specified and an error is
detected in an update file. It identifies the file and record number where
the error is found.
DMSUPD177I WARNING MESSAGES ISSUED (SEVERITY = nn). ['REP' OPTION IGNORED]
Warning messages were issued during the updating process. The severity
shown in the error message in the "nn" field is the highest of the return
codes associated with the warning messages that were generated during the
updating process. The warning return codes have the following meanings:
RC = 4 - Sequence errors were detected in the original source file being
updated.
RC = 8 - Sequence errors, which did not previously exist in the source file
being updated, were introduced in the output file during the updating
process.
RC = 12 - Any other warning error detected during the updating process.
Such errors include invalid update file control statements and missing
update or PTF files.
The severity value is passed back as the return code from the UPDATE
command. In addition, if the REP option is specified in the command line,
then it is ignored, and the updated source file has the fileid "$fn1 ft1,"
as if the REP option was not specified.
DMSUPD178I UPDATING ['fn ft fm'] WITH 'fn ft fm'
The specified update file is being applied to the source file. This message
appears only if the CTL option is specified in the command line. The
updating process continues.
DMSUPD304I UPDATE PROCESSING WILL BE DONE USING DISK
An insufficient amount of virtual storage was available to perform the
updating in virtual storage, so a CMS disk must be used. This message is
displayed only if NOSTOR was specified in the UPDATE command line.
DMSUPD180W MISSING PTF FILE fn ft fm RC=12
In the event that the user receives this message during the update process,
the message MISSING PTF FILE 'fn ft fm' will appear in the update log
associated with the program being updated.