UPDATE

Update or Control file

Options

Notes:

¹ The defaults you receive appear above the line in the Options fragment.
² You can enter Options in any order between the parentheses.
³ Update or control file is fn1 UPDATE A1 if NOCTL is specified, fn1 CNTRL A1 if CTL is specified.
⁴ CTL implies INC.
⁵ STK is only valid when CTL is specified and when UPDATE is entered from EXEC.
⁶ STOR is the default when CTL is specified.

Authorization

General User

Purpose

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.

Operands

fn1 ft1 fm1: is the file identifier of the source input file. The file must consist of fixed-format records with sequence fields in the last eight columns (or the last five columns). If you do not specify file type or file mode, a default of ASSEMBLE A1 is assumed. It cannot be an empty file.
fn2 ft2 fm2: is the file identifier of the update file or control file. If you specify the NOCTL option, this file must be an update file that lists the updates you choose to apply. The update file can contain requisite information (PREREQ, CO-REQ, and IF-REQ comments) for applying the updates. 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. A control file cannot be an empty file.

Options

REP: creates an output source file with the same file name as the input source file. If the output file is placed on the same disk or directory as the input file, the input file is erased.
NOREP: retains the old file in its original form, and assigns a different file name to the new file, consisting of a dollar sign ($) plus the first seven characters of the input file name (fn1). This is the default.
SEQ8: specifies the entire sequence field (the last eight columns of the file) contains an eight-digit sequence number on every record of source input. This is the default.
NOSEQ8: specifies the last eight columns of the file contain a three-character label field, followed by a five-digit sequence number.
Note: The CMS editor, by default, sequences source files with five-digit sequence numbers.
INC: increments sequence numbers in the last eight columns 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. This is the default.
CTL: specifies fn2 ft2 fm2 describes an update control file for applying multiple update files to the source input file.
NOCTL: specifies a single update file is to be applied to the source input file. This is the default.
OUTMODE fm: specifies the files created by the UPDATE command will be written onto the disk or directory accessed as fm. You must access the disk or directory as a read/write, otherwise the UPDATE command stops processing. If you do not specify a file mode number when you specify fm, the file mode number defaults to 1. If you do not specify OUTMODE, the files are put onto the disk or directory as outlined in in File Mode of Output Files.
STK: stacks information from the control file in the CMS console stack. STK is valid only if you specify the CTL option, and is valid only when you issue the UPDATE command from an EXEC procedure.
NOSTK: does not stack control file information in the console stack. This is the default.
TERM: displays warning messages at the terminal whenever UPDATE finds a sequence or update control card error. (Such warning messages appear in the update log, whether UPDATE displays them at the terminal or not.) This is the default.
NOTERM: suppresses the display of warning messages at the terminal. However, error messages that stop the entire update procedure are displayed at the terminal.
TYPe: has the same function as the TERM option.
NOTYPe: has the same function as the NOTERM option.
DISK: places the update log file on a disk or directory. This file has a file identifier fn UPDLOG, where fn is the file name of the file being updated. This is the default.
PRINT: prints the update log file directly on the virtual printer. For more information, see Usage Note 1.
STOR: specifies the source input file is to be read into storage and the updates performed in storage before placing the updated source file on a disk or directory. This option is meaningful only for use with the CTL option, because the benefit of increased processing speed is realized when processing multiple updates. STOR is the default when you specify CTL.
NOSTOR: specifies no updating is to take place in storage. NOSTOR is the default when you apply single updates (for example, you do not specify CTL on the command line). This is the default.

Usage Notes

If the PRINT option is specified and the LPP option on the CP SPOOL command is 0 (LPP OFF), the number of lines per page for the update log file will be 55. If the LPP value is greater than 0, the number of lines per page for the update log file will be equal to the LPP value. For more information, see z/VM®: CP Commands and Utilities Reference.

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 the last eight columns of the source record, or the last five columns 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.

