Playback setup, execution, and parameters

To facilitate the replaying of the user applications along with the collected data, the replay side of the product must be used. The #hlq.SBZULINK load library contains the main replay module named BZUPLAY. This replay module must run APF-authorized and the load library must be part of the link list or LPA. The replay program when executed, will set up the replay environment and then load and execute the appropriate runner program.

The typical set of JCL to execute the replay side is to include in the STEPLIB the load library containing the standard load module library for this product concatenated with the user load libraries required for execution. These user load modules are the exact same modules that were used in the original environment. No changes are required to be made, although the user programs can have the logic modified and then be used with the recorded data to verify outcomes. If your application being replayed is a batch/Db2 program, then you must also include the #hlq.SBZULMOD load library.

If you use any of the optional replay features, such as native file I/O QSAM or VSAM (KSDS, ESDS or RRDS) or forcing the date/time to be that of the recording, then you must also include the #hlq.SBZULLEP load library and activate the desired feature (see parameters on the PARM statement below).

Included in the JCL is the BZUPLAY DD statement that will point to at least one of the sequential recorded datasets previously created. Multiple recording datasets can be concatenated if desired. This concatenation could be typical for CICS environments as the runner will dynamically extract the next logical set of recorded data records based upon the task number, thus logically separating each transaction during the replay processing.

To resolve a request from the user application program, the runner will look for data specific to the call intercepted at replay time from the recorded data. If it is not located in the recorded data, the runner will check to see if there are any Associated Test Case exit points defined for the specific intercepted function. By using these two locations for obtaining data, it is possible to use 100% recorded data, 100% exit point data or any combination in between. A user could provide all the data to be returned to the program calls through an exit point call and have a completely empty recorded file. The IBM Developer for z/OS (IDz) provides support for this feature.

If the replay scenario is to use Associated Test Case exit points or if program-to-program interception was recorded and is still wanted during replay, then a configuration file is needed, otherwise it is optional. The configuration file is by defined through an BZUCFG DD statement which is to point at the required configuration file. In replay mode this file can be either a sequential dataset or a PDS member.

Additionally, if Associated Test Case exit points are to be used then the BZUCBK DD statement must point to a list of load libraries that contain the Associated Test Case programs. This set of modules will be dynamically loaded based upon a configuration file setting for when member names are to be included.

For any Test Case programs written in the PL/1 language, both BZUCBK and STEPLIB must reference the load libraries containing the PL/1 Test Case programs. In this case, BZUCBK is used to locate the desired Test Case programs and STEPLIB is used to satisfy the LE Fetch of the PL/1 program.

The output from the execution will be written to the LE spool file for the JOB unless it has been redirected to the optional BZUMSG DD statement. If redirection is desired, then point it at a variable blocked dataset with a logical record length of at least 120.

