Coding rules for SPZAP control statements

Follow these rules when coding the control statements for SPZAP:

The size of a SPZAP control card is 80 bytes; it can contain 71 bytes of control information.
Statements can begin in any column up to column 71.
The operation name of the statement must precede the parameters and must be complete on the first statement; you cannot continue the operation name.
There must be at least one blank between the specified operation name and the first parameter.
All parameters must also be separated by at least one blank space.
Data field parameters may be formatted with commas for easier visual check, but blanks within data fields are not permitted.
Data and offset values must be specified as a multiple of two hexadecimal digits.
Following the last required parameter and its blank delimiter, the rest of the space on most control statements can be used for comments. Exceptions to this are the NAME and DUMP control statements: if you omit the CSECT parameter from either of these statements, do not use the space following the load module parameter for comments.
A record beginning with an asterisk is considered to be a comment statement.
A comment statement (one that begins with a single asterisk) cannot be continued.
Member names and CSECT names for program objects can be as long as 1024 characters.
When SYSLIB refers to a PDSE or a z/OS® UNIX file, you can continue any non-comment statement as follows:
- Column 72 of the control card to be continued must contain a non-blank character.
- The string of characters on the immediately following card (starting with the first non-blank character) is concatenated with column 71 of the preceding card. AMASPZAP ignores leading blanks in a continuation card, but it displays the cards on SYSPRINT unchanged.
- You can continue statements as necessary. You cannot, however, continue a comment field that follows the last parameter.
- Even though some parameters allow you to use a single asterisk (*) to indicate an omitted parameter, the first non-blank character on a continuation card cannot be an asterisk. Select the break point carefully to avoid starting a continuation statement with a single asterisk.
In other words, for continuation:
- When the SYSLIB is a PDSE or a z/OS UNIX file, IGWSPZAP is invoked, which supports continuation.
- When the SYSLIB is a PDS, AMASPZAP is invoked, which does not support continuation.

Following are detailed descriptions of the SPZAP control statements, in alphabetical order.

{ABSDUMP|ABSDUMPT}{startaddr stopaddr | startrec stoprec | membername | ALL}

This statement can be used to dump the following, as defined in the SYSLIB DD statement:

A group of physical records
A group of records belonging to a member of a PDSE data library
A load module member or all load module members of a PDS
All members of a PDSE
The directory of a PDSE that contains program objects

If the key associated with each record is to be formatted, DCB=(KEYLEN=nn), where “nn” is the length of the record key, must also be specified by the SYSLIB DD statement. Note that when dumping a VTOC, DCB=(KEYLEN=44) should be specified; when dumping a PDS directory, DCB=(KEYLEN=8) should be specified. ABSDUMP produces a hexadecimal printout only, while ABSDUMPT prints the hexadecimal data, the EBCDIC translation, and the mnemonic equivalent of the data. See Reading SPZAP output. The variables are:

startaddr

The absolute direct access device address of the first record to be dumped. This address must be specified in hexadecimal in the form cccchhhhrr (cylinder, track and record numbers). This parameter must be exactly 10 digits long.

stopaddr

The absolute direct access device address of the last record to be dumped, and it must be in the same format as the start address.

Both addresses must be specified when this method of dumping records is used, and both addresses must be within the limits of the data set defined by the SYSLIB DD statement. The record number specified in the start address must be a valid record number. If a record number of 0 is specified, SPZAP will change it to 1 since the READ routine skips over such records. The record number specified as the stop address need not be a valid record number, but if it is not, the dump will continue until the last record on the track specified in the stop address has been dumped.

Note: When the SYSLIB DD statement describes a data set placed in an extended address volume (EAV), the startaddr and stopaddr values must be specified in hexadecimal in the form CCCCcccHRR, where CCCCccc is referred to as a 28-bit cylinder address. The meanings of the codes are as follows:

CCCC is the 16 low order bits of the cylinder number.
ccc is the 12 high order bits of the cylinder number.
H is the track number.
RR is the record number.

startrec

