The Extraction Control Utility allows a user to extract records for specific transaction
names, terminal identifiers or task numbers from the playback file into another playback file. This
is intended for transactional systems like CICS or IMS/TM where
multiple transaction might be embedded within the playback file.
The Extraction Control Utility is started using JCL. This utility allows a user to list the
transactions, terminals and task numbers found in the playback file or to extract specific
transaction records based on selection criteria. The JCL execution parameter ID is used to define
these criteria. The absence of this parameter will cause the Extraction Control Utility to produce a
list of transactions instead of extracting them.
During installation the customized procedure name BZUPECP was made for use. If a user wants to
use their own JCL, then the following description will assist in understanding the JCL
requirements.
To start the execution of the Extraction Control Utility, code a JCL execute statement for
program BZUPLAY. Four parameters are allowed for this execution: RUN, LANG, ID and REPLACE. Refer to
the Playback Setup and Execution section of this document for more information on these parameters.
The value for the RUN parameter needs to be the name of the Extraction Control Utility, which is
BZUECP. Typically, a user would code the execute statement like
this:
// EXEC PGM=BZUPLAY,PARM='RUN=BZUECP,ID=ABCD'
The absence of the ID parameter indicates that a list is produced instead of an extraction. This
list assists a user in the identification of the transactions that are stored within the playback
file. Once this identification has occurred, a user may define criteria on the ID parameter to
indicate which transactions are to be extracted and written to another data set. The ID parameter
defines the name of the transactions, terminals or the task numbers to be extracted. The transaction
name and the terminal identifier can be from 1 to 4 characters. The task number must be exactly 5
digits long requiring leading zeros if needed. This exact length for task numbers allows the
Extraction Control Utility to differentiate between a numeric transaction name or terminal
identifier from a task number. A comma-delimited list must be used if more than 1 identifier is
wanted and that list must be enclosed within parentheses. The maximum size of the total passed
parameter area is 80 characters, which limits the maximum number of ID identifiers to around 15 or
so. An example of requesting an extraction of all ABC, DEFG transactions and specific task number
122 could be coded like
this:
// EXEC PGM=BZUPLAY,PARM='RUN=BZUECP,ID=(ABC,DEFG,00122)'
Matching for transaction names or terminal identifiers is done by comparing them with the ID
parameter. If this parameter matches either the transaction name or the terminal identifier, then a
match will occur, and the records will be included in the extraction output to the file.
The REPLACE parameter with a value of Y allows the user to indicate to the utility that the
selected transactions are to be replaced by the contents of the BZUIN playback file. Instead of the
default method of including the selected transactions, a 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. An empty or non-empty BZUIN file can be used. 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.
The installation of
IBM® Z Virtual Test Platform placed program
BZUPLAY into the link list, as it is required to be APF-authorized. This BZUPLAY program will set up
the replay environment and then load and execute the required Extraction Control Utility under it.
For this loading to locate the BZUECP program, the JCL must include the location of the standard
distribution load library as STEPLIB. For
example:
//STEPLIB DD DISP=SHR,DSN=#hlq.SBZULOAD
A DD statement is used to define the location of the recorded playback file from which an
extraction is to occur. This can be a concatenation of multiple playback files if desired. The name
of the DD statement is BZUPLAY. For
example:
//BZUPLAY DD DISP=SHR,DSN=MY.PLAYBACK
A DD statement is used to define the location of the output playback file into which the selected
extraction records are to be written. The name of the DD statement is BZUOUT. For
example:
//BZUOUT DD DISP=SHR,DSN=MY.NEW.PLAYBACK
A DD statement is used to define the location of the optional input playback file from which the
records will be used to replace the first set of selected extraction records. The name of the DD
statement is BZUIN. This file can be empty of no records are to be inserted into the resulting
playback file. For example:
//BZUIN DD DISP=SHR,DSN=MY.OTHER.PLAYBACK
The human-readable formatted output from the utility is written to DD BZUMSG if it exists,
otherwise the output is written to the LE message spool file for the JOB. If you wish to control the
output's location, use the optional BZUMSG DD statement. If writing to a data set, the data set
requires a record format of VB, with a logical record length of at least 120. Some
examples:
//BZUMSG DD SYSOUT=*
//BZUMSG DD DISP=SHR,DSN=MY.OUTPUT
//BZUMSG DD DISP=(NEW,CATLG),DSN=MY.OUTPUT,
// DCB=(RECFM=VB,LRECL=256,BLKSIZE=260,DSORG=PS)