WRITE JOURNALNAME

Create a journal record

WRITE JOURNALNAME

Conditions: INVREQ, IOERR, JIDERR, LENGERR, NOJBUFSP, NOTAUTH, NOTOPEN

This command is threadsafe.

Description

WRITE JOURNALNAME writes a journal record from the specified data area to the system logger log stream that corresponds to the CICS® journal name, or to SMF. The request can be for synchronous or asynchronous output; definitions of these terms, and information regarding the synchronization of journal output, are in Journal output synchronization .

Options

FLENGTH(data-value)

specifies, as a full word binary value, the length in bytes of the user data to be built into the journal record.

Note that the maximum total length of a journal record depends on a number of factors:

There is a limit of 32KB minus 400 bytes if the journal is using SMF.
The limit for journals that map to log streams is the value expressed in the MAXBUFSIZE attribute for the structure being used minus 400 bytes. This has to include the user data, the prefix data, and the 2-byte JTYPEID.

Note: Data longer than 32K bytes cannot be read by offline jobs using the SUBSYS=LOGR interface.

FROM(data-area)

specifies the user data to be built into the journal record.

JOURNALNAME(data-value)

specifies a 1- to 8-character journal name. The valid characters for a journal name are the upper-case letters A through Z, the numeric characters 0 through 9, and the special symbols $ @ and #.

On first reference to this journal name, CICS must be able to map the journal name to a corresponding MVS™ system loggerlog stream, or MVS SMF data set. To do this, CICS searches the installed JOURNALMODEL definitions, looking for a matching journal name in a journal model. CICS looks for either a specific match or a generic match. If a matching entry cannot be found, CICS attempts to use a default log stream name.

To write to the CICS system log, specify DFHLOG as the journal name.

Note: The CICS system log should be used only for short-lived data required for recovery purposes. You should not write user records for such things as audit trails to it.

To write to journals defined using the journal numbering convention (for example, to the auto journals defined in file resource definitions), specify the name as DFHJnn, where nn is the journal number in the range 1 to 99.

You cannot write to a forward recovery log that is known to CICS only by its 26-character log stream name (as derived directly from the VSAM ICF catalog) unless you write to a journal whose matching JOURNALMODEL is associated with the same log stream name.

Specifying DFHJ01 on this command refers to a user journal, not the system log.

JTYPEID(data-value)

specifies a 2-character identifier to be placed in the journal record to identify its origin.

NOSUSPEND

specifies that the application program is not to be suspended for the NOJBUFSP condition. The user record is ignored.

PFXLENG(data-value)

specifies the length (halfword binary value) in bytes of the user prefix data to be included in the journal record.

Note that the maximum total length of a journal record depends on a number of factors:

There is a limit of 32KB minus 400 bytes if the journal is using SMF.
The limit for journals that map to log streams is the value expressed in the MAXBUFSIZE attribute for the structure being used minus 400 bytes. This has to include the prefix data, the user data, and the 2-byte JTYPEID.

The minimum value is 0. See FLENGTH for the limits to the size of a journal record.

Note: Data longer than 32K bytes cannot be read by offline jobs using the SUBSYS=LOGR interface.

PREFIX(data-value)

specifies the user prefix data to be included in the journal record. A data area must be provided in COBOL programs.

REQID(data-area)

specifies a data area that identifies the journal record. The data area is a fullword binary variable. CICS sets the variable to a token that can be used for synchronization. REQID is only valid for asynchronous output (that is, the WAIT option is not specified).

WAIT

specifies that synchronous journal output is required. The requesting task waits until the record has been hardened.

Conditions

16 INVREQ

the command is not valid for processing by CICS.

Default action: Terminate the task abnormally.

17 IOERR

a journal record has not been output because an irrecoverable error condition was returned by the system logger log stream or by SMF.

Default action: If the log is the system log, CICS either quiesces or abends CICS. If the log is a general log, the task is terminated abnormally.

43 JIDERR

CICS cannot connect to a log stream referenced by the specified journal name, for one of the following reasons:

The log stream does not exist and cannot be created dynamically using default model definitions.
The log stream is a DASD-only log stream to which a CICS region in another MVS image is currently connected.

Default action: terminate the task abnormally.

22 LENGERR

the aggregate length of the journal record, comprising the user data (FROM, JTYPE, and PREFIX data) and the CICS header data, is too great to fit the maximum block size allowed for the log stream.

Default action: terminate the task abnormally.

45 NOJBUFSP

the journal buffers are logically full (that is, the current buffer has insufficient space for this journal record, and I/O is in progress on the alternate buffer).

Default action: CICS suspends task activity until the journal request can be satisfied. CICS ensures that both buffers are written out to auxiliary storage, thus freeing them for new records. (You can override the default action by the NOSUSPEND option.)

70 NOTAUTH

a resource security check has failed on the JOURNALNAME(data-value).

Default action: terminate the task abnormally.

19 NOTOPEN

occurs in any of the following situations:

The command cannot be executed because the specified journal has been explicitly disabled by the user.
The request could not be satisfied because the specified journal was defined using a journal model that maps it onto the logstream that is being used as the system log for this CICS system. The error is detected when trying to connect to the logstream and results in a definition for the JOURNALNAME being installed and set to 'failed'.

Default action: terminate the task abnormally.

Examples

The following example shows how to write synchronous journal output and wait for the output operation to be completed:

EXEC CICS WRITE
     JOURNALNAME('ACCTSJNL')
     JTYPEID('XX')
     FROM(KEYDATA)
     FLENGTH(40000)
     PREFIX(PROGNAME)
     PFXLENG(6)
     WAIT

The following example shows how to write deferred (asynchronous) user recovery data to the CICS system log:

EXEC CICS WRITE
     JOURNALNAME('DFHLOG')
     JTYPEID('UR')
     FROM(COMDATA)
     FLENGTH(10)
     REQID(ENTRYID)