During installation the customized procedure name BZUPPLAY was made for use. If a user wants to use their own JCL, then the following sample shows JCL for executing the replay side and invoking the runner.
//         EXEC PGM=BZUPLAY,PARM='option=value,option=value'
//STEPLIB  DD DISP=SHR,DSN=#hlq.SBZULOAD
//                DD DISP=SHR,DSN=#hlq.SBZULMOD      (used with optional, and batch/Db2 replay only)
//                DD DISP=SHR,DSN=#hlq.SBZULLEP         (used with optional, and batch replay)
//                DD DISP=SHR,DSN=MY.CICS.LOADLIB
//BZUPLAY  DD DISP=SHR,DSN=MY.PLAYBACK
//SYSOUT   DD SYSOUT=*                                  (this keeps LE output in one spool file)
//BZUMSG  DD SYSOUT=*                                 (optional, can be a VB output dataset)
//BZUCFG   DD DISP=SHR,DSN=#hlq.SBZUSAMP(BZUSCFG)    (optional)
//BZUCBK   DD DISP=SHR,DSN=MY.TESTCASE.LOADLIB        (optional, location of dataset load libraries containing the test case load modules)
The following parameters can be specified on the PARM argument of the JCL execute statement.
Parameter Used by Description
CMA BZUMCP A value of YES for this parameter causes the Associated Test Case Generation program to specifically create the exit point for the CICS_CMA exit. This parameter can be combined with parameters CWA, PLT, TUA and TWA if desired.
CWA BZUMCP A value of YES for this parameter causes the Associated Test Case Generation program to specifically create the exit point for the CICS_CWA exit. This parameter can be combined with parameters CMA, PLT, TUA and TWA if desired.
CWASIZE Replay This parameter allows a user to alter the default size (512) of the CWA to be created. If this parameter is not provided, then the size of the CWA in the recording is used.
ELAPSED Replay A value of YES for this parameter caused elapsed time tracing between subsystem calls to be produced in the output during replay. This should be used along with the TRACE=YES option. This elapsed time tracing option is useful for identifying performance problems in user applications.
ID BZUECP This parameter is used by the Extraction Control Utility exclusively and allows the user to define a list of one or more search criteria to be used for record selection when creating a subset playback file. Possible values are a 1 to 4-character transaction name, a 1 to 4-character terminal identifier or a 5-digit task number (with leading zeros if necessary). If multiple values are wanted, then they are separated by commas and enclosed by parentheses.
INIT Replay This parameter sets a hex value (2-character code) to be used for any uninitialized CICS application GETMAINs. This is useful in problem determination as uninitialized memory pieces can be identified more easily. The default is 00, however for debug purposes a value of EE is suggested.
LANG All This parameter sets a 2-character code to be used to load the correct language module for the replay messages. Currently EN (for English) is the only supported value, but more languages are being considered for the future. The default is EN.
LIST BZUDCP This parameter will instruct the Playback Dump Utility to dump all data for the record and its arguments instead of limiting the output to the first 60 characters.
MODE Replay Normally, the recorded playback file has recorded the environment that was used to collect the data. However, in the case of batch, it might be unknown. In that case, a value can be specified to tell the runner what environment to set up. Values can be BTCH (standard batch), CICS, DLIP (batch with DL/I) or DB2P (batch with Db2). It is not usual to have to set this value.
NAME Replay Some user applications inspect the operating system JSCB control block for the program name that is currently running, usually to see if they are running under IMS. During replay, the name in this JSCB field will be BZUPLAY. This can be dynamically changed to any desired value by using the NAME= parameter.
PCBS Replay For IMS, the runner will create pseudo-PCBs that are used during replay. The recorded data does not know how many PCBs were in the original PSB. Because of this, the runner automatically creates 100 PCBs for use during replay. If the user needs more, then this parameter can be specified with a larger, more appropriate value. The runner will allocate 348 bytes per PCB that is created and defining many PCBs will cause a large amount of memory to be acquired.
PLT BZUMCP A value of YES for this parameter causes the Associated Test Case Generation program to specifically create the exit point for the CICS_PLT exit. This parameter can be combined with parameters CMA, CWA, TUA and TWA if desired.
PROGRAM Replay Normally, the recorded playback file contains the name of the user application that is to execute during replay. It is possible that the recording will not know the name of the program, if for example it was not an LE program. If the program name is unknown, a user may specify the name of the program to invoke first by using this parameter.
READ Replay During replay, logical playback records are read into storage to a maximum limit of 1600. This is to prevent too much memory being required in case a huge number of records are in the playback file for the batch program or CICS or IMS transaction. As the replaying progresses, used records will be freed and more will be read to fill the buffer. If less logical records are wanted to decrease the memory requirements, then specify the decreased numeric limit. If more logical records are wanted to help enable special program ignoring features, then specify the increased numeric limit.
REPLACE BZUECP This parameter is used by the Extraction Control Utility exclusively and allows the user to indicate to the utility that the selected transactions are to be replaced by the contents of the BZUIN playback file. The value of N (the default) indicates that the selected transactions are to be extracted and written to the BZUOUT playback file. The value of Y indicates that the selected transactions are to be excluded and that all other records are to be copied to the BZUOUT playback file with the contents of the BZUIN playback file is to be inserted at the location of the first matched (excluded) record. By using this parameter, a user can create new playback files from existing ones that either include or exclude identified transactions and optionally insert other playback records.
REPLAY Replay

There are 2 replay modes that can be used. The default mode is S (sequential), which means that the recorded data is returned in the same order as was originally recorded. Record skipped is still allowed if the user program was altered to remove some of the calls.