The value of the first relative record of a member of a PDSE data library to display. This parameter can be 1 to 8 digits long. The first record of a member has a startrec value of 1.

Note: ABSDUMP|ABSDUMPT startrec stoprec is valid only following a NAME member statement where SYSLIB is a PDSE data library and member is a valid member of that library.

stoprec

The value of the last relative record of a member of a PDSE data library to display. This parameter can be 1 to 8 digits long. If the value of stoprec specifies a relative record value greater than that of the last physical record, printing stops after the last record of the member is printed. If the value of stoprec is less than the value of startrec, no records are displayed. One can display all the records of a member of a PDSE data library by using the following two statements:

   NAME  member
   ABSDUMP|ABSDUMPT   1 99999999

membername

The name of a member of a PDS or a PDSE, as specified by the SYSLIB DD statement. The name can refer to a load module member of a PDS or a member of a PDSE data library. In each case, the entire member is dumped when this variable is specified. (Use DUMP/DUMPT for program object members of a PDSE.)

ALL

Specifies that the entire data set defined by the SYSLIB DD statement is to be dumped. How much of the space allocated to the data set is dumped depends on how the data set is organized:

For a sequential data set, SPZAP dumps until it reaches end of file.
For an indexed sequential and direct access data set, SPZAP dumps all extents.
For a PDS, SPZAP dumps all extents, including all linkage editor control records, if any exist.
For a PDSE data library, SPZAP displays a directory plus a listing of all members of the library. If the data set is a PDSE that contains program objects, SPZAP displays only the directory.

BASE xxxxxx

Used by SPZAP to adjust offset values that are to be specified in any subsequent VERIFY and REP statements. This statement should be used when the offsets given in the VERIFY and REP statements for a CSECT are to be obtained from an assembly listing in which the starting address of the CSECT is not location zero.

For example, assume that CSECT ABC begins at assembly listing location X'000400', and that the data to be replaced in this CSECT is at location X'000408'. The actual displacement of the data in the CSECT is X'08'. However, an offset of X'0408' (obtained from the assembly listing location X'000408') can be specified in the REP statement if a BASE statement specifying X'000400' is included prior to the REP statement in the SPZAP input stream. When SPZAP processes the REP statement, the base value X'000400' will be subtracted from the offset X'0408' to determine the proper displacement of data within the CSECT. The variable is:

xxxxxx: A 6-character hexadecimal offset that is to be used as a base for subsequent VERIFY and REP operations. This value should reflect the starting assembly listing address of the CSECT being inspected or modified.
Note: The BASE statement should be included in the SPZAP input stream immediately following the NAME statement that identifies the control section that is to be involved in the SPZAP operations. The specified base value remains in effect until all VERIFY, REP, and SETSSI operations for the CSECT have been processed.

Figure 1 shows how to use the BASE control statement to inspect and modify a CSECT whose starting address does not coincide with assembly listing location zero.

Figure 1. Example: Using the BASE control statement

//MODIFY     JOB          MSGLEVEL=(1,1)
//STEP       EXEC         PGM=AMASPZAP
//SYSPRINT   DD           SYSOUT=A
//SYSLIB     DD           DSNAME=SYS1.LINKLIB,DISP=OLD
//SYSIN      DD           *
 NAME             IEFMCVOL  IEFCVOL2
 BASE            0398
 IDRDATA         MOD04
 VERIFY          039A 5820C010
 REP             039A 47000000
 DUMP            IEFMCVOL   IEFCVOL2

SYSLIB DD Statement: Defines the system library, SYS1.LINKLIB, that contains the module IEFMCVOL in which the CSECT to be changed, IEFCVOL2, resides.

SYSIN DD Statement: Defines the input stream that contains the SPZAP control statements.

NAME Control Statement: Instructs SPZAP that the operations defined by the control statements that immediately follow it are to be performed on CSECT IEFCVOL2 in the load module IEFMCVOL.

BASE Control Statement: Provides SPZAP with a base value that is to be used to readjust the offsets on the VERIFY and REP statements that follow it.

