Utility control statements for DFHJUP

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.

CONTROL statement

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.

Figure 10. The DFHJUP CONTROL statement
1         10       16

CONTROL   CNTL     [{SKIP|K}={0|number}]
                   [,{STOPAFT|H}={Start of changeEOFEnd of change|number|(number,E)}]
                   [,{DDNAME|D}={SYSUT1|ddname}]
                   [,{DDNOUT|O}={SYSUT4|ddname}]
SKIP= or K=
defines the first record tested. All prior records are ignored. If this keyword is not specified, a default value of zero is used and causes the first record on the input file to be tested.
number
must be specified in the range 0 through 999999, and cannot have imbedded commas.
STOPAFT= or H=
defines the last record to be tested. When this value has been reached by counting processed records, the current group of tests is terminated. Start of changeIf you do not specify this keyword, the default value of EOF is assumed.End of change
number
must be specified in the range 0 through 9999999, with no imbedded commas.

Start of changeIf you specify a value of zero, one record is processed.End of change

EOF
denotes end-of-file condition; allows record processing beyond the stated maximum of 99999999 records.
E
causes records to be counted for test sequence termination only if they satisfy selection criteria. Otherwise, all records read (after the SKIP value) are counted.
DDNAME= or D=
identifies the ddname for the input data set for the current group of tests.

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.

DDNOUT= or O=
identifies the ddname for the optional output data set for the current group of tests.

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.

OPTION statement

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.

Figure 11. The DFHJUP OPTION statement
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]

Options

Each option has two distinct functions:

  1. Determine the starting position for the OFFSET keyword
  2. Determine the output processing to be performed.

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.

PRINT
causes all selected records to be displayed on the SYSPRINT data set.
COPY
causes all selected records to be transferred to the specified output data set. You can also write these records on the SYSPRINT data set by coding the PRTSYS keyword.
NEGOF
causes the OFFSET keyword value to be used as a negative offset from the end of the journal record. All records selected using this function are displayed on the SYSPRINT data set.

All the following OPTION control statement keywords are optional:

OFFSET= or O=
defines the location in the record of the first byte of the field to be tested. The default is position 1 of the record.
number
can be in the range from 1 up to and including the length of the record under test. Maximum value is 32767 bytes, and no checking is performed to determine if the logical record length is exceeded.
Note:
If DSECTs are used to locate values in control records or blocks, you must adjust the starting value for the OFFSET parameters. Most DSECTs start with a relative value of zero, while the value specified in the OFFSET keyword is always expressed as relative to byte 1.
FLDTYP= or T=
defines the type of data in the VALUE=field.
X
data to be treated as hexadecimal pairs. The test data is packed (2 bytes into 1 to form hexadecimal equivalents). This is the default value.

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.