An alternate mode is D (dynamic) which means that during replay processing, the recorded data is logically matched to find the proper recorded data to return for the call. This is done based on argument matching and positioning within the file. The benefit of using dynamic mode, is that it allows a user to alter the order of CICS, IMS, Db2 and MQ calls within the user program, without having to re-record the playback data. Simple changes to user program code will still process. Calls can even be skipped but if new calls are introduced that have no recorded data and no exit point, then the process is unable to proceed. The runner cannot manufacture data.

It is important to understand that the dynamic mode has a default tolerance level of 0, meaning that there must be an exact match for the recorded record to be returned. Sequential mode is more tolerant but could produce more warnings. A user may alter the tolerance level by using the TOLERANCE parameter, described below.

REPORT Replay This parameter is used exclusively with test case invocation. A value of XML for this parameter causes XML-style result information to be written to the BZURPT DD statement. If no BZURPT DD statement is defined in the JCL, then output will be written to a dynamically allocated output spool file. The DCB information for this file is VB, with any LRECL of at least 120.
RUN

BZUDCP

BZUECP

BZUMCP

This sets the name of the runner program to use. The default is BZURUN, which is used for replaying recorded data and programs. Other utility programs that come with this product are started by using an alternate value for RUN, such as BZUDCP, BZUECP or BZUMCP.
STOP Replay This sets the error level that will force termination of the current replay. If the replay is part of a TESTCASE that has multiple tests, then this will only stop the current test in progress and allow the next test to start. The possible values are W (for warning level), E (for error level) and S (for severe level), which refer to the level of any messages that are produced. The default value of S, which means that a severe error message will cause termination of the process.
TCTUASIZE Replay This parameter allows a user to alter the default size (0) of the TCTUA to be created. If this parameter is not provided, then the size of the TCTUA in the recording is used.
TIMESTAMP Replay

This optional feature parameter allows a user to define how the date and time are to be returned for COBOL or PL/1 direct calls. Direct calls are ones made to the COBOL or PL/1 language itself, instead of using other facilities such as CICS ASKTIME. Typically, for COBOL this would be though the ACCEPT verb. The parameter can be defined as R (the default) meaning that the original recorded date and time are to be returned, C meaning that the current date and time are to be returned, or a value in the form of YYYYMMDDHHMMSSFFF. If a value is specified, it is only checked to ensure it is numeric. If it is not numeric, then it is ignored, and the default will be used. Example values are TIMESTAMP=R, TIMESTAMP=202003111345000.

If the value of R is specified or defaulted, then the date and time will be updated on every CICS call to the original value. For batch and IMS/BMP programs the date and time is set once at the beginning of the batch replay. For IMS/TM transactions the date and time is set only at the beginning of the transaction.

In order for this optional feature to be activated, the #hlq.SBZULLEP load library must be in STEPLIB, before any references to LE libraries.

TOLERANCE Replay This allows a user to define the maximum number of bytes (default is 0) that can mismatch in the arguments, before it is rejected. Any mismatch count above the specified value, will result in the recorded record from being rejected. Care should be given in setting this value as it directly affects the selection of the record to use.
TRACE Replay Specify a value of N (the default) to prevent tracing messages from being written. Specify a value of Y to cause tracing messages to be written. Specify a value of I to get internal tracing messages, in addition to standard tracing messages to be written. Typically, a user would use the default or specify Y. Trace messages are internally collected during execution, whether tracing has been set on or off. In the event of an error or abend that causes premature termination, the most recent 1000 trace messages are written, to assist in problem determination.
TUA BZUMCP A value of YES for this parameter causes the Associated Test Case Generation program to specifically create the exit point for the CICS_TUA exit. This parameter can be combined with parameters CMA, CWA, PLT and TWA if desired.
TWA BZUMCP A value of YES for this parameter causes the Associated Test Case Generation program to specifically create the exit point for the CICS_TWA exit. This parameter can be combined with parameters CMA, CWA, PLT and TUA if desired.
UTF Replay This option is used with the REPORT option and allows a user to specify whether the generated XML output is to be written as EBCDIC (value N), UTF-8 (value Y) or defaulted to the same code set (UTF-8 or EBCDIC) defined by the BZUCFG’s file code set.