RockZap

Introduction

RockZap is a load module maintenance facility, similar to z/OS IMASPZAP or the CMS ZAP command. RockZap modifies load modules (or for CMS, both load modules and text libraries) based on information from control statements supplied by the user. RockZap is not a plug compatible replacement for the IBM ZAP utilities, but it provides functional and performance enhancements for load module maintenance.

RockZap is distributed as part of a software maintenance agreement between Rocket Software Inc. and its customers. RockZap is provided for the purpose of applying maintenance to Rocket Model 204 products, but you need not limit use of RockZap to those products.

Versions

This wiki page assumes that a site is running RockZap version 1.6 or later. Any documented feature or facility that requires a later version of RockZap will be clearly marked to indicate this. If a feature or parameter is not indicated as requiring any specific version of RockZap, it can be assumed that it is available in all versions covered by this document; that is, versions 1.6 and later of RockZap.

RockZap features

RockZap provides the following features:

• RockZap can save significant amounts of elapsed time and CPU for long ZAP input streams. This is because RockZap applies all ZAPs in the input stream before writing a module back to disk. (IMASPZAP and CMS ZAP both write parts of the load module back to disk each time a new NAME statement is encountered, reducing performance significantly.)
• RockZap detects and reports ZAPs that are already applied. Using IMASPZAP or CMS ZAP, the user must inspect long CSECT dumps produced by the ZAP utility in order to determine if the ZAP is already applied, or simply in error.
• RockZap allows the module name on all NAME statements to be overridden using the MODULE option. This provides the ability to have the same set of VERs and REPs applied to different load modules without making global changes to the NAME statements.
• RockZap can "back out" or remove ZAPs without requiring modification to the ZAP control statements. By using the BACKOUT option, ZAPs can be removed from the load module and replaced by the original Verify data.
• RockZap limits error reporting to the specific statements in error, and it reports only the information necessary to diagnose and correct the error.
• RockZap only writes modified load modules. If the ZAPs are already completely applied, RockZap does not write the load module back to disk.
• RockZap enforces stricter rules on ZAP input statements. Verify statements are required for all replaced bytes. This ensures that the load module contents are known before they are modified, and that a ZAP can be removed or "backed out" if necessary. You can override this feature, however, using the !NOVERIFY statement.

Differences between RockZap and IMASPZAP

• RockZap requires that every byte in the load module that is replaced is also verified, unless the !NOVERIFY statement is used.
• RockZap only modifies direct access load libraries. RockZap does not modify any other types of direct access datasets.
• The following SPZAP statements are not supported but are ignored when encountered in the input stream: SETSSI, IDRDATA, and CHECKSUM.
• The following IMASPZAP statments are not supported and will cause RockZap to terminate when they are encountered: CONSOLE, ABSDUMP, ABSDUMPT, and RECORD.

Differences between RockZap and CMS ZAP

• RockZap requires that every byte in the load module that is replaced is also verified, unless the !NOVERIFY statement is used.
• RockZap does not support CMS LOADLIBs.
• The following ZAP statements are not supported but are ignored when encountered in the input stream: COMMENT and LOG.

CMS installation

RockZap is distributed as a single load module in VMFPLC2 format. A set of object decks is also included in case linkedit is required. (This might be necessary for some older CMS versions).

RockZap will be installed when you install the other Sirius products you ordered. Usually, no additional steps are required.

The RockZap load module is linked AMODE=31. If RockZap must be relinked on your system, use the following commands:

