Structure and content of COMPAT41-format journal records

SMF records

The following description does not apply to journal records written to an SMF data set. These are described in topic Format of journal records written to SMF.

CICS® allows you to format journal records so that they are presented in the format used at CICS/ESA 4.1. Use the COMPAT41 option on the SUBSYS=(LOGR...) step of your JCL.

Within the data presented, certain fields are not presented at CICS Transaction Server for z/OS®. They appear as X'00' in the formatted output. These fields are:

Table 38. Fields formatted as X'00'
JCLRJFID
JCLRVCD
JCLRVSN
JCLRLBW
JCLRTBAL
JCRBB
JCSPFS
JCSPDSP
JCSPEMER
JCSPMIDT
JCSPRRIF

Each general log comprises a stream of contiguous blocks of journaled data. Each block comprises a journal control label header followed by a variable number of CICS journal records. Each CICS journal record comprises a system header, system prefix, user prefix, and journaled data.

A graphical overview of the format of a general log, showing the format of a complete block, is shown in Figure 76.

Figure 76. Format of general log formatted using the COMPAT41 option
 The picture shows two rectangles, one above the other. The top rectangle consists of a series of log blocks. The lower rectangle is an expansion of one of the log blocks from the top rectangle. It consists of a journal control label header, followed by a series of journal records.

Format of COMPAT41 journal control label header

Each log block starts with a journal control label header. There is one journal control label header per log block. It is 42 bytes long, and comprises a length field, label header, and label prefix. The format of the journal control label header is shown in Figure 77.

Figure 77. Format of journal control label header
 The picture shows a rectangle, representing the journal control label header. It contains three fields:    4 bytes containing the length of a block. (This is not presented unless the caller is reading data blocks rather than records.) 10 bytes containing the label header. 32 bytes containing the label prefix.

The label header part of the journal control label header is 10 bytes long, and its format is shown in Figure 78.

Figure 78. Format of label header part of journal control label header
This fields in this picture are described in the list that follows.

JCRLL
2-byte length of record.
X'0000'
2-bytes containing X'0000'.
JCRSTRID
2-byte system-type identifier. For a user journal request, this is X'0000'. Otherwise, it consists of a 1-byte function ID followed by a 1-byte module ID.
JCRUTRID
2-byte user-type identifier. For a CICS journal request, this is X'0000'. Otherwise, it contains the code specified by the JTYPEID keyword of the user request.
JCRLRN
2-byte record number within the block.

The label prefix part of the journal control label header is 32 bytes long, and its format is shown in Figure 79.

Figure 79. Format of label prefix part of journal control label header
This fields in this picture are described in the list that follows.

X'00'
1-byte containing X'00'.
JCRBLKN
3-byte journal block number.
X'00's
12-bytes each containing X'00'.
JCLRTIME
4-bytes containing the time the block was written, in hhmmss format. (Local or GMT set in LOGR SSI.)
JCLRRST
4-bytes containing the run start time.
JCLRDATE
4-bytes containing the date the block was written.
JCLRSEQ
4-byte journal block sequence number.

Format of journal record

Each CICS journal record comprises a system header, system prefix, user prefix, and journaled data. The format of a journal record is shown in Figure 80.

Figure 80. Format of COMPAT41 journal record
 The picture shows the format of a COMPAT41 journal record. It consists of:   A 10-byte system header A 20-byte system prefix A variable-length user prefix Variable-length journal data

The system header is 10 bytes long. Its format is shown in Figure 81.

Figure 81. Format of the system header
This fields in this picture are described in the list that follows.

JCRLL
2-byte length of record.
X'0000'
2-bytes containing X'0000'.
JCRSTRID
2-byte system-type identifier. For a user journal request, this is X'0000'. Otherwise, it consists of a 1-byte function ID followed by a 1-byte module ID.
JCRUTRID
2-byte user-type identifier. For a CICS journal request, this is X'0000'. Otherwise, it contains the code specified by the JTYPEID keyword of the user request.
JCRLRN
2-byte record number within the block.

The field JCRSTRID (the system-type ID) and the field JCRUTRID (the user-type ID) in the system header allow you to distinguish those journal records output by CICS (by such components as terminal control), from those issued by direct user requests.

For CICS journal requests, JCRUTRID contains binary zeros, and JCRSTRID contains a 1-byte function code followed by a 1-byte module code. The function code tells you which function was being journaled, and the module code shows which module caused the record to be written. Valid settings of these codes are contained in the member DFHFMIDS of the CICS assembler-language macro library. Figure 84 shows the valid function identifiers of those CICS components that issue journal requests. Figure 85 shows the valid module identifiers.