IDRDATA Control Statement: Causes SPZAP to update the IDR in module IEFMCVOL for CSECT IEFCVOL2 with the data MOD04, if the REP operation is successful.

VERIFY Control Statement: Requests that SPZAP inspect the data at offset X'039A'. The base value X'0398' given in the previous BASE statement is subtracted from this offset to determine the proper displacement of the data within CSECT IEFCVOL2. Therefore, SPZAP checks the data at the location that is actually displaced X'0002' bytes from the beginning of CSECT IEFCVOL2 to ensure that it is the same as the hexadecimal data specified in this control statement. If the data is the same, SPZAP continues processing the following statements in the order in which they are encountered. If the data is not identical, SPZAP does not perform the REP, SETSSI, or IDRDATA functions, but it does perform the DUMPs operation; it also dumps a hexadecimal image of CSECT IEFCVOL2 to the SYSPRINT data set.

REP Control Statement: Causes SPZAP to replace the data at displacement X'0002' (offset 039A minus base value 0398) into CSECT IEFCVOL2 with the hexadecimal data specified in this control statement.

DUMP Control Statement: Requests that SPZAP dump a hexadecimal image of CSECT IEFCVOL2 to the SYSPRINT data set. Since the DUMP statement follows the REP statement, the image will reflect the changes made by SPZAP (assuming no verification has been rejected).

CCHHR record address

Identifies a physical record on a direct access device that is to be modified or verified. The record must be in the data set defined by the SYSLIB DD statement. Any immediately following REP or VERIFY statements will reference the data in the specified record. The variable is:

record address: The actual direct access address of the record containing data to be replaced or verified. It must be specified as a 10-digit hexadecimal number in the form cccchhhhrr, where cccc is the cylinder, hhhh is the track, and rr is the record number. For example, 0001000A01 addresses record 1 of cylinder 1, track 10. A zero record number is incorrect and defaults to 1.

Note:

You can define more than one CCHHR statement in your input to SPZAP. However, the VERIFY, REP and SETSSI statements associated with each CCHHR statement must immediately follow the specific CCHHR statement to which they apply.
When the SYSLIB DD statement describes a data set placed in an extended address volume (EAV), the record address value must be specified in hexadecimal in the form CCCCcccHRR, where CCCCccc is referred to as a 28-bit cylinder address. The meanings of the codes are as follows:
- CCCC is the 16 low order bits of the cylinder number.
- ccc is the 12 high order bits of the cylinder number.
- H is the track number.
- RR is the record number.

CHECKSUM [hhhhhhhh]

Used to print or verify a fullword checksum (parity-check). All of the valid hexadecimal operands since the preceding CHECKSUM statement or SPZAP initialization are logically concatenated into a single string divided into fullwords, the sum of which is the checksum. For example, the string 12345678FACE produces the checksum 0D025678. Each CHECKSUM statement resets the accumulated checksum value to zeros.

The CHECKSUM statement is effective in detecting clerical errors that may occur when transcribing an SPZAP type of fix. CHECKSUM does not prevent errors; it only causes a message to be issued. By the time the CHECKSUM statement is processed, all prior replaces have been done.

hhhhhhhh

8 hexadecimal characters that are compared with the checksum. If the two values are equal, a message is written indicating that the checksum was correct and has been reset.

If the operand field is blank, a message is written giving the actual value of the checksum, and indicating that the checksum has been reset.

When the CHECKSUM control statement is provided with an incorrect operand, the REP and SETSSI statements processed already are not affected.

If the operand is not valid or is not equal to the checksum, a message is written indicating incorrect operand or checksum error. All subsequent REP and SETSSI statements are ignored until the next NAME or CCHHR statement is encountered. The results of previously processed statements are not affected.

* (Comment)

When the first non-blank character in a statement is an asterisk, SPZAP recognizes the statement as a comment, used to annotate the SPZAP input stream and output listing. You can specify the asterisk in any position, but at least one blank space must follow the asterisk. You can include any number of comment statements in the input stream, but you cannot continue a comment statement. When SPZAP recognizes a comment, it writes the entire statement to the data set specified for SYSPRINT.