LOAD ROCKZAP (RESET ROCKZAP RMODE 24 AMODE 31 GENMOD ROCKZAP (FROM APPL

You can omit the RMODE and AMODE parameters if you are running in a non-XA environment.

IBM z/OS installation

The ROCKZAP load module and library are distributed in IEBCOPY unload format and are merged with any other Sirius products you have purchased.

RockZap will be installed when you install the other Sirius products you ordered. Usually, no additional steps are required.

ROCKZAP can be copied to SYS1.LINKLIB, or SYS1.LPALIB and is reentrant.

RockZap options

z/OS users supply RockZap options in the PARM parameter of the EXEC job control statement.

For example, to force uppercase output and to backout ZAPs, use the following EXEC statement:

//ROCKZAP EXEC PRM=ROCKZAP,PARM='UPPER,BACKOUT'

CMS users specify options following a left parenthesis on the ROCKZAP command line.

For example, to force uppercase output and to backout the ZAPs in the file "LOCAL ZAP A1", specify the following:

ROCKZAP LOCAL ( BACKOUT UPPER

MODULE

The MODULE=modname option allows the module name on each NAME statement to be overridden with a single load-module name. This means that you can use the same ROCKZAP jobstream to apply the same zaps to different load modules in the designated load library (SYSLIB) without making changes to any of the NAME statements. For instance PARM='MODULE=ONLINE' would apply the zaps to the module named ONLINE in the designated load library, regardless of the load-module name on each NAME statement. Then, using the same job stream, PARM='MODULE=ONLINTST' would apply the same zaps to the module named ONLINTST, again, regardless of the load-module name on each NAME statement.

The MODULE option was introduced in version 1.6 of RockZap.

BACKOUT

The BACKOUT option removes a ZAP without requiring any modification to the ZAP input statements. BACKOUT reverses the effect of a ZAP by replacing the original Verify data in the module.

If the ZAPs were applied with IMASPZAP, CMS ZAP, or with RockZap using the !NOVERIFY statement, RockZap might not be able to perform a backout because all the original Verify data might not be present.

UPPER

The UPPER option forces all RockZap output to uppercase. This is usually unnecessary, except on certain Japanese terminals and when sending output to uppercase-only printers. UPPER is the default setting for Hitachi and Fujitsu systems.

REPORT

The REPORT option indicates that RockZap will run normally except that it will not update any load modules. This is useful in a situation in which you have a production load module you don't want to modify, but you need to determine whether or not a particular set of ZAPs are applied.

TXTLIB txtlib

The TXTLIB option is valid under CMS only. TXTLIB specifies that the ZAPs should be applied to a CMS text library instead of a load module.

You must provide the name of the text library following the TXTLIB parameter. The first parameter of the name statement (the module name) is ignored when using the TXTLIB option. Only the CSECT name is used for text libraries. No load modules are inspected or modified when the TXTLIB option is specified.

EXTRACT filetype

The EXTRACT option allows you to extract individual object files from a CMS text library. EXTRACT can only be used when the TXTLIB option is also specified.

EXTRACT requires a parameter that specifies the file type of the object files it creates. One object file is created for each member of the text library. The text library member name is used as the CMS file name.

RockZap control statements

RockZap control statements appear in columns 1 to 72 in fixed length, 80 byte records. Statements that begin with an asterisk are treated as comments and are ignored, except for the two special inline parameter statements !VERIFY and !NOVERIFY. Control statements can begin in any column, but line continuation is not allowed.

VER

The VER statement identifies a range of bytes to be matched with the load module contents. VER statements must follow a NAME statement. A VER statement must be present for each range of bytes that will be replaced in the load module. This is to ensure that the ZAP can be backed out later if necessary.

The format of the VER statement is:

VER offset verify-values comments

offset	The hexadecimal displacement from the start of the CSECT specified in the previous NAME statement, or from the start of the load module if no CSECT was specified.
verify-values	Pairs of hexadecimal characters optionally separated by commas. The values are the expected contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.
comments	Any characters after the first blank after the last verify-values character are ignored by RockZap.

The following are all valid VER statements:

VER 00 010203,040506 Verify bytes at offset 0. VER 01ca 47f0,c0e9 VER 23EC D20310004000,90ECD000,07FC

REP

The REP statement identifies a range of bytes to replace the current contents of a load module. The REP statement must be preceded by VER statements that cover the entire range of bytes that will be replaced. The format of the REP statement is:

REP offset replace-value comments

offset	The hexadecimal displacement from the start of the CSECT in the previous NAME statement.
replace-value	Pairs of hexadecimal characters optionally separated by commas. The values will replace the contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.
comments	Any characters after the first blank after the last replace-value character are ignored by RockZap.

The following are all valid REP statements:

REP 00 FFFFFF,FFFFFF Replace bytes at offset 0. REP 01ca 47f0,c0e8 REP 23EC D203101C4000,90ECD008,07FE

NAME

The NAME statement identifies a load module, and optionally a CSECT that defines the context for the VER and REP statements that follow. NAMEX is a synonym for NAME that allows compatibility with the Fujitsu OSIV ZAP utility.

The format of the NAME statement is:

NAME module [csect]

Where:

module	The name of the load module. Under CMS the filetype must be "MODULE". Under z/OS this is the name of a PDS member in the load library.
csect	The name of the control section in the load module. The csect name is optional. If the csect name is missing, subsequent verify and replace displacements are calculated from offset 0 in the load module.

DUMP or DUMPT

The DUMP statement prints all or part of the contents of a load module or CMS text library to SYSPRINT. Specifying DUMPT has the same effect as DUMP.

The format of the DUMP or DUMPT statement is:

DUMP[T] name [csect [offset [length]]]

Where:

name	The name of the load module or text library. Under CMS, specify the filename (only) of a file whose filetype must be "MODULE" or "TXTLIB". Under z/OS, specify the name of a PDS member in the load library.
csect	The name of the control section. The csect name is optional. If the csect clause is missing, the entire load module or text library contents are dumped.
offset	The hexadecimal starting offset within the csect. This is optional and can only be specified when a csect name is specified. Use the offset parameter when you want to dump only a part of a csect. If the offset is omitted, it defaults to 0.
length	The number of bytes (in hexadecimal) of the csect to dump. This is an optional parameter and can only be specified if a csect and starting offset are specified.

* !VERIFY

The special statement !VERIFY (and !NOVERIFY) allows you to control whether individual ZAPs are verified before being applied.

The main purpose of these statements is to override whether the current portion of the zap requires verify data. This can be useful when a single ZAP in an input stream containing many ZAPs has no verify data.

The asterisk and space are necessary so that other ZAP utilities treat the statements as comments.

Use !VERIFY anywhere within the ZAP input stream. ZAPs following the !VERIFY statement will be verified (the VER data must match the module contents) before the ZAP will be applied.

Since the !NOVERIFY statement is new in RockZap version 1.6, you might have RockZap JCL or EXECs that use the NOVERIFY program option to accomplish this purpose, but at a dangerous job step level. We strongly recommend you do not use the NOVERIFY program option, but use the !NOVERIFY statement instead, and only when needed.

* !NOVERIFY

The special inline statement !NOVERIFY (and !VERIFY) allows you control whether individual ZAPs are verified before being applied. The main purpose of these statements is to override whether the current portion of the zap requires verify data. This can be useful when a single ZAP in an input stream containing many ZAPs has no verify data or the verify data is known to be incorrect.

Use !NOVERIFY anywhere within the ZAP input stream. ZAPs following the !NOVERIFY statement will not be verified (the VER data may be missing, or not match the module contents) before the ZAP will be applied.

Since the !NOVERIFY statement is new in RockZap version 1.6, you might have RockZap JCL or EXECs which use the NOVERIFY program option to accomplish this purpose, but at a dangerous job step level. We strongly recommend you do not use the NOVERIFY program option, but use the !NOVERIFY statement instead, and only when needed.

Using RockZap under z/OS

Job Control requirements for RockZap are the same as for IMASPZAP. Most RockZap storage is allocated above the 16 megabyte line, so the default region size should be sufficient.

RockZap DD statements

Required statements:

• SYSLIB points to the load library PDS (Partitioned Data Set) containing the load module you want to ZAP.
• SYSIN contains the ZAP control statements and must have the DCB attributes of RECFM=F or FB, and LRECL=80.
• SYSPRINT is the report data set.

RockZap sample JCL

//ROCKZAP JOB CLASS=A,MSGCLASS=A //ZAP EXEC PGM=ROCKZAP,PARM='RockZap parms' //STEPLIB DD DSN=ROCKZAP.V106.LOAD,DISP=SHR //SYSLIB DD DSN=loadlib,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSIN DD * zap control statements /*

Using RockZap under CMS

The format of the ROCKZAP command is:

ROCKZAP fn [ft [fm]] ( options

RockZap is invoked as a CMS command. Simply enter ROCKZAP followed by the name of the input file. The default filetype is "ZAP", and the default filemode is "*".

Options are supplied in any order following the left parenthesis. See "Options" for a list of options.

RockZap writes the report and any modified load modules to the disk accessed as the "A" disk. Make sure that the "A" disk is accessed in Read/Write mode.

Using RockZap with CMS text libraries

When RockZap processes a text library, the resulting text library or object files usually contain fewer records than the original. No information is lost and the resulting text library or object file is logically the same as the original. Text records in the object file are always written with the maximum amount of object code per record. Often, fewer records are required than are typically written by the compiler or assembler that originally generated the object. This object file 'normalization' is similar to how a linkage editor processes an object file. RockZap performs this normalization so that ZAPs can be applied more efficiently.

RockZap return codes

0	ZAPs were processed successfully. Any modified load modules are written back to disk.
4	ZAPs were processed successfully, but one or more warning messages were produced. This usually indicates a CSECT was missing from one or more of the load modules. Check the RockZap report for the name of the module and CSECT. If any load modules were modified, they are written back to disk.
8	One or more errors occurred. Check the RockZap report for details.
12	RockZap was unable to open the input file. Make sure the filename is correct and that the file or PDS member is present.
40	RockZap could not open the report file (SYSPRINT). For z/OS, make sure a DD statement for SYSPRINT is present. For CMS, the internal FILEDEF for SYSPRINT may have failed. Make sure the "A" disk is accessed in read/write mode.

Deprecated options

The following program options are no longer necessary. It is recommended that you not use them, and that if you discover them in old JCL or EXECs, you correct them to use the newer recommended approaches.

NOVERIFY

The NOVERIFY option allows you to apply ZAPs that have no verify data. Use the NOVERIFY option with caution. Once a ZAP is applied using NOVERIFY, the original contents of the load module are lost.

Note: Since the !NOVERIFY statement can provide the functionality needed for applying a portion of a zap without verify data, we strongly recommend that you do not use the NOVERIFY option, which might extend to other portions of the zap with incorrect verify data.

VERIFY

The VERIFY option ensures that all replace data has been successfully verified before updating the load module. The VERIFY option is a RockZap default and need not be specified.

Note: Since we recommend that you do not use the NOVERIFY option, you might want to avoid the VERIFY option as well, thus eliminating any tendency to control requirement of verify data at the job step level.