For user journal requests, JCRSTRID always contains binary zeros, and JCRUTRID contains the 2-byte hexadecimal code specified by the JTYPEID keyword of the WRITE JOURNALNAME request in the application program.

The system prefix is 20 bytes long. Its format is shown in Figure 82.

Figure 82. Format of the system prefix
This fields in this picture are described in the list that follows.

JCSPLL
2-byte length of the system prefix.
Reserved
2-byte reserved field.
JCSPF1
1-byte flag field:
X'01'    User prefix present
X'02'    Physical start-of-task, JCSPSOTK
X'04'    Logical start-of-task, JCSPLSTK
JCSPTASK
3-byte task number.
JCSPTIME
4-byte time of request.
JCSPTRAN
4-byte transaction identifier.
JCSPTERM
4-byte terminal identifier.

For some CICS journal requests, additional data is included in the system prefix to identify more specifically the originator of the request. This extra data follows the common fields of the system prefix, and is usually variable in length; hence the need for the length field JCSPLL at the start of the system prefix. All the following have their own prefix layout, and these are described, for the purposes of diagnosis and recovery, in the CICS Data Areas manual.

The user prefix is a variable length area. It is present if this record has been written by a user request, an EXEC CICS WRITE JOURNALNAME command. The information contained in the record is set by the user within the terms of the command via the JTYPEID, PREFIX, and PFXLENG parameters. Its format is shown in Figure 83.

Figure 83. Format of the user prefix
 The picture shows the format of the user prefix (of a COMPAT41 journal record). The user prefix consists of two variable-length fields: the first containing the length of the user prefix, and the second the user prefix data.

Field JCSPUP is set in the system prefix area if a user prefix is present in a journal record.

The journaled data then follows. If you want a length field for the data, you must include it in the data. Alternatively, you can compute the length of the data portion of a journal record by taking the length of the system header (10 bytes), plus the length of the system prefix (JCSPLL), plus the length of the user prefix (in the field, if any, defined by yourself), and subtracting the total from the length of the journal record (JCRLL):

JCRLL - (system header (10) bytes + JCSPLL + user prefix)

Not all journal records contain journaled data.

The CICS components that issue journaling requests are journal control, file control, FEPI, and terminal control.

Figure 84. Journal function identifiers
***********************************************************************
* *             F U N C T I O N   I D E N T I F I E R S             * *
***********************************************************************
*                                                                     *
*        X'20' PLUS X'8-' ...USE FOR AUTOMATIC JOURNALING             *
*        X'40' PLUS X'8-' ...USE FOR AUTOMATIC LOGGING                *
***********************************************************************
* *                         JOURNAL CONTROL                         * *
***********************************************************************
FIDJCLAB EQU   X'80'               ...JOURNAL CONTROL LABEL
*                                  RECORD (DFHJCR)                    *
***********************************************************************
* *                         FILE CONTROL                            * *
***********************************************************************
FIDALOG  EQU   X'40'               ...AUTOMATICALLY LOGGED
FIDAJRN  EQU   X'20'               ...AUTOMATICALLY JOURNALED
FIDMASS  EQU   X'10'               ...MASSINSERT REQ. (FIDFCWA ONLY)
*                                       PLUS ONE OF...                *
FIDFCRO  EQU   X'80'               ...FILE CONTROL READ-ONLY
FIDFCRU  EQU   X'81'               ...FILE CONTROL READ-UPDATE
FIDFCWU  EQU   X'82'               ...FILE CONTROL WRITE-UPDATE
FIDFCWA  EQU   X'83'               ...FILE CONTROL WRITE-ADD
FIDFCWAC EQU   X'84'               ...FILE CONTROL WRITE-ADD-COMPLETE
FIDFCWD  EQU   X'86'               ...FILE CONTROL WRITE DELETE
FIDFCBOF EQU   X'88'               ...BACKOUT FAILED LOG RECORD
FIDFCDSN EQU   X'8F'               ...DSNAME RECORD
*                                                                     *
*        NOTE THAT FID* VALUES (AS ABOVE) ARE OFTEN USED BOTH TO      *
*        IDENTIFY THE FUNCTION OF THE DWE AND THE FUNCTION OF THE     *
*        LOG RECORD.  IN THE CASE OF THE FIDFC* EQU'S ABOVE, THEY     *
*        ARE USED FOR LOG RECORDS ONLY.  THOSE BELOW APPLY ONLY       *
*        TO DWE'S                                                     *
*                                                                     *
FIDFCVWA EQU   X'80'               THIS DWE ADDRESSES A VSWA.
FIDFCRVY EQU   X'40'               THIS DWE IS ASSOCIATED WITH A      *
                                   RECOVERABLE CHANGE.
