Structure and content of CICS Transaction Server for z/OS 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.

General logs (that is, those containing forward-recovery logs, auto-journals, and user journals) can be presented in the format introduced at CICS® Transaction Server for OS/390®, Version 1 Release 1. Each journal record in these logs, if presented in the newer format, contains more information than in the equivalent journal record presented in the CICS/ESA 4.1 format.

System logs are always presented in CICS Transaction Server for z/OS® format..

Each general log comprises a stream of contiguous blocks of journaled data. Each block comprises a block header followed by a variable number of CICS journal records. Each CICS journal record comprises a record header followed by caller data.

Figure 60 gives a graphical overview of a general log, showing the format of a complete block, and the format of a complete journal record.

The format of the caller data depends on the CICS component that is issuing the journal record, and also on the function being journaled at the time. Thus, for example, the format of caller data in journal records issued by file control differs from that of caller data in journal records issued by FEPI.

Figure 60. Layout of a general log
 The picture shows three rectangles, one above the other. The top rectangle consists of a series of log blocks. The middle rectangle is an expansion of one of the log blocks from the top rectangle. It consists of a block header, followed by a series of CICS journal records. The bottom rectangle is an expansion of one of the CICS journal records from the middle rectangle. It consists of a record header, followed by caller data.

Format of general log block header

The log block header contains information of a general system-wide nature such as the CICS applid writing the journal block. Figure 61 shows the format of the log block header.

Figure 61. Format of a general log block header
This fields in this picture are described in the list that follows.

LGBH_GLOBAL_INFO
8-bytes containing '>DFHtrnn', where:
t  = log type
r  = reserved
nn = block version number
LGBH_GENERIC_APPLID
8-byte CICS applid.
LGBH_START_GMT
8-byte start time (GMT).
LGBH_START_LOCAL
8-byte start time (local).
LGBH_BLOCK_NUMBER
8-byte sequence number.

Format of general log journal record

The journal record comprises a record header followed by caller data. The record header contains information that describes some of the attributes of the record, such as the time it was written. Figure 62 shows the format of the record header.

Figure 62. Format of a general log record header
This fields in this picture are described in the list that follows.

GLRH_RECORD_LENGTH
4-byte record length.
GLRH_HEADER_LENGTH
4-byte header length.
GLRH_REC_DATA_LEN
4-byte record data length.
GLRH_GMT
8-byte time (GMT).
GLRH_LOCAL
8-byte time (local).
GLRH_TRAN_ID
4-byte transaction identifier.
GLRH_TASK_ID
4-byte task identifier.
GLRH_TERM_ID
4-byte terminal identifier.
GLRH_REC_TYPE
2-byte record type. Either:
X'0001'  Start of run record
X'0002'  Any other record
GLRH_REC_COMPID
2-byte domain identifier.
GLRH_REC_JOURNAL
8-byte journal name.
Start of task indicator
1-byte which may contain:
X'8n'   Equivalent to JCSPSOTK (start of task)
X'4n'   Equivalent to JCSPLSTK (start of UOW)
Reserved
3-byte reserved field.

The caller data differs depending on the CICS component issuing the record, and on the function being journaled.

Start-of-run record

When CICS connects to a general log, it writes a start-of-run record to it as the first record for this run of CICS. This record comprises a record header (with the same format as that for any general log journal record) followed by a start-of-run body. Its format is shown in Figure 63.

Figure 63. Format of the start-of-run record
This fields in this picture are described in the list that follows.

SOR_CICS_RELEASE
4-byte CICS release.
SOR_SPECIFIC_APPLID
8-byte CICS applid.
SOR_CICS_USERNAME
8-byte CICS username.

Start of changeFor a start-of-run record, CICS puts the domain identifier "LG" (for "logger") in the GLRH_REC_COMPID field of the record header.End of change

Format of caller data

Caller data follows the record header.

The format of the caller data part of a general log journal record differs according to the CICS component writing the record, and the function being journaled.

Journal records can be written by any of the following CICS components: Start of changethe loggerEnd of change, journal control (in the case of a request issued by a user), file control, the front end programming interface (FEPI), and terminal control. The field GLRH_REC_COMPID in the record header tells you which component has written the record: Start of changeLGEnd of change, UJ, FC, SZ, or TC respectively.

File control adds information to the start of the actual journaled data, and this is described in Caller data written by file control. The other components (journal control, FEPI, and terminal control) do not add any further information to the journaled data.

If the record has been written by the CICS API, the caller data section starts with an API user header, the format of which is shown in Figure 64.

Figure 64. Format of the API user header
This fields in this picture are described in the list that follows.

