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:
  • 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 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: 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 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-S97             JUPEXIT                                *
      *                                                              *
      * (C) Copyright IBM Corp. 2009                                 *
      *                                                              *
      * CICS                                                         *
      * (Element of CICS Transaction Server                          *
      * for z/OS, Version 4 Release 2)                               *
      * @BANNER_END                                                  *
      *                                                              *
      * STATUS = 4.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 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
 


dfha6c0024.html | Timestamp icon Last updated: Monday, 5 June 2017