Control statements and return codes for DFHJUP

CONTROL statement

1         10       16

CONTROL   CNTL     [{SKIP|K}={0|number}]
                   [,{STOPAFT|H}={EOF|number|(number,E)}]
                   [,{DDNAME|D}={SYSUT1|ddname}]
                   [,{DDNOUT|O}={SYSUT4|ddname}]

The CONTROL statement 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.

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 embedded 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. If you do not specify this keyword, the default value of EOF is assumed.

number

must be specified in the range 0 through 9999999, with no embedded commas.

If you specify a value of zero, one record is processed.

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 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]

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:

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 for the T option, 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:

• REGISTERS
• R1 contains a pointer to a parameter list.
• R13 points to an empty save area.
• R14 contains a return address.
• R15 contains the exit routine entry address.
• PARMLIST
• The parameter list consists of 2 words. The first is a pointer to the candidate record; the second (with the high order bit on) is a pointer to the SYSPRINT data set DCB.

EXIT:

• Upon return from the exit routine, the contents of register 15 determine whether or not processing is to continue on this record.
• A nonzero value indicates that no further processing is to be done on this record, and selection tests start again against the next input record.
• A zero value indicates that this record is required, and output processing is now determined by the last OPTION statement encountered containing the COND=E keyword.
• If the EXITR keyword is omitted, processing continues as if a return code value of zero was received.

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. You can specify on the JCL that the output data set will be in variable blocked format. You might want to use NEWDCB to specify output data set attributes when your input log data has not been converted into COMPAT41 form. 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. 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 COMPAT41 format, 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            *
   .
   .
   .
      *                                                              *
      * 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 data set.   *
      ****************************************************************
               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 statement

When you have defined all tests for the current input file, use the END statement to initiate the tests.

Positions 10 and upward can be used for comments.

1         10       16

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

COMMENTS statement

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

1         10       16

*

DFHJUP return codes