CL_UH_LENGTH
4-byte header length.
CL_UH_JOURNAL_TYPE
2-byte journal type.
Reserved
2-byte reserved field.
CL_UH_PREFIX_LENGTH
4-byte prefix length.
Prefix
Variable-length prefix area.
User data
Variable-length user data.

Caller data written by file control

The file log and journal block (FLJB) describes the caller data that file control writes as part of its journal records. The copybook DFHFCLGD defines the FLJB DSECT.

There are two sections in the FLJB: the first section contains data that is applicable to all journal records written by file control; the second section contains information specific to the record type. Both sections are of fixed length.

Some records have a third and fourth section which are of variable length.

Table 37 outlines the sections in a journal record written by file control.

Table 37. FLJB sections in journal records issued by file control
Record type First section Second section Third section Fourth section
Read-only Read-update Write-update Write-add Write-add complete FLJB_GENERAL_DATA FLJB_COMMON_DATA FLJB_CD_KEY FLJB_CD_DATA
Write delete FLJB_GENERAL_DATA FLJB_WRITE_DELETE _DATA FLJB_WDD_BASE_KEY FLJB_WDD_PATH_KEY
File close FLJB_GENERAL_DATA FLJB_FILE_CLOSE _DATA None None
Tie-up FLJB_GENERAL_DATA FLJB_TIE_UP_RECORD _DATA None None
Tie-up FLJB_GENERAL _DATA FLJB_TIE_UP _RECORD _DATA None None

A description of each of the structures, and the sections within them, now follows:

Read-only, read-update, write-update, write-add, write-add complete record types

There are four sections in the journal records written for read-only, read-update, write-update, write-add, and write-add complete record types:

The format of such a record written for these record types is shown in Figure 65.

Figure 65. Layout of record written for read-only, read-update, write-update, write-add, and write-add-complete record types
This fields in this picture are described in the list that follows.

FLJB_GENERAL_DATA
12-byte general data.
FLJB_COMMON_DATA
16-byte common data.
FLJB_CD_KEY
Variable-length caller data key.
FLJB_CD_DATA
Variable-length caller data.

The format of the FLJB_GENERAL_DATA section is shown in Figure 66.

Figure 66. Format of FLJB_GENERAL_DATA section
This fields in this picture are described in the list that follows.

FLJB_RECORD_TYPE
1-byte record type:
X'80'    Readonly
X'81'    Read update
X'82'    Write update
X'83'    Write add
X'84'    Write add complete
X'86'    Write delete
X'8E'    File close
X'8F'    File tie-up record
FLJB_BITS
1-byte flag field:
X'80'    File control autojournal record
X'40'    Forward recovery log record
X'20'    System log record
X'10'    Log-of-log record
FLJB_FILE_NAME
8-byte file name.
Reserved
2-byte reserved field.

The format of the FLJB_COMMON_DATA section is shown in Figure 67.

Figure 67. Format of FLJB_COMMON_DATA section
This fields in this picture are described in the list that follows.

FLJB_CD_BASE_ESDS_RBA
4-byte relative byte address of record in base data set for ESDS (0 if file does not refer to ESDS).
FLJB_CD_KEY_LENGTH
2-byte length of user data key.
Reserved
2-byte reserved field.
FLJB_CD_DATA_LENGTH
4-byte length of user data.
FLJB_CD_BITS
1-byte flag field:
X'80'    UOW has been shunted at least once
X'40'    Write massinsert
X'20'    First write-add-complete in massinsert sequence
X'10'    End of massinsert sequence
X'8'     Fixed length record
Combinations of settings are possible.
Reserved
3-byte reserved field.

Write-delete record types

There are four sections in the journal records written for write-delete record types:

The format of such a record written for write-delete record types is shown in Figure 68.

Figure 68. Layout of record written for write-delete record types
This fields in this picture are described in the list that follows.

FLJB_GENERAL_DATA
12-byte general data section.
FLJB_WRITE_DELETE_DATA
12-byte write-delete data section.
FLJB_WDD_BASE_KEY
Variable-length base key.
FLJB_WDD_PATH_KEY
Variable-length path key.

See Figure 66 for the format of the FLJB_GENERAL_DATA section.

The format of the FLJB_WRITE_DELETE_DATA section is shown in Figure 69.

Figure 69. Format of the FLJB_WRITE_DELETE_DATA section
This fields in this picture are described in the list that follows.

FLJB_WDD_BASE_ESDS_RBA
4-byte relative byte address of record in base data set for ESDS (0 if file does not refer to ESDS).
FLJB_WDD_BASE_KEY_LENGTH
2-byte base key length.
FLJB_WDD_PATH_KEY_LENGTH
2-byte path key length (0 if file does not refer to a path).
FLJB_WDD_BITS
1-byte flag field:
X'80'    UOW has been shunted at least once
X'40'    Fixed-length record
Reserved
3-byte reserved field.

