Using OBJZAP on OS/390

Introduction

OBJZAP is a utility that can be run under OS/390 to make changes to object modules (because several parts of the products are supplied in object form). OBJZAP operates on object modules that are members of partitioned data sets, allowing users to

examine data and instructions
change data and instructions
dump any control section (CSECT) of the object deck.

Although OBJZAP was designed to be similar to the IBM utility program AMASPZAP (also known as superzap), several important differences exist, notably in the algorithm used by the CHECKSUM statement. OBJZAP uses several control statements that specify the operations to be performed. This section includes a brief synopsis of the control statements and detailed syntax rules, followed by an example of an OS/390 job stream to run OBJZAP in batch.

Control Statements

This section provides an introduction to the organization of the control statements that are used to run the OBJZAP utility. Following this introduction is a detailed description of each statement and a brief discussion of the syntax rules.

Organization

Control statements for the OBJZAP utility are listed below. (Control statements are not case sensitive.)

NAME member csect
   VER offset expected-content
   REP offset replacement-data
   CHECKSUM value
   ALIAS alias1,alias2, . . .
   IDRDATA xxxxxxxxxx
   DUMP member csect

Each set of control statements begins with a NAME statement. The VER, REP, ALIAS, IDRDATA, and DUMP statements following the NAME statement apply to the partitioned data set (PDS) member and the CSECT that the NAME statement identifies.

The VER, REP, ALIAS, IDRDATA, and DUMP statements can appear in any order, but it is better to code all VER statements before the first REP statement to ensure that the data are verified before anything is replaced. The DUMP statement must follow the NAME statement; the CHECKSUM statement can appear anywhere in the sequence of statements. When a new NAME statement occurs, it defines a new CSECT (possibly in a new member) as the object of succeeding VER, REP, ALIAS, IDRDATA, and DUMP statements.

Statement Descriptions

NAME member csect
NAME gives the identity of the object deck member containing the csect (control section) that all succeeding control statements operate on. There is no restriction on the number of NAME statements that can appear.
VER offset expected-content
VER compares the contents of a location in the CSECT (offset ) with the expected content (expected-content) supplied by the user. If the two fields do not compare as equal, the VER operation fails and a formatted dump is provided for the csect. No further REP operations are performed until the next NAME statement occurs. offset contains the hexadecimal displacement of the data in csect. The VER operation fails if offset is outside the boundaries for the CSECT specified by the NAME statement (offset can be an even or odd number of digits).
expected-content
contains the hexadecimal representation of the data expected at the offset in csect. The data must be expressed as an even number of two hexadecimal values, for example,
```
4741D175 (or, with commas: 4741,D175).
```
If commas are used to separate data, the number of digits between them must also be even. Blanks cannot be used to separate digits. A blank ends expected-content; any data following a blank are treated as comments and ignored. For data that will not fit in one 80-byte VER statement, a second statement must be used.
REP offset replacement-data
REP changes the data in a CSECT defined in the NAME statement. It replaces the data specified at offset with the data specified in replacement-data. The REP operation fails if offset is outside the boundaries for the CSECT specified in the NAME statement. The formats of the arguments to REP follow the same rules as the formats of the VER arguments.
The VER operation should always be performed to determine what will be changed with the REP function. If more than one VER and REP operation is to be performed on a CSECT, statements should be ordered so that all VER statements appear before all REP statements. The reason for this order is to ensure that no REP statement is performed if any VER operation fails.
When REP is successful, the old data are printed out, and the IDR information in the object deck is automatically updated. (See the IDRDATA discussion.)
CHECKSUM <value>
The CHECKSUM statement performs one of two tasks, depending on whether the optional value argument is used. The value argument must be eight hexadecimal digits and cannot contain commas.
If the value argument is present, the statement compares the number specified in value and the accumulated CHECKSUM. The checking is done when OBJZAP reads the control statements. If the accumulated CHECKSUM and the number specified by value are not equal, no processing is done.
If the value argument is not present, the accumulated CHECKSUM is printed in hexadecimal.
The accumulated CHECKSUM starts at zero and is reset to zero by each CHECKSUM statement. Only the offsets and data from REP statements are used in accumulating the CHECKSUM.
The CHECKSUM statement guards effectively against typographical errors in making a change. All fixes to object modules supplied by SAS Institute contain CHECKSUM statements, and you should not remove them.
You can use a comment in the CHECKSUM statement if the CHECKSUM statement contains a value argument. (See the discussion of comments later in this chapter.)
ALIAS alias1<,alias2, . . .>
The ALIAS statement establishes aliases for the PDS member being zapped. Each ALIAS statement can have one or more alias values separated by commas; no blanks can occur between aliases in an ALIAS statement. Up to sixteen unique aliases are allowed for each member.
The ALIAS statement uses the member name from the latest NAME statement. ALIAS statements can occur anywhere after the NAME statement; however, ALIAS information is updated only if there has been a successful REP operation (that is, if IDR data are updated).
Note: The ALIAS statement is needed because OBJZAP does not update in place. Therefore, aliases must be explicitly re-established; the ALIAS statement does this. Zaps to the resident portion of the run-time library from SAS Institute contain the names of any necessary aliases in an ALIAS statement as part of the zap.
IDRDATA xxxxxxxxxx
The IDRDATA control statement is executed only if at least one REP operation is executed. IDRDATA puts a maximum of 10 bytes of user data into bytes 1 to 10 at the location of the second IDR item (on the END card of the deck that contains the CSECT). xxxxxxxxxx is the ten bytes of data, expressed without embedded blanks. Blanks are added at the right if less than 10 bytes are specified. IDRDATA is useful for tracing what zaps have been applied.
Note that when a REP operation is performed, the following occurs:
If there is more than one CSECT in the deck on which a REP is performed, the IDRDATA from the last CSECT is used. If there was no previous IDR statement, *UNKNOWN* is used. It is customary for zaps supplied by SAS Institute to contain IDRDATA statements with the release and zap numbers as identification.
DUMP <member> <csect>
DUMP or DUMPT dumps the CSECT identified in the NAME statement. The csect and member arguments are optional, and if specified, they must be the same as in the NAME statement. The output of the DUMP command is in hexadecimal format. When this command is used, the IDR data from the most recent zap (successful or unsuccessful) are printed, in addition to the contents of the CSECT. Note that a NAME statement must always come before the DUMP statement.
GO
GO delimits a set of control statements. It is primarily intended for interactive execution of OBJZAP under TSO.
The GO statement instructs OBJZAP to perform the preceding control statements. OBJZAP does syntax checking and executes the statements if it finds no syntax errors. You can then enter a new set of OBJZAP control statements. (The new set must begin with a NAME statement.)
* Comments
Comment statements: You can use comments in the OBJZAP command stream. Comment statements must be in the form *comment. (The number of comments is not limited.) OBJZAP writes the comment statements to the standard output data set ( stdout ).
Comments included on control statements: You can also include comments on control statements, other than the DUMP or DUMPT statements. In a control statement, place the comment after the last argument that the statement requires. Precede the comment with a blank. You do not need an asterisk (*) to indicate a comment on a control statement. If no arguments are present, you cannot use a comment on the control statement.

