ibm:vm370-lib:cmshelp:update.helpcmd
UPDATE
CMS Commands
- update.helpcmd.txt
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.
ibm/vm370-lib/cmshelp/update.helpcmd.txt · Last modified: 2023/08/06 13:36 by Site Administrator