CICS Journal Management

CICS journal management covers how journals (log streams or journal data sets) are used to record events and data for recovery, backout, and auditing. CICS and other components write system journal records automatically; application programs can write their own records using EXEC CICS WRITE JOURNALNAME (or WRITE JOURNALNUM). Each journal record has a structure that includes system header and prefix information plus the journal data. Understanding journal management helps you design application journaling and use CICS recovery facilities.

Explain Like I'm Five: What Is a Journal?

A journal is like a diary the computer keeps. Every time something important happens (or your program says "write this down"), the system adds a line to the diary. Later, if something goes wrong, people can read the diary to see what happened and sometimes undo or redo work. Your program can add its own lines (WRITE JOURNALNAME) so that your actions are in the diary too. The diary has a special format so the system knows what each line means.

What Are CICS Journals Used For?

CICS journals are used for: (1) dynamic transaction backout—recording updates so they can be undone if a task fails or backs out; (2) forward recovery—recording changes so resources (e.g. files) can be recovered after a failure; (3) restart—replaying or using journal data after a CICS or region restart; (4) auditing and problem determination—having a trail of what happened. Application programs that need to participate in recovery or need an audit trail can write their own journal records in addition to the records CICS writes.

Writing Application Data: WRITE JOURNALNAME and WRITE JOURNALNUM

To write a record to a journal from an application program, use EXEC CICS WRITE JOURNALNAME(name) JOURNALLENGTH(length) FROM(data-area). The journal name is the 1–8 character name of a journal defined in the CICS JOURNALS resource. JOURNALLENGTH is the length in bytes of the data you are writing (from the FROM area). You can optionally specify JTYPEID—a 2-byte value that identifies the type of your record (user type ID). This lets readers of the journal distinguish different record types. WRITE JOURNALNUM is the same idea but you identify the journal by a numeric ID instead of a name. Both commands require the journal to be defined and the task to have permission to write to it.

1
2
3
4
5
6
7
EXEC CICS WRITE
    JOURNALNAME(WS-JOURNAL-NAME)
    JOURNALLENGTH(WS-DATA-LEN)
    FROM(WS-JOURNAL-REC)
    JTYPEID(WS-TYPE-ID)
    RESP(WS-RESP)
END-EXEC.

Journal Record Structure

CICS format journal records have a standard layout. The system adds a header and prefix so that each record is self-describing and recoverable. Application data you pass in FROM becomes the journal data portion; the system adds the rest. Understanding the structure helps when you read journals or design recovery logic.

The system header includes record length and type identifiers (e.g. JCRUTRID for user type, JCRSTRID for system type). The system prefix holds task number, time, transaction ID, terminal ID. The user prefix is optional. The journal data is your FROM data (for application writes) or component-specific data. CICS and other components use these fields to distinguish record types and to perform backout or recovery.

JOURNALLENGTH and FROM

JOURNALLENGTH must specify the length of the data in the FROM area. It is typically a halfword binary value. The FROM area contains only the application payload; CICS adds the header and prefix. So the length you pass is the length of your record, not the total length of the stored journal record. Ensure the FROM area is at least JOURNALLENGTH bytes and that the value matches what you intend to write (e.g. no truncation, no overrun).

JTYPEID for User Records

For application (user) journal writes, JTYPEID is a 2-byte value that is stored in the journal record (e.g. in the user type ID field). It allows your recovery or audit code (or CICS facilities) to identify the kind of record when reading the journal. Use different JTYPEID values for different application record types (e.g. one for "order committed," one for "payment logged") so you can filter or process them correctly during recovery or analysis.

Step-by-Step: Writing an Application Journal Record

1. Ensure the journal is defined to CICS (JOURNALS resource) and the task is allowed to write to it.
2. Build the record in working storage (or a data area). This is the data you want in the journal (e.g. key fields, before/after values for recovery).
3. Set the length of that data (e.g. in a halfword binary field) and set JTYPEID if you use record types.
4. Issue EXEC CICS WRITE JOURNALNAME(...) JOURNALLENGTH(...) FROM(...) [JTYPEID(...)] RESP(...).
5. Check the response code. Normal means the record was written. Handle errors (e.g. journal not available, length error, not authorized) as required.

Recovery and Backout

CICS uses journal records when performing dynamic transaction backout (undoing updates of a failed or backed-out task) and for forward recovery of resources. Application-written records can be used by your own recovery programs: after a failure you read the journal (or CICS replays it) and reapply or compensate based on the data you wrote. Design the content of your journal records so they contain everything needed for recovery (e.g. resource id, operation, before/after image, or idempotency key). Consider recovery requirements when you choose what to journal and in what format.

Best Practices

• Design journal record content for recovery: include enough data to redo or compensate the operation.
• Use JTYPEID to distinguish record types so readers can process them correctly.
• Set JOURNALLENGTH correctly; mismatched length can cause truncation or invalid records.
• Check RESP after WRITE and handle NOTAUTH, IOERR, and other conditions.
• Coordinate with CICS recovery and backout: understand how your records interact with system journaling and resource recovery.

Test Your Knowledge