UPDATE checks the sequence numbers while applying updates. 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. UPDATE skips any source input records with a sequence field of eight blanks without any indication of a sequence error. UPDATE replaces or deletes such records 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 record, followed by one or more blanks and additional, blank-delimited fields. Control statement data must not extend beyond column 50.

SEQUENCE Control Statement

Numbers or renumbers the records in a file. Sequence numbers are written in the last eight columns (if you specify SEQ8) or in the last five columns with the label placed in the three preceding columns (if you do not specify NOSEQ8).

The format of the SEQUENCE control statement is:

Where:

seqstrt: is a 1-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-8 digit numeric field specifying the decimal increment for resequencing the output file. The default is the seqstrt value.
label: is a three-character field to be duplicated in the first three of the last eight columns of each source record if NOSEQ8 is specified. The default value is the first three characters of the input file name (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 the last eight columns 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

Precedes new records you may want to add to a source file.

The format of the INSERT control statement is:

Where:

seqno: is the sequence number of the record in the source input file where you want to add new records.
$: is an optional delimiter indicating to sequence the inserted records by increments.
seqstrt: is a 1-8 digit numeric field specifying the first decimal increment for sequencing the inserted records.
seqincr: is a 1-8 digit numeric field specifying the decimal increment for sequencing the inserted records.

The INSERT statement tells UPDATE where to add the new records. For example, the lines:

./ I 1600
TEST2 TM    HOLIDAY,X'02'    HOLIDAY
      BNO   VACATION         NOPE...VACATION

insert two lines of code, following the statement numbered 1600, into the output file. The inserted lines are flagged with asterisks in the last eight columns (if you specify NOCINC). If you specify either the INC or CTL option, UPDATE inserts the records unchanged in the output file, or they are sequenced according to the seqstrt fields, if you specify the dollar sign ($) key.

The default sequence increment, if you include the dollar sign, 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 is assumed here). For the control statement:

./  I  240000 $

the defaulted seqincr is the maximum, 100, and the starting sequence number is 240100. UPDATE assumes SEQ8, so it sequences the inserted records, 00240100, 00240200, and so forth.

If you specify either INC or CTL, not the dollar sign, whatever sequence number appears on the inserted records in the update file is included in the output file.

DELETE Control Statement

Deletes one or more records from the source file.

The format of the DELETE control statement is:

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 you do not specify seqno2, UPDATE deletes only a single record.

REPLACE Control Statement

Replaces one or more input records with updated records from the update file. It precedes any new records you may want to add. It is a combination of the DELETE and INSERT statements.

The format of the REPLACE control statement is:

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 the substituted records are to be sequenced incrementally.
seqstrt: is a 1-8 digit numeric field specifying the first decimal number to be used for sequencing the substituted records.
seqincr: is a 1-8 digit numeric field specifying the decimal increment for sequencing the substituted records.

For example, the lines:

./ R 38000 38500
PLIST   DS   OD
        DC   CL8X'TYPE'
        DC   CL8X' '
        DC   CL8X'FILE'
        DC   CL8X'A1'
        DC   8XX'FF'

replace the existing statements numbered 38000 through 38500 with the new lines of code. As with the INSERT statement, UPDATE does not automatically resequence new lines. In addition, the dollar sign ($), seqstrt, and seqincr processing is identical with that for the INSERT statement.

COMMENT Statement

Lets you place comments in the update log file.

Note: 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:

Where:

*: specifies this is a comment statement. PREREQ, CO-REQ, and IF-REQ comments identify requisite updates. PREREQs and CO-REQs describe dependencies in the same product. IF-REQs describe dependencies in other products. All comments are copied into the update log file. PREREQ, CO-REQ, and IF-REQ comments are also copied into the fn UPDATES file.

Summary of Files Used by the UPDATE Command

This discussion shows input and output files used by the UPDATE command for a:

Single update
Multiple updates
Multiple updates with an auxiliary control file

File Mode of Output Files

These steps determine the disk or directory selection for placing the output files, the search stops as soon as one of these steps is successful:

