Options
- Determine the starting position for the OFFSET keyword
- 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.
- 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