Detailed Syntax Rules

As described earlier in this chapter, statement syntax is similar to that for the IBM program AMASPZAP. The detailed syntax rules follow:

An OBJZAP operation name must be specified before any arguments in a statement.
The statement can be entered starting in any column. Control statements can be up to 80 bytes long. (Information beyond column 72 is ignored.)
Several blanks can separate the OBJZAP operation name and its first argument, but there must be at least one blank. Similarly, one or more blanks must separate arguments in the statement.
Commas can be used in data fields other than offsets and the CHECKSUM value. Blanks are not allowed inside data fields. A blank terminates a data field.
Values in the expected-content field (VER statement) and the replacement-data field (REP statement) must be expressed as an even number of hexadecimal digits.
Comment statements are specified by an asterisk. Comments can also be used in control statements other than the DUMP statement. In a control statement, a space separates the comment from the last argument that the statement takes. No asterisk (*) is needed for comments on control statements.
Control statements are not case sensitive.

JCL Execution

The following DD statements are required to execute OBJZAP:

SYSIN: contains the OBJZAP control statements.
SYSPRINT: identifies the standard output message data set (sequential).
SYSLIB: identifies the partitioned data set containing the member(s) to be zapped.
STEPLIB: compiler library and transient library.

The following statement is optional:

SYSTERM the data set to be used for diagnostic messages.

Example B.1 shows a sample OS/390 JCL routine to run OBJZAP.

Sample JCL for OBJZAP
//jobname JOB jobcard information //OBJZAP EXEC PGM=OBJZAP //STEPLIB DD DSN=sasc.LOAD,DISP=SHR // DD DSN=sasc.LINKLIB,DISP=SHR //SYSIN DD * NAME XXX BUILD@$ VER 002 C5E2C3 REP 002 C6E3C4 IDRDATA ABCDEF1237 * A NEW CSECT IN A DIFFERENT PDS MEMBER. NAME ZZZ MAIN@$ VER 35 969540F1 VER 6D A3009096 IDRDATA XXXXEF1237 //SYSLIB DD DSN=sasc.object.library,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSTERM DD SYSOUT=* //

In batch mode, OBJZAP reads all control statements before processing them.

Interactive Execution

You can run OBJZAP interactively under TSO by entering OBJZAP control statements from the terminal, followed by a GO statement. The GO statement executes all control statements you enter before the GO statement. Use the string EOF (in uppercase) to signal end-of-input when you are finished with OBJZAP.

Chapter Contents
Previous
Next
Top of Page