If you specify the OUTMODE option, UPDATE places the output files on the disk or directory specified, if it accessed as read/write. If the disk or directory you specify is accessed as a read/only extension, this message is displayed:
```
DMS037E  Filemode mode [(vdev)] is accessed as read/only
```
If the disk or directory on which the original source file resides is read/write, UPDATE places the output files on that disk or directory.
If the disk or directory on which the original source file resides is a read-only extension of a read/write disk or directory, UPDATE places the output files on that particular read/write disk or directory.
If neither of the last two steps is successful, UPDATE places the output files on the disk or directory accessed as A.

Applying a Single Update

Say you have created an update file, fn UPDATE, and you want to apply it to the source file fn ASSEMBLE. You can do this by issuing the following command:

update fn

UPDATE makes the changes to the source file you indicate in the update file and creates an updated version of the source file, but with a different file name. By default, the updated version of the file is called $fn ASSEMBLE. UPDATE also creates a file, fn UPDLOG, which is a record of the updates applied. For the above example, if you do not want this update log file written on a disk or directory, specify the PRINT option.

Note: You can override the default file types and file modes of the output files on the command line. For example,

update testprog cobol b fix cobol b (rep

results in updating the source file TESTPROG COBOL B, with control statements contained in the update file FIX COBOL B. The output file replaces the existing TESTPROG COBOL B.

Using UPDATE with a Control File

If you have more than one update file you want to apply to the same source file, you can apply them using a series of single updates, or you can use the UPDATE command specifying a control file. A control file lists the file type of the update files you want to apply to a source file. The control file itself does not contain the actual UPDATE control statements.

Say you have two update files, fn UPDTABC and fn UDPTXYZ, and they contain UPDATE control statements and new source records. These two update files must have file names that are the same as the source input file. The first four characters of the file type must be UPDT. The UPDATE command searches all accessed disks and directories to locate the update files. You can use one UPDATE command to apply these updates to one file at the same time. You do this by specifying a control file.

A control file (fn CNTRL) lists the file types of the files that contain UPDATE control statements. It may not contain UPDATE control statements. As an example, let's use the following sample control file:

*THIS IS A SAMPLE CNTRL FILE
TEXT MACS CMSLIB
TWO UPDTABC
ONE UPDTXYZ

TEXT, TWO, and ONE are update level identifiers. An update level identifier is the first word in a line and can be from 1-5 characters long. z/VM updating procedures such as the VMFASM EXEC use these identifiers to locate and identify text decks produced by multi-level updates.
MACS must be the first uncommented record in the control file. It contains an update level identifier (TEXT) and, optionally, macro library (MACLIB) file names, subject to the logical record length. MACLIB names must be separated by blanks. If the list does not fit on one MACS record, additional MACS records can be included. Each additional MACS record must have the same format as the first one. However, the update level identifier on additional MACS records is ignored. All MACS records must be contiguous. The total number of MACLIBS permitted in a control file is 63.
UPDATE uses the information provided in the MACS card and the update level identifier only when you specify the STK option. This information is, however, required in the CNTRL file.

You may specify comments on MACS records by means of an asterisk. Any information beyond the asterisk will be treated as a comment and will not be passed on when you specify the STK option.
UPDTABC and UPDTXYZ are file types 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.
These files can also contain PREREQ, CO-REQ, and IF-REQ comments that specify dependencies for applying the updates. The update files must have file names that are the same as the source input file.

So, in our example, to update fn ASSEMBLE with our sample control file, issue these:

update fn (ctl

UPDATE looks at the control file and begins applying the updates listed starting with fn UPDTXYZ (the bottom entry).

When you create update files that have file types beginning 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

Using UPDATE with an Auxiliary Control File

There may be times when you have two groups of programmers working on different sets of changes for the same source file. Each group can create several update files and have a unique control file. When you combine these changes, you could create one control file or you can use auxiliary control files. An auxiliary control file is a list of file types of the update files you want to apply to a source file.

Take an example where you want to make an update using an auxiliary control file. You have fn ASSEMBLE as the source file, fn UPDTABC and fn UPDTXYZ, as the update files, and a control file that looks like these:

TEXT MACS CMSLIB
TWO UPDTABC
ONE UPDTXYZ
TEXT AUXLIST

AUX in the file type AUXLIST indicates this is an auxiliary control file. This is another type of file listing the file types of update files you want to apply to a source file. In this example, the auxiliary control file lists the update files FIX01 and FIX02.

The 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 you issue:

update fn (ctl

UPDATE looks in the control file at the bottom entry, TEXT AUXLIST. Because this is an auxiliary control file, UPDATE looks in it and applies the updates listed in it (starting with the bottom entry) before applying the other updated files listed in the control file fn CNTRL.

Note: The file name of an auxiliary control file must be the same as the source input file. The file type must begin with the characters AUX and the remaining characters (a maximum of five) can be anything.

You may also specify an auxiliary file as:

xxxxx yyyyy AUX

in the control file.

Where:

xxxxx: specifies the update level identifier and
yyyyy: specifies the last five characters following AUX in the file type.

For example, the record:

TEXT LIST AUX

identifies the auxiliary file fn AUXLIST.

Additional Control File Records

In addition to the MACS record, the file types of update (UPDT) files, and the file types of auxiliary control (AUX) files, a control file can also contain:

Comments. These records begin with an asterisk (*) in column 1. Comments are also valid in AUX files.
PTF records. If the characters PTF appear in the update level identifier field, the UPDATE command expects the second field to contain the file type of an update file. The file type may be anything; the file name must be the same as the source input file.
Update level identifiers not associated with update files.

This is an example of a control file showing 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

Preferred AUX File

By using preferred auxiliary control files, you can use one control file for multiple versions of a file or multiple releases of a product. (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.)

Remember, to specify auxiliary control files, specify their file type in a control file.

To use preferred auxiliary control files, you must specify more than one file type per update level identifier. The first file type indicates a file UPDATE will use if none of the additional file types exist for any disks or directories you have accessed. If any of the files indicate the additional file types do exist, UPDATE ignores that entire entry and proceeds to the next entry in the control file. The files that indicate additional file types are preferred because UPDATE does not use the file the first file type indicates. For example, assume you want to update the file SAMPLE ASSEMBLE using the updates in SAMPLE AUXTEST. To update SAMPLE ASSEMBLE, use this control file (MYMODS CNTRL):

TEXT  MACS  MYMACS  CMSLIB  OSMACRO
MY2   AUXTEST
MY1   AUXMINE AUXTEST

and the command:

UPDATE SAMPLE ASSEMBLE * MYMODS CNTRL (CTL

UPDATE looks at the bottom entry in the control file first. It searches all accessed disk and directories for the auxiliary control file SAMPLE AUXTEST. Because that file exists, UPDATE does not use the auxiliary control file SAMPLE AUXTEST. Instead, UPDATE ignores this entry and continues to the next entry in the control file. The next entry only specifies one file type (AUXTEST). This is the preferred AUX file you want to use, so UPDATE applies the updates listed in SAMPLE AUXTEST. It is assumed 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 not a valid file type; that is, less than four or more than eight characters. This token and the remainder of the line are considered a comment.

The STK Option

The STK (stack) option is valid only with the CTL option and is meaningful only when the UPDATE command is issued 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 DMSGPI DMSOM  * basic system MACLIBS
LCL  AUXLCL * Local Mods
TEXT AUXVM  * PTF service

and the DMSABC AUXVM and DMSABC AUXLCL auxiliary control files both contain updates, and the UPDATE command appears in a REXX exec as follows:

/*****************************************************/
/* Update module DMSABC ASSEMBLE using control file  */
/* DMSVM CNTRL and stack the update level identifier */
/* and the list of MACLIBs from the MACS records.    */
/* Note: No error checking is performed here.        */
/*************************************************** */
'UPDATE DMSABC ASSEMBLE A DMSVM CNTRL A (CTL STK'
Parse Upper Pull star updtlvl
Parse Upper Pull star maclibs

the following variables will be set:

Variable: Value
star: *
updtlvl: LCL
maclibs: DMSGPI DMSOM

The library list may be useful to establish macro libraries in a subsequent GLOBAL command within the exec. If no update files are found, UPDATE stacks the update level identifier on the MACS record.

Missing Update Files

The following return codes are displayed when there are missing update files.

RC=0. This is returned when the only missing update files are files that are referenced directly through control files, and there was at least one update file found.
RC=12. This is returned if any of the update files referenced from an AUX file are not found, regardless of whether any other update files are found.
RC=40. This is returned if no update files are found and either AUX files are not used or there are no update files referenced by them. An RC=40 is also returned if AUX files are used, but there are no update files referenced.

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.

DMS177I 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:

4: Sequence errors were detected in the original source file being updated.
8: Sequence errors, which did not previously exist in the source file being updated were introduced in the output file during the updating process.
12: Any other warning error detected during the updating process. Such errors include not valid 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 file ID $fn1 ft1, as if the REP option was not specified.

DMS178I  Updating fn ft fm
            Applying fn ft fm
            Applying fn ft fm
            Applying fn ft fm (empty file)
                .
                .
                .

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. If the update file is empty, the text with (empty file) is displayed. The updating process continues.

DMS304I 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 or SFS directory must be used. This message is displayed only if NOSTOR was specified in the UPDATE command line.

DMS1229I fn ft fm is empty

This message is displayed when the auxiliary control file is an empty file.

DMS180W Missing PTF file fn ft fm RC=12

In the event 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.

Messages and Return Codes

DMS001E No file name specified [RC=24]
DMS002E File [fn [ft [fm]]] not found [RC=28]
DMS003E Invalid option: option [RC=24]
DMS007E File fn ft fm is not fixed, 80-character records [RC=32]
DMS007E File fn does not have the same format and record length as fn [RC=32]
DMS007E File fn ft fm is not fixed record format [RC=32]
DMS007E File fn ft fm does not have a logical record length greater than or equal to 80 and less than or equal to 255 [RC=32]
DMS010W Premature EOF on file fn ft fm--sequence number seqno not found [RC=12]
DMS024E File fn ft fm already exists [RC=28]
DMS048E Invalid filemode mode [RC=24]
DMS065E option option specified twice [RC=24]
DMS066E option1 and option2 are conflicting options [RC=24]
DMS069E Filemode mode not accessed [RC=36]
DMS070E Invalid parameter parameter [RC=24]
DMS104S Error nn reading file fn ft fm from disk or directory [RC=100]
DMS105S Error nn writing file fn ft fm on disk or directory [RC=100]
DMS174W Sequence error introduced in output file: seqno1 to seqno2 seqno1 to seqno2 [RC=8]
DMS176W Sequencing overflow following sequence number seqno [RC=8]
DMS179E Missing or invalid MACS card in control file fn ft fm [RC=32]
DMS181E No update files were found [RC=40]
DMS182W Sequence increment is zero [RC=8]
DMS183E Invalid {CONTROL|AUX} file control card [RC=32]
DMS184W ./S not first card in update file--ignored [RC=12]
DMS185W Invalid character in sequence field seqno [RC=12]
DMS186W Sequence number seqno not found [RC=12]
DMS187E Option STK invalid without CTL [RC=24]
DMS207W Invalid update file control card [RC=12]
DMS210W Input file sequence error: seqno1 to seqno2 [RC=4]
DMS299E Insufficient storage to complete update [RC=41]
DMS300E Insufficient storage to begin update [RC=41]
DMS361E Disk mode is not a CMS disk [RC=36]
DMS1213W Update fn ft fm is an UPDATE SHELL [RC=12]
DMS1229E fn ft fm is empty [RC=32]
DMS1259E File pool filepoolid has run out of physical space in the storage group [RC=100]
DMS1262E Error nn opening file fn ft fm [RC=nn]

Additional system messages may be issued by this command. The reasons for these messages and their location are:

Reason	Location
Errors in command syntax	Command Syntax Error Messages
Errors in using a file	File Error Messages
Errors in using the Shared File System	File Pool Server Messages