Create a journal record
WRITE JOURNALNAME
>>-WRITE JOURNALNAME(data-value)--JTYPEID(data-value)----------->
>--FROM(data-area)--+---------------------+--------------------->
'-FLENGTH(data-value)-'
>--+------------------+----------------------------------------->
'-REQID(data-area)-'
>--+---------------------------------------------+--+------+---->
'-PREFIX(data-value)--+---------------------+-' '-WAIT-'
'-PFXLENG(data-value)-'
>--+-----------+-----------------------------------------------><
'-NOSUSPEND-'
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)