***********************************************************************
*                TERMINAL CONTROL FUNCTION IDENTIFIERS                *
*                                                                     *
FIDTCML  EQU   X'F0'               SYNCPOINT - LOG SEQUENCE
*                                  NUMBERS                            *
*                                  CAN BE OR'ED WITH ANY OF           *
                                   THE FOLLOWING THREE FIELDS:
FIDTCDWL EQU   X'01'               ...DEFERRED WRITE DATA
FIDTCFMH EQU   X'02'               ...+ FUNCTION MANAGEMENT
*                                  HEADER
FIDTCDIP EQU   X'04'               ...+ DIP REQUEST
*                                                                     *
*        EQU   X'08'               ...DYNAMIC BACKOUT MASK            *
                                      RESERVED
FIDTCAL  EQU   X'40'               AUTOMATIC LOGGING MASK...
FIDTCAJ  EQU   X'20'               AUTOMATIC JOURNALING MASK..
*                        ...THE ABOVE 2 PLUS 1 OF FOLLOWING SET       *
FIDTCTL  EQU   X'80'               ...SEQUENCE NUMBER ONLY
*                                  (LOG ONLY)                         *
FIDTCIM  EQU   X'81'               ...INPUT MESSAGE (LOG AND
*                                  JOURNAL)                           *
FIDTCOM  EQU   X'82'               ...OUTPUT MESSAGE (JOURNAL
*                                  ONLY)                              *
FIDTCWP  EQU   X'83'               ...WRITE WAS PURGED (LOG
*                                  ONLY)                              *
FIDTCPRR EQU   X'84'               ...POSITIVE RESPONSE
*                                  RECEIVED (LOG ONLY)                *
FIDTCIMF EQU   X'85'               ...INPUT MESSAGE (W/FMH,
*                                  LOG AND JOURNAL)                   *
FIDTCOMN EQU   X'86'               ...OUTPUT MESSAGE, (W/O
*                                  FMH, JOURNAL ONLY)                 *
FIDTCON  EQU   X'87'               ...OUTPUT MESSAGE, FMH,
*                                  CCOMPL=NO                          *
FIDTCONN EQU   X'88'               ...OUTPUT MESSAGE, W/O FMH,
                                   ...CCOMPL=NO
FIDTCUA  EQU   X'89'               ...INITIAL TCT USER AREA
FIDTCEIB EQU   X'8A'               ...INITIAL EXEC COMM AREA
FIDTCIMN EQU   X'8B'               INPUT MSG, NO FMH, COMPLETE
FIDTCINN EQU   X'8C'               INPUT MSG, NO FMH, INCOMPLETE
***********************************************************************
*              FRONT END PROGRAMMING INTERFACE IDENTIFIERS            *
FIDFEPIN EQU   X'F0'               FEPI INBOUND DATA    API <--- FEPI
FIDFEPOU EQU   X'F1'               FEPI OUTBOUND DATA   API ---> FEPI
***********************************************************************

Figure 85. Journal module identifiers
***********************************************************************
* *               M O D U L E   I D E N T I F I E R S               * *
***********************************************************************
*                                                                     *
MODIDTC  EQU   X'10'               ...TERMINAL CONTROL
MODIDFC  EQU   X'11'               ...FILE CONTROL
MODIDJC  EQU   X'45'               ...JOURNAL CONTROL
MODIDFEP EQU   X'50'               ...FEPI
*                                                                     *
***********************************************************************
Notes:
  1. Records created by automatic journaling and automatic logging are identified by values of X'20' (FIDAJRN) and X'40' (FIDALOG) respectively, added to the "base" value of the function identifier.
  2. A File Control write-delete record created by the forward recovery process (where the write-delete is done) has a function identifier of X'86' (FIDFCWD). However, if the record is created by the autojournal process it has a function identifier of X'A2', made up of X'82' (write-update or FIDFCWU) plus X'20' (FIDAJRN).

Identifying records for the start of tasks and UOWs

You can identify records written to mark the start of tasks by examining the value of the system prefix field JCSPF1. If the JCSPSOTK bit is set, the record has been written at the start of the task.

If the JCSPLSTK bit is set in field JCSPF1, then the record has been written at the start of the UOW.

Related concepts
The CICS log manager
Log stream storage
Related tasks
Enabling, disabling, and reading journals
Related reference
Structure and content of CICS Transaction Server for z/OS format journal records
Format of journal records written to SMF
[[ Contents Previous Page | Next Page Index ]]