CONSOLE

Indicates that SPZAP control statements are to be entered through the system console. When this statement is encountered in the input stream, the following message is written to the operator:

AMA116A  ENTER AMASPZAP CONTROL STATEMENT OR END

The operator may then enter in any valid SPZAP control statement conforming to the specifications described in the beginning of this control statement discussion. After each operator entry through the console is read, validated, and processed, the message is reissued, and additional input is accepted from the console until “END” is replied. SPZAP will then continue processing control statements from the input stream until an end-of-file condition is detected.

Note:

You can enter control statements through the console in either uppercase or lowercase letters, but AMASPZAP does not fold lowercase input to uppercase.
You cannot continue a control statement entered through the console.

Figure 2 shows how to enable SPZAP control statements to be entered through the console.

Figure 2. Example: Entering SPZAP control statements through console

//CONSOLIN   JOB      MSGLEVEL=(1,1)
//STEP       EXEC     PGM=AMASPZAP
//SYSPRINT   DD       SYSOUT=A
//SYSLIB     DD       DSNAME=SYS1.LINKLIB,DISP=OLD
//SYSIN      DD       *
        CONSOLE
/*

SYSLIB DD Statement: Defines the data set that contains the module to be updated.

SYSIN DD Statement: Defines the input stream.

CONSOLE Control Statement: Indicates that SPZAP control statements are to be entered through the console.

{DUMP|DUMPT} member [csect | ALL | * ] [class-name]

Dumps a specific control section or all control sections in a load module in a PDS, a program object in either a PDSE or a z/OS UNIX file. DUMP produces a hexadecimal printout only, while DUMPT prints the hexadecimal data, the EBCDIC translation, and the mnemonic equivalent of the data (see Reading SPZAP output). The variables are:

member: The member name of the load module in a PDS or program object in a PDSE that contains the control section(s) to be dumped. (Note: This variable, ‘member’, must correspond to the name of a member of the PDS or PDSE that is defined by the SYSLIB DD statement.
csect | ALL | *: Defines the name of the particular control section that is to be dumped. To dump all the CSECTs of a load module in a PDS or a program object in a PDSE, specify “ALL” instead of the CSECT name. If you omit the variable entirely, or, for program objects only, code “*”, SPZAP assumes that you mean to dump only the first CSECT in the load module or program object.
If you specify a CSECT name that SPZAP does not find in the member, SPZAP dumps all of the CSECTs in the member.

Note: DUMP or DUMPT applied to a CSECT consisting only of space allocations (DS statements) will produce no output between the statement printback and the dump-completed message.
class-name: Indicates, for program objects only, the class of text that you want to dump. The default is B_TEXT. Specifying B_*, C_*, or D_* causes SPZAP to dump all text classes beginning with the string that precedes the asterisk. If you want to omit the CSECT name and supply a class-name, code a single asterisk for the CSECT name followed by the class-name.
For information about the values you can specify for class name, see z/OS MVS Program Management: User's Guide and Reference.

Note: SPZAP does not fold lowercase input to uppercase; be sure to enter class-name in the correct case.

Figure 3 shows how to use the DUMPT and DUMP control statements to inspect CSECTs in a program object with multiple text classes in a z/OS UNIX file:

Figure 3. Example: Using the DUMP control statement with a class name

_//ZAPDUMP    EXEC PGM=AMASPZAP
_//SYSPRINT DD SYSOUT=*
_//SYSLIB   DD PATH='/u/mydir',PATHDISP=(KEEP,KEEP)
_//SYSIN DD *
DUMPT hwz CEEMAIN C_CODE
DUMP  hwz CEESTART B_*
DUMP  hwz ALL C_*
/*

SYSLIB DD Statement: Defines the z/OS UNIX directory that contains the module hwz in which the CSECTs to be inspected reside.

SYSIN DD Statement: Defines the input stream that contains the SPZAP control statements.

DUMPT hwz CEEMAIN C_CODE: This control statement requests that the contents of class C_CODE in csect CEEMAIN in module hwz be dumped.

DUMP hwz CEESTART B_*: This control statement requests that the contents of all classes in csect CEESTART in module hwz whose class name begins with B_ be dumped.

DUMP hwz ALL C_*: This control statement requests that the contents of all classes whose class name begins with C_ in any csect in module hwz be dumped.

IDRDATA xxxxxxxx

Causes SPZAP to place up to eight bytes of user data into the SPZAP CSECT identification record of the load module; this is only done if a REP operation associated with a NAME statement is performed and the load module was processed by the linkage editor to include CSECT identification records. The variable is:

xxxxxxxx: Eight (or fewer) bytes of user data (with no embedded blanks) that are to be placed in the user data field of the SPZAP IDR of the named load module. If more than eight characters are in the variable field, only the first eight characters will be used.

Note: The IDRDATA statement is valid only when used in conjunction with the NAME statement. It must follow its associated NAME statement, or the BASE statement associated with a NAME statement, and precede any DUMP, DUMPT, ABSDUMP or ABSDUMPT statement. IDRDATA statements associated with CCHHR statements will be ignored.

NAME member [csect | * ] [class-name]

Identifies a CSECT in a load module member of a PDS, a program object member of a PDSE, or a z/OS UNIX file that is to be the object of subsequent VERIFY, REP, SETSSI, or IDRDATA operations. The variables are:

member: The member name of the load module belonging to a PDS, the program object belonging to a PDSE, or a z/OS UNIX file that includes the CSECT that contains the data to be inspected or modified. The load module or the program object must be a member of the data set defined by the SYSLIB DD statement.
csect | *: The name of the particular control section that contains the data to be verified or replaced. If you omit this variable, or, for program objects only, code “*”, SPZAP assumes that the first CSECT in the load module contained in a PDS, the program object contained in a PDSE, or a z/OS UNIX file is the one to be used. If there is only one CSECT in the load module or program object, this variable is not necessary.
If you specify a CSECT name that SPZAP does not find in the member you name, then SPZAP does not perform any requested processing. Instead, it produces hexadecimal dumps of all CSECTs in the member. (The class of text dumped is specified on the class-name variable, and the default is B_text.)
class-name: Indicates, for program objects only, the class of text that you want to modify. The default is B_text. If you want to omit the CSECT name and supply a class-name, code a single asterisk for the CSECT name, followed by the class-name.
For information about the values you can specify for class name, see z/OS MVS Program Management: User's Guide and Reference.

Note: SPZAP does not fold lowercase input to uppercase; be sure to enter class-name in the correct case.

Note that you can define more than one NAME statement in your input to SPZAP. However, the VERIFY, REP and SETSSI statements associated with each NAME statement must immediately follow the NAME statement to which they apply.

NAME member

Identifies the member of a data library that is to be the object of subsequent VERIFY, REP, ABSDUMP, ABSDUMPT or RECORD operations. The variable is:

member: The member name of a data library whose contents are to be displayed, verified and/or replaced.

RECORD nnnnnnnn

This statement identifies a particular record in a member of a PDSE data library and must follow a NAME member statement where member specifies the name of the member. The combination of NAME and RECORD defines the record for which VER|VERIFY and possible REPs are to be performed. nnnnnnnn consists of 1 to 8 decimal digits and specifies the relative record of interest. Leading zeroes are ignored. For example, the first record of a member may be specified as 1 or 01 or 00000001.

REP offset data

Modifies data at a specified location in a CSECT or physical record that was previously defined by the NAME, NAME/RECORD combination, or CCHHR statement. The data specified on the REP statement will replace the data at the record or CSECT location stipulated in the offset variable field.

SPZAP issues message AMA122I to record the contents of the specified location as they were before the change was made.

Note: IBM® recommends that, before you replace any data, you always use VER/VERIFY to make sure that the contents you are going to change with the REP function are what you expect. The offset and length that you specify on the VER/VERIFY statement, however, do not need to match any following REP statement exactly; a single successful VERIFY can validate multiple following REP statements.

offset

Provides the hexadecimal displacement of data to be replaced in a CSECT or data record. This displacement need not address a fullword boundary, but it must be specified as a multiple of two hexadecimal digits (0D, 02C8, 001C52).

If the offset value is outside the limits of data record (physical block) or CSECT being modified, the replacement operation will not be performed. When replacing data in a record with a key, the length of the key should be considered in the calculation of the displacement; that is, offset zero is the first byte of the key, not of the data.

data

Defines the bytes of data to be inserted at the location. As with the offset variable, the number of bytes of data defined must be specified as a multiple of two hexadecimal digits. If desired, the data within the variable may be separated by commas (never blanks); but again, the number of digits between commas must also be a multiple of two. For example, a REP data variable may look like this:

 4160B820 (without commas)
     or like this:
 4160,B820 (with commas).

If all the data to be modified does not fit into one REP statement (72 bytes), you can code another REP statement.

Note:

Remember that SPZAP automatically updates the system status index (SSI) when it successfully modifies the CSECT named or implied on the previous NAME statement.
If you are performing multiple VERIFY and REP operations on a CSECT, make sure that all the VERIFY statements precede all the REP statements. This procedure ensures that all REP operations are ignored if one VERIFY reject occurs.
You are not required to supply a VERIFY statement before the first REP statement; however, when SPZAP encounters a VERIFY statement, it must be satisfied before SPZAP processes any following REP requests.
When you access a record in the VTOC (for example, the data set control block (DSCB)) for modification, SPZAP issues the message AMA117D to the console. No message is issued, however, when an ABSDUMPT operation is performed on the VTOC.

SETSSI xxyynnnn

Places user-supplied system status information in the directory entry for the load module member in a PDS or program object member in a PDSE. The SSI entry must have been created when the load module or program object member was link edited. The variable is:

xxyynnnn

Four bytes of system status information the user wishes to place in the SSI field for this member. Each byte is supplied as two hexadecimal digits indicating the following:

xx   - change level
yy   - flag byte
nnnn - modification serial number

If SPZAP detects an error in any previous VERIFY or REP operation, the SETSSI function is not performed.

Note: Because all bits in the SSI entry are set (reset) by the SETSSI statement, be very careful when using it to avoid altering the vital maintenance-status information. SPZAP issues message AMA122I to record the SSI as it was before the SETSSI operation was performed. See Updating the System Status Index (SSI).

{VERIFY|VER} offset expected-content

Causes the data at a specified location within a CSECT or physical record to be compared with the data supplied in the statement.

offset

The hexadecimal displacement of data to be inspected in a CSECT or record. This displacement does not have to be aligned on a fullword boundary, but it must be specified as a multiple of two hexadecimal digits, such as 0D, 021C, 014682. If this offset value is outside the limits of the CSECT or data record defined by the preceding NAME, NAME/RECORD, or CCHHR statement, the VERIFY statement is rejected. If this offset value plus the length of the expected-content string is outside the limits of the CSECT or record defined by the preceding NAME, NAME/RECORD combination, or CCHHR statement, the VERIFY statement is rejected and flagged in error. When inspecting a record with a key, the length of the key should also be considered in the calculation of the displacement; that is, offset zero is the first byte of the key.

expected-content

Defines the bytes of data that are expected at the specified location. As with the offset variable, the number of bytes of data defined must be specified as a multiple of two hexadecimal digits. If desired, the data within the parameter may be separated by commas (never blanks), but again, the number of digits between commas must also be a multiple of two. For example, expected content might look like this:

5840C032 (without commas),
or like this:
5840,C032 (with commas)

If all the data does not fit into one VERIFY statement (80-byte logical record), then another VERIFY statement must be defined.

Note: If the two fields being compared are not in agreement, that is, if the VERIFY operation is rejected, no succeeding REP or SETSSI operations are performed until the next NAME or CCHHR control statement is encountered. SPZAP provides a formatted dump of each CSECT or record for which a VERIFY operation failed.