C
data to be treated as EBCDIC characters. DFHJUP uses the data as coded in the OPTION statement, without alterations.
VALUE= or V=
defines those characters that comprise the test field. If you specify FLDTYPE=X, you must enter this data as hexadecimal character pairs. For a ‘test under mask’ condition, a single pair must represent the hexadecimal value for the test. If you specify FLDTYP=C, you must enter the value data as EBCDIC characters. However, if a blank or comma character is to be included in the value, you must specify FLDTYP=X, and code the value operand as hexadecimal characters, using X'40' for the blank and X'6B' for the comma, as appropriate.
string
cannot exceed 255 EBCDIC or 510 hexadecimal characters. The length of this field is set by the value of the FLDLEN= keyword and not by the number of non-null characters in this field.
FLDLEN= or L=
defines the number of characters to be used from the test field.
number
represents the actual number of bytes to be used, not the number of characters specified in the VALUE= keyword. The acceptable range of values for this field is from 1 up to and including 255. The default is 1.
COND= or C=
defines the type of test and its relationship to other tests in the group. If this keyword is not specified, the default is COND=E.
E
marks the last (or only) element in a test series. Any OPTION control statements appearing after this form a new series of tests. Coding an E to terminate a test series allows DFHJUP to perform various tests on each record, and each test series can be used on different fields within the record. Final output processing is determined by the OPTION function defined with this keyword value.
M
indicates that this is a multifield test. That is, more than one test is to be made on each input record. All tests in this series must be satisfied for record selection and output processing to begin.
T
causes the VALUE= byte to be used as a test-under-mask value, instead of as a compare field. Only the first byte (two hexadecimal characters if FLDTYP=X) of the VALUE= field is used. If FLDTYP=C is used, the hexadecimal equivalent of the EBCDIC character is the test value. If you code COND=T, you must not specify the FLDLEN= keyword and DFHJUP assumes a default length of 1.
Y
indicates that, for the test under mask to be considered satisfied, there must be a bit in the record test field for each corresponding bit of the test byte. This is equivalent to a branch-if-ones test.
N
indicates that, for the test under mask to be considered satisfied, there must not be a bit in the record test field for any of the corresponding bits of the test byte. This is equivalent to a branch-if-zeros test.
MT
defines a test-under-mask option as described above for T, but with the properties of a multifield test as described for M. Because the T parameter causes FLDLEN to default to 1, the MT parameter must be used for a multifield test that starts with a test-under-mask value.
ET
signifies that a multifield test series ends with a test-under-mask condition.
EXITR= or E=
specifies the entry point name of an exit routine that is to be given control when a candidate record has satisfied all selection criteria for the current test.

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:

DDNAME= or D=
defines the output data set used by the DL/I call trace journal record retrieval routine for whenever it has been specified as the user exit routine. A corresponding DD statement must be supplied.
PRTSYS= or P=
determines whether to print all the selected records on the SYSPRINT data set.
N
indicates that no printing of selected records is to be done.
Y
indicates that all records transferred to the output data set are also formatted and printed.

This keyword can be used only with the OPTION COPY function. N is the default.

NEWDCB
To ignore the DCB information from the original data set, specify NEWDCB when using the COPY function. Supply the new DCB information on the JCL for the output data set. You can use this process to create an output data set in COMPAT41 mode from a logstream that is in the format introduced at CICS Transaction Server for OS/390®, Version 1 Release 1. You can specify on the JCL that the output data set will be in variable blocked format.
Note:
Start of change
You may want to use NEWDCB to specify output data set attributes when your input log data has not been converted into COMPAT41 form. That is, the data is in the newer log data format introduced in CICS Transaction Server for OS/390 Version 1 Release 1. Using NEWDCB to COPY data to a BSAM data set means that the data must conform to the various access method restrictions and requirements. For example, BSAM data cannot exceed 32 KB in size. Also, data copied to a variable, or variable blocked, data set (recfm=V or recfm=VB) using NEWDCB, requires the data to be in variable format. This means that the newer log record format will cause DFHJUP to fail with an S002 if used on a copy step with NEWDCB, because the input data is not in a variable format as its records do not begin with an LLBB fullword.

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.

End of change
Start of changeFigure 12. Sample exit program for DFHJUP
****************************************************************
      *                                                              *
      * 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
      ................................................................
End of change

END statement

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.

Figure 13. The DFHJUP END statement
1         10       16

END       [.....comments....]

COMMENTS statement

The COMMENTS statement (see Figure 14) is optional. If used, it causes the contents to be displayed on the SYSPRINT data set.

Figure 14. The COMMENTS statement
1         10       16

*

Related reference
Reading log streams using batch jobs (for example, DFHJUP)
SUBSYS=(LOGR,DFHLGCNV,...) keyword
Using DFHJUP to read log streams
DD statements for DFHJUP or your own batch job
DFHJUP return codes
Managing the size of log streams
Log data accessible to DFHJUP
Diagnostic information in DFHJUP output
Examples of using DFHJUP
[[ Contents Previous Page | Next Page Index ]]