You can use the control statements, CONTROL, OPTION, and END, to guide DFHJUP through the stages described in Using DFHJUP to read log streams.
Use the END statement as a delimiter to separate one group of tests (comprising one or more OPTION statements) from subsequent groups of tests on the next data set. When an END statement is encountered in the control input stream, the construction of record selection parameters ceases and the processing of input data records starts. Proper use of the END statement allows one execution of the utility program to perform a varied number of tests on one or more CICS® journal data sets.
You can use the statement, * or COMMENTS, to provide titles or comments on the output listings. Use it to include any information you think is helpful to identify tests or data. It has no effect on the utility program.
Each full keyword has a corresponding abbreviated form that you may use.
You can continue keyword operands of the DFHJUP statements on the next record, up to a maximum of 9 records, provided you code a nonblank character in position 72, and continue the operands in column 16 of the next statement. If a statement is not a continuation record of the preceding statement, the character in column 72 of that preceding statement must be a blank.
The CONTROL statement (see Figure 10) is optional, and you can omit it if the default operand values are satisfactory. It defines the ddnames to be used for the input and output data sets and the beginning and ending limits of the data set to be scanned. If you do not specify this statement, DFHJUP defaults to reading the input file named in a SYSUT1 DD statement. The optional output data set defined on the SYSUT4 DD statement is opened only if you specify the OPTION COPY function in the current group of tests, and also code the COND=E parameter.
1 10 16
CONTROL CNTL [{SKIP|K}={0|number}]
[,{STOPAFT|H}={
EOF
|number|(number,E)}]
[,{DDNAME|D}={SYSUT1|ddname}]
[,{DDNOUT|O}={SYSUT4|ddname}]
If you specify a value of zero, one record is
processed.
The default ddname of SYSUT1 is used if you do not code this keyword, and a SYSUT1 DD statement must be included in your job stream. If you code this parameter to specify a different ddname, your job stream must include the corresponding DD statement.
This keyword is used in conjunction with the OPTION COPY function, and you need only code this parameter if you want to use a ddname other than the default of SYSUT4. Coding DDNOUT, or the presence of SYSUT4 in the DFHJUP job stream, does not cause this data set to be used. An output data set is used only if OPTION COPY is specified with COND=E.
The OPTION statement (see Figure 11) defines the test or series of tests to be performed upon the data of the candidate record to determine whether it is selected. Each OPTION statement constructs one set of tests. You can specify one or more OPTION statements, in any combination, to define more closely the selection criteria and output processing to be performed against each input record. If you omit all keyword operands (except for EXITR and DDNAME), all records processed by stage 2 of DFHJUP are either written to the SYSPRINT data set, or copied to the specified output data set.
You can execute one or more tests on each logical record by coding the appropriate number of OPTION statements, creating the logical OR function. You can analyze records with the logical AND function by using the multifield test capability of the COND operand and the appropriate OPTION statements, creating a test series. Use the operands COND=M and COND=E to denote the beginning and ending, respectively, of a series for multifield testing of a record.
Each OPTION statement has its own output processing defaults. If you use multiple OPTION statements to create a multifield test series, final output processing is determined by the OPTION statement and its associated keywords that are defined along with the COND=E keyword.
1 10 16
OPTION {PRINT| [{OFFSET|O}={1|number}]
COPY|
NEGOF} [,{FLDTYP|T}={X|C}]
[,{VALUE|V}=string]
[,{FLDLEN|L}={1|number}]
[,{COND|C}={E|M|T{Y|N}|ET{Y|N}|MT{Y|N}}]
[,{EXITR|E}=name]
[,{DDNAME|D}={TRCPUNCH | ddname}]
[,{PRTSYS|P}={N|Y}]
[,NEWDCB]
Each option has two distinct functions:
If individual options are combined to form a multifield test, the use of OFFSET remains unchanged; however, output processing is determined by the option coded with the COND=E keyword.
All the following OPTION control statement keywords are optional:
Example: If VALUE=D9D6D6E3E2C5C7 (14 bytes) is specified with the FLDTYP=X parameter, the resultant VALUE= looks like this: ROOTSEG in EBCDIC characters or D9D6D6E3E2C5C7 in hexadecimal; in either case, the length is only 7 bytes.
If multiple test groups have specified the same exit routine, DFHJUP attempts to load the routine into storage for each group; therefore, the routine should be reenterable. Upon reaching end of file on input, a final call is made to the exit routine. You can determine if end of file was reached by checking for zeros in the parameter field.
The interface to the exit routine is as follows:
ENTRY:
EXIT:
This keyword can be used only with the OPTION COPY function. N is the default.
If you want to use NEWDCB against input data in the new format, that was introduced in CICS Transaction Server for OS/390 Version 1 Release 1, you can define an exit program to DFHJUP that modifies the format of the records to put an LLBB value at their start. Doing this allows the use of NEWDCB to copy the data into a different record format.
The following example exit program can be used to achieve this result. The program modifies the first word of each record, to replace it with an LLBB field, and also avoids returning CICS block header records, as they are for internal use by CICS. Define the exit program to DFHJUP using the EXITR= or E=OPTION statement.
****************************************************************
* *
* MODULE NAME = JUPEXIT *
* *
* DESCRIPTIVE NAME = Sample exit program for DFHJUP *
* *
* @BANNER_START 01 *
* Licensed Materials - Property of IBM *
* *
* 5655-M15 JUPEXIT *
* *
* (C) Copyright IBM Corp. 2009 *
* *
* CICS *
* (Element of CICS Transaction Server *
* for z/OS, Version 3 Release 2) *
* @BANNER_END *
* *
* STATUS = 3.2.0 *
* *
* Provide a sample exit routine for DFHJUP, to parse log *
* records and reject block header records. Adjust remaining *
* records to have an LLBB at their start. This means that *
* the remaining CICS TS log records returned by DFHJUP are *
* in RECFM=VB format, and so are eligible for blocking by *
* BSAM if COPY is used with a NEWDCB for the output dataset. *
****************************************************************
DFHREGS Establish register equates
JUPEXIT CSECT
STM R14,R12,12(R13) Save the registers
BASR R3,0 Establish base register
USING *,R3 Tell the assembler
ICM R4,15,0(R1) Address record
BZ EOF If plist empty then eof
CLC 0(0,R4),=CL4'>DFH' Test for block hdr record
BE EXITREJ If so, reject record
L R5,0(,R4) Pick up record length
SLL R5,16 Convert to LLBB format
ST R5,0(,R4) Store back at start
* WTO 'DFHJUP EXIT RAN' Diagnostic message
B EXIT Leave the program
EOF DS 0H
* WTO 'EOF ENCOUNTERED' Diagnostic message
EXIT DS 0H
LM R14,R12,12(R13) Restore the registers
SR R15,R15 Set a good return code
BR R14 Return to DFHJUP
EXITREJ DS 0H
LM R14,R12,12(R13) Restore the registers
LA R15,1 Set a bad rc (no base)
BR R14 Return to DFHJUP
DROP R3 Tell the assembler
LTORG Define the literal pool
END
................................................................
When you have defined all tests for the current input file, use END statement (see Figure 13) to initiate the tests.
Positions 10 and upward can be used for comments.
1 10 16
END [.....comments....]
The COMMENTS statement (see Figure 14) is optional. If used, it causes the contents to be displayed on the SYSPRINT data set.
1 10 16
*