The following examples illustrate some of the ways in which DFHJUP can be used. Each makes reference to a CICS® log stream. However, this utility can be used with any data set that can be processed using QSAM.
For clarity, all option keywords have been specified in their full form, and many are coded where the default could be taken. Use of the short form and keyword defaults will greatly reduce the required input. In each of the two main examples, the COMMENT statement has been used to describe the function being performed.
Figure 17 shows the JCL and control statements required to print to the output data set all the records written during a one-week period to a CICS general log.
//JNLPRNT1 JOB (accounting information),CLASS=A
//PRNTJNL EXEC PGM=DFHJUP
//STEPLIB DD DSNAME=CICSTS31.CICS.SDFHLOAD,DISP=SHR
//SYSPRINT DD SYSOUT=A,DCB=RECFM=FBA
//SYSUT1 DD DSNAME=CICSDA#.CICSDA1.JRNL054,
// DCB=BLKSIZE=32760,
// SUBSYS=(LOGR,DFHLGCNV,
// 'FROM=(1995/001,06:00),TO=(1995/007,23:59),LOCAL')
//SYSIN DD *
*-----------------------------------------------------*
* CONTROL STATEMENT : DEFAULTS *
* INPUT = SYSUT1 *
* OUTPUT = SYSPRINT *
* SELECTION QUALIFIERS : *
* 1. DEFAULT = ALL INPUT RECORDS *
*-----------------------------------------------------*
OPTION PRINT
END
*-----------------------------------------------------*
/*
Figure 18 shows the JCL and control statements required to copy to the output data set all the records written to a CICS general log. The records are copied in the CICS/ESA 4.1 format, and then deleted from the log stream. Note that there are two jobsteps, the first to perform the copy step, and the second to perform the delete step. The delete step is dependent upon the copy step completing successfully. Also, the same TO= value is specified on both jobstep's SUBSYS card. This ensures that both jobs manipulate the same range of log data. If TO= is omitted, and allowed to default to the current end of the logstream, there is the possibility of new log data being written to the logstream after the copy step, but before the delete step; this would then be deleted. To avoid this, it is recommended that the same TO= value be used for both jobsteps. Also, to avoid having to modify the TO= value every time the job is submitted, the year and Julian date are not specified. This causes the job to default to today's date. Therefore, the recommendation is to submit the job soon after the time specified on the TO= value. It should be noted that a TO= value close to midnight may cause problems. If the copy step were to run just before midnight, and the delete step just after midnight, the TO= value would default to different days, and there would be the potential for uncopied data being deleted.
//JNLCOPY1 JOB (accounting information),CLASS=A
//COPYJNL EXEC PGM=DFHJUP
//STEPLIB DD DSNAME=CICSTS31.CICS.SDFHLOAD,DISP=SHR
//SYSPRINT DD SYSOUT=A,DCB=RECFM=FBA
//SYSUT1 DD DSNAME=CICSAA#.CICSDC1.JRNL001,
// DCB=BLKSIZE=32760,
// SUBSYS=(LOGR,DFHLGCNV,'TO=(,10:00)',COMPAT41)
//SYSUT4 DD DSNAME=EXAMPLE1.COPY1,DISP=(NEW,CATLG),
// UNIT=SYSDA,VOL=SER=USRPAK,
// SPACE=(TRK,(3,1))
//SYSIN DD *
*-----------------------------------------------------*
* CONTROL STATEMENT : DEFAULTS *
* INPUT = SYSUT1 *
* OUTPUT = SYSUT4 *
* SELECTION QUALIFIERS : *
* 1. DEFAULT = ALL INPUT RECORDS *
*-----------------------------------------------------*
OPTION COPY
END
//CHKCOPY IF (COPYJNL.RC = 0) THEN
//IEFBR14 EXEC PGM=IEFBR14
//LOGSTRM DD DSNAME=CICSAA#.CICSDC1.JRNL001,
// SUBSYS=(LOGR,DFHLGCNV,'TO=(,10:00)',DELETE)
//CHKCOPY ENDIF
*-----------------------------------------------------*
/*
The next example shows how to delete a log-stream tail without reading the log stream.
//DELTAIL JOB (accounting information),CLASS=A
//IEFBR14 EXEC PGM=IEFBR14
//LOGSTRM DD DSNAME=CICSAA#.CICSDC1.JRNL001,
// SUBSYS=(LOGR,DFHLGCNV,'TO=(1995/229,09:30)',DELETE)
Figure 20 shows the JCL and control statements required to take two copies of the same log stream partition, using the SETBRCUR and REPBRCUR options, and then to delete the log stream partition using the DELBRCUR option.
//ARCHJNL JOB (accounting information),CLASS=A
//ARCHJNL1 EXEC PGM=DFHJUP
//STEPLIB DD DSNAME=CICSTS31.CICS.SDFHLOAD,DISP=SHR
//SYSPRINT DD SYSOUT=A,DCB=RECFM=FBA
//SYSUT1 DD DSNAME=CICSAA#.CICSDC1.JRNL001,
// DCB=BLKSIZE=32760,
// SUBSYS=(LOGR,DFHLGCNV,
// 'TO=(,12:00),GMT',
// 'COMPAT41,SETBRCUR')
//SYSUT4 DD DSNAME=JRNL001.ARCHIVE1,DISP=(NEW,CATLG),
// UNIT=SYSDA,VOL=SER=USRPAK,
// SPACE=(TRK,(3,1))
//SYSIN DD *
*-----------------------------------------------------*
* CONTROL STATEMENT : DEFAULTS *
* INPUT = SYSUT1 *
* OUTPUT = SYSUT4 *
* SELECTION QUALIFIERS : *
* 1. DEFAULT = ALL INPUT RECORDS *
*-----------------------------------------------------*
OPTION COPY
END
//ARCHJNL2 IF (ARCHJNL1.RC = 0) THEN
//ARCHJNL1 EXEC PGM=DFHJUP
//STEPLIB DD DSNAME=CICSTS31.CICS.SDFHLOAD,DISP=SHR
//SYSPRINT DD SYSOUT=A,DCB=RECFM=FBA
//SYSUT1 DD DSNAME=CICSAA#.CICSDC1.JRNL001,
// DCB=BLKSIZE=32760,
// SUBSYS=(LOGR,DFHLGCNV,,REPBRCUR)
//SYSUT4 DD DSNAME=JRNL001.ARCHIVE2,DISP=(NEW,CATLG),
// UNIT=SYSDA,VOL=SER=USRPAK,
// SPACE=(TRK,(3,1))
//SYSIN DD *
*-----------------------------------------------------*
* CONTROL STATEMENT : DEFAULTS *
* INPUT = SYSUT1 *
* OUTPUT = SYSUT4 *
* SELECTION QUALIFIERS : *
* 1. DEFAULT = ALL INPUT RECORDS *
*-----------------------------------------------------*
OPTION COPY
//ARCHJNL2 ENDIF
//JNLDEL JOB (accounting information),CLASS=A
//IEFBR14 EXEC PGM=IEFBR14
//LOGSTRM DD DSNAME=CICSAA#.CICSDC1.JRNL001,
// SUBSYS=(LOGR,DFHLGCNV,,DELBRCUR)
//*
Depending on whether COMPAT41 has been specified on the SUBSYS parameter, log stream journal records are presented either:
The OPTION parameters can be used to select specific types of records from a journal. You need to specify the offset within the record at which these specific record types lie. These offsets are different between the two different formats-CICS/ESA 4.1 and CICS Transaction Server for z/OS, Version 3 Release 1.
See the CICS Customization Guide descriptions of the formats and offsets of fields in journal record headers.
There are tables at the end of this section to help you define the OPTION statements that you need. Example statements are included here to illustrate some of the types of record selection that can be achieved in this way.
If all the file control records were to be found, for example, the OPTION statement has the following form:
//SYSIN DD *
OPTION PRINT OFFSET=43,FLDTYP=C,VALUE=FC,FLDLEN=2,COND=E
END
/*
The offset to this field, GLRH_REC_COMPID, is 39. If FLDTYP=C is used in the parameters, this value can be entered in its character form, as shown in the example above, for the component ID for file control, FC.
The task number appears as a three byte packed decimal value in a journal record. It must appear in the same form in the VALUE parameter. To do this take the actual task number, in this case 25, and turn it into a five digit decimal value by filling up the left hand side with zeros: 00025. Then add a capital letter C to the right hand end to show its a positive value: 00025C. The following statements will cause all records belonging to task 25 to be directed to the SYSPRINT data set:
//SYSIN DD *
OPTION PRINT OFFSET=34,FLDTYP=X,VALUE=00025C,FLDLEN=3,COND=E
END
/*
The transaction identifier appears as a 4-byte hexadecimal field in the journal records. If FLDTYP=C is used in the parameters then this value can be entered in its character form as shown below, for a transaction called TRN1.
//SYSIN DD *
OPTION PRINT OFFSET=29,FLDTYP=C,VALUE=TRN1,FLDLEN=4,COND=E
END
/*
Alternatively, the hexadecimal equivalent for these characters could be used, with FLDTYP=X, as shown in the next example.
//SYSIN DD *
OPTION PRINT OFFSET=29,FLDTYP=X,VALUE=E7F0F0F5,FLDLEN=4,COND=E
END
/*
At CICS Transaction Server for z/OS, Version 3 Release 1, if you intend to select journal records for a particular time, you are recommended to use the time selection options on the SUBSYS parameter.
The terminal identifier is a 4-byte value which can be entered as four characters or their hexadecimal equivalent, in the same way as a transaction identifier. In this example all the records from terminal T004 are to be selected and printed.
//SYSIN DD *
OPTION PRINT OFFSET=37,FLDTYP=C,VALUE=T004,FLDLEN=4,COND=E
END
/*
Suppose you wanted to print all the file control records for a particular task. This needs two OPTION statements. The COND=M parameter performs the AND operation on the two statements.
//SYSIN DD *
OPTION PRINT OFFSET=34,FLDTYP=X,VALUE=00025C,FLDLEN=3,COND=M
OPTION PRINT OFFSET=43,FLDTYP=C,VALUE=FC,FLDLEN=2,COND=E
END
/*
The example shows how to search for all records which belong to task number 25 and have a component ID of FC.
If more than one type of record is to be found then the form of the following example could be used.
In this case, all the user journal records written with JTYPEID CP for transaction TRN5 are selected. The OPTION statements are ‘ANDed’ together.
//SYSIN DD *
OPTION PRINT OFFSET=43,FLDTYP=C,VALUE=UJ,FLDLEN=2,COND=M
OPTION PRINT OFFSET=61,FLDTYP=C,VALUE=CP,FLDLEN=2,COND=M
OPTION PRINT OFFSET=29,FLDTYP=C,VALUE=TRN5,FLDLEN=4,COND=E
END
/*
If all the file control records were to be found, for example, the OPTION statement has the following form:
//SYSIN DD *
OPTION PRINT OFFSET=6,FLDTYP=X,VALUE=11,FLDLEN=1,COND=E
END
/*
The offset to this field, the module identifier, is 6. It is a numeric (X) type of field, of length 1 byte. For file control, this value equates to X'11' as listed in the CICS Customization Guide.
The task number appears as a three byte packed decimal value in a journal record. It must appear in the same form in the VALUE parameter. To do this take the actual task number, in this case 25, and turn it into a five digit decimal value by filling up the left hand side with zeros: 00025. Then add a capital letter C to the right hand end to show its a positive value: 00025C. The following statements will cause all records belonging to task 25 to be directed to the SYSPRINT data set:
//SYSIN DD *
OPTION PRINT OFFSET=16,FLDTYP=X,VALUE=00025C,FLDLEN=3,COND=E
END
/*
The transaction identifier appears as a 4-byte hexadecimal field in the journal records. If FLDTYP=C is used in the parameters then this value can be entered in its character form as shown below, for a transaction called TRN1.
//SYSIN DD *
OPTION PRINT OFFSET=23,FLDTYP=C,VALUE=TRN1,FLDLEN=4,COND=E
END
/*
Alternatively, the hexadecimal equivalent for these characters could be used, with FLDTYP=X, as shown in the next example.
//SYSIN DD *
OPTION PRINT OFFSET=23,FLDTYP=X,VALUE=E7F0F0F5,FLDLEN=4,COND=E
END
/*
The time must be entered in the form hhmmsss+ as a series of decimal digits and where the + sign is represented by the letter F. The utility does not support the use of the ‘greater than’ or ‘less than’ logical operators, so searching using a time stamp value is of limited use.
//SYSIN DD *
OPTION PRINT OFFSET=19,FLDTYP=X,VALUE=1446591F,FLDLEN=4,COND=E
END
/*
The terminal identifier is a 4-byte value which can be entered as four characters or their hexadecimal equivalent, in the same way as a transaction identifier. In this example all the records from terminal T004 are to be selected and printed.
//SYSIN DD *
OPTION PRINT OFFSET=27,FLDTYP=C,VALUE=T004,FLDLEN=4,COND=E
END
/*
Suppose you wanted to print all the file control records for a particular task. This needs two OPTION statements. The COND=M parameter performs the AND operation on the two statements.
//SYSIN DD *
OPTION PRINT OFFSET=16,FLDTYP=X,VALUE=00025C,FLDLEN=3,COND=M
OPTION PRINT OFFSET=6,FLDTYP=X,VALUE=11,FLDLEN=1,COND=E
END
/*
The example shows how to search for all records which belong to task number 25 and have a system type ID of X'11'.
If more than one type of record is to be found then the form of the following example could be used.
In this case, all the file control records for task 48 are selected together with all the records generated by the TRN6 transaction. The first two OPTION statements are ‘ANDed’ together, whereas the third statement is a separate search because the second statement is terminated by COND=E.
//SYSIN DD *
OPTION COPY OFFSET=6,FLDTYP=X,VALUE=11,FLDLEN=1,COND=M
OPTION COPY OFFSET=16,FLDTYP=X,VALUE=00048C,FLDLEN=3,COND=M
OPTION COPY OFFSET=23,FLDTYP=C,VALUE=TRN6,FLDLEN=4,COND=E
END
/*
Field name |
OFF SET |
FLD TYP |
VALUE (example) |
FLD LEN |
Contents |
---|---|---|---|---|---|
GLRH_RECORD_LENGTH | 1 | X | 00000100 | 4 | Length of record |
GLRH_HEADER_LENGTH | 5 | X | 0000003B | 4 | Length of header |
GLRH_REC_DATA_LEN | 9 | X | 0050 | 4 | Record data length |
GLRH_GMT | 13 | X | 8 | Time (GMT) | |
GLRH_LOCAL | 21 | X | 8 | Time (local) | |
GLRH_TRAN_ID | 29 | C | TRN1 | 4 | Transaction identifier |
GLRH_TRAN_ID | 29 | X | E3D9D5F1 | 4 | alternative format |
GLRH_TASK_ID | 33 | X | 0000025C | 4 | Task Number |
GLRH_TERM_ID | 37 | C | T004 | 4 | Terminal identifier |
GLRH_TERM_ID | 37 | X | E3F0F0F4 | 4 | alternative format |
GLRH_REC_TYPE | 41 | X | 0001 | 2 | Record type |
GLRH_REC_COMPID | 43 | C | FC | 2 | Component ID |
GLRH_REC_JOURNAL | 45 | C | JRNL0001 | 8 | Journal name |
53 | X | 81 | 1 | Start of task/start of UOW |
Field name | OFFSET | FLDTYP | VALUE (example) | FLDLEN | Contents |
---|---|---|---|---|---|
JCRLL | 1 | X | 0037 | 2 | Length of record |
JCRSTRID | 5 | X | EF59 | 2 | System type ID |
JCRSTRID | 5 | X | EF | 1 | Function identifier |
JCRSTRID | 6 | X | 59 | 1 | Module identifier |
JCRUTRID | 7 | X | 12EF | 2 | User type ID |
JCRLRN | 9 | X | 002C | 2 | Record number within block |
JCSPLL | 11 | X | 0014 | 2 | Length of system prefix |
JCSPTASK | 16 | X | 00025C | 3 | Task number |
JCSPTIME | 19 | X | 1445123F | 4 | Time of request - hhmmsss+ |
JCSPTRAN | 23 | C | TRN1 | 4 | Trans-action identifier |
JCSPTRAN | 23 | X | E3D9D5F1 | 4 | alter-native format |
JCSPTERM | 27 | C | T004 | 4 | Terminal identifier |
JCSPTERM | 27 | X | E3F0F0F4 | 4 | alternative format |