File-close record types

There are two sections in the journal records written for file-close record types:

The format of such a record written for file-close record types is shown in Figure 70.

Figure 70. Layout of record written for file-close record types
This fields in this picture are described in the list that follows.

FLJB_GENERAL_DATA
12-byte general data section.
FLJB_CLOSE_DATA
28-byte close data section.

See Figure 66 for the format of the FLJB_GENERAL_DATA section.

The format of the FLJB_CLOSE_DATA section is shown in Figure 71.

Figure 71. Format of the FILE_CLOSE_DATA section
This fields in this picture are described in the list that follows.

FLJB_FCD_FWDRECOVLOG_NAME
26-byte log stream name of the forward recovery log.
FLJB_FCD_BITS
1-byte flag field:
X'80'    Forward recovery specified for file or data set
X'40'    Autojournaling specified for file
Reserved
1-byte reserved field.

Tie-up record types

There are two sections in the journal records written for tie-up record types:

The format of such a record written for tie-up record types is shown in Figure 72.

Figure 72. Layout of record written for tie-up record types
This fields in this picture are described in the list that follows.

FLJB_GENERAL_DATA
12-byte general data.
TIE_UP_RECORD_DATA
136-byte tie-up record data.

See Figure 66 for the format of the FLJB_GENERAL_DATA section.

The format of the TIE_UP_RECORD_DATA section is shown in Figure 73.

Figure 73. Format of TIE_UP_RECORD_DATA section
This fields in this picture are described in the list that follows.

FLJB_TUR_BASE_CI_SIZE
4-byte CI size of base data set.
FLJB_TUR_MAXIMUM_LRECL
4-byte maximum record length.
FLJB_TUR_BASE_KEY_POSITION
4-byte base key position in record.
FLJB_TUR_BASE_KEY_LENGTH
2-byte base key length.
FLJB_TUR_DATASET_TYPE
1-byte data set type:
X'C5'     ESDS
X'D2'     KSDS
X'D7'     Path
X'D9'     RRDS
X'E5'     VRRDS
FLJB_TUR_RECORD_FORMAT
1-byte record format:
X'E5'     Variable
X'C6'     Fixed 
FLJB_TUR_BASE_DSNAME_LENGTH
2-byte length of base data set name.
FLJB_TUR_BASE_DSNAME
44-byte base data set name.
FLJB_TUR_PATH_DSNAME_LENGTH
2-byte length of path data set name.
FLJB_TUR_PATH_DSNAME
44-byte path data set name.
FLJB_TUR_FWDRECOVLOG_NAME
26-byte log stream name of forward recovery log.
FLJB_TUR_BITS
1-byte flag field.
Reserved
1-byte reserved field.
Note:
The format of caller data in journal records written by file control in RLS mode is identical to that in journal records written by file control in non-RLS mode except for FLJB_TUR_BITS where a value of X'80' indicates RLS-access.

Terminal control prefix data

CICS terminal control (TC) writes journal records to track the messages it issues. Each TC journal record contains a prefix area, which lies in the position of the prefix area in the API user header. For LU6.1-related records only, the prefix area contains the VTAM® physical sequence numbers at syncpoint time; for all other TC journal records, it contains binary zeros. The format of the TC prefix area is shown in Figure 74.

Figure 74. Format of the terminal control prefix area
This fields in this picture are described in the list that follows.

Function ID
1-byte function identifier.
Module ID
1-byte module identifier.
Inbound VTAM SN
2-byte inbound VTAM sequence number.
Outbound VTAM SN
2-byte outbound VTAM sequence number.
JCAUP TID
4-byte terminal identifier (padded with blanks if unused).

FEPI prefix data

Each FEPI journal record contains a prefix area that allows you to identify the FEPI conversation for which the data was journaled. This prefix area lies in the position of the prefix area in the API user header. Its format is shown in Figure 75.

Figure 75. Format of the FEPI prefix area
This fields in this picture are described in the list that follows.

UP_MODFN
1-byte module function
UP_SVMID
1-byte module identifier
UP_FEPDF
1-byte data function
UP_FEPES
1-byte escape character for keystroke
Reserved
2-byte reserved field
UP_FEPPL
8-byte pool name
UP_FEPTG
8-byte target name
UP_FEPCV
8-byte conversation identifier
Reserved
4-byte reserved field

See the CICS Front End Programming Interface User’s Guide for more information about FEPI journaling.

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