WRITE JOURNAL (DC/UCF)

Data Manipulation Language Statements › WRITE JOURNAL (DC/UCF)

WRITE JOURNAL (DC/UCF)

The WRITE JOURNAL statement writes a task-defined record to the journal file. Records written to the journal file with the WRITE JOURNAL function will be available to user-defined exit routines during a task- or system-initiated rollback.

Syntax

►►─── WRITE JOURNAL ─┬────────────┬─┬──────────┬──────────────────────────────►
                     ├─ WAIT ─────┤ ├─ SPAN ◄ ─┤
                     └─ NOWAIT ◄ ─┘ └─ NOSPAN ─┘

 ►─── FROM (record-location) ─┬─ TO (end-record-location) ─┬─ ; ──────────────►◄
                              └─ LENGTH (record-length) ───┘

Parameters

WAIT/NOWAIT

Specifies whether the issuing task is to wait for completion of the WRITE JOURNAL function before resuming execution:

WAIT: Specifies that the issuing task will wait for completion of the physical I/O associated with the WRITE JOURNAL function before resuming execution. This option will cause the system to write a partially filled buffer to the journal file.
NOWAIT: Specifies that the issuing task will not wait for completion of the WRITE JOURNAL function; the journal record will remain in a storage buffer until a future request necessitates writing the buffer to the journal file. NOWAIT is the default.

SPAN

Indicates that the system will write the record across several journal file blocks, if necessary. SPAN is the default.

Note: In general, the SPAN option provides better space utilization in the journal file than NOSPAN because it increases the average fullness of each block.

NOSPAN

Indicates that the system will write the record to a single journal file block; if it is longer than the journal block, the record will be split.

When a record is shorter than a journal file block, based on space available in the current journal block, the system will either place the record in the block, split it across multiple blocks (SPAN), or write it to a new block after the current block is written (NOSPAN).

The following considerations apply to using an exit routine to retrieve journal file records during recovery:

If a WRITE JOURNAL statement issued before a failure specified the SPAN option, records may have been written across several journal blocks. To retrieve these records, the exit routine will be invoked once for each segment of each record to be retrieved.
If a WRITE JOURNAL statement issued before a failure specified the NOSPAN option and records written to the journal file are shorter than journal blocks, the exit routine need only be concerned with the complete records.

FROM (record-location)

Defines the program variable-storage entry of the record to be written to the journal file. Record-location is the symbolic name of a user-defined field. The length of the record area is determined by one of the following specifications:

TO (end-record-location): Indicates the end of the record area to be written to the journal file and is specified following the last data-item entry in record-location. End-record-location is the symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the record being written to the journal file.
LENGTH (record-length): Defines the length, in bytes, of the record to be written to the journal file. Record-length is either the symbolic name of the user-defined field that contains the length, or the length itself expressed as a numeric constant.

Example

The following statement writes the JOURNAL_DATA record to the journal file, spanning it across several blocks if necessary:

WRITE JOURNAL SPAN
  FROM (JOURNAL_DATA) TO (END_JOURNAL_DATA);

Status Codes

Upon completion of the WRITE JOURNAL function, the ERROR_STATUS field in the IDMS DC communications block indicates the outcome of the operation:

0000: The request has been serviced successfully.
5002: Storage is not available for the required control blocks.
5032: The derived length of the specified journal record is zero or negative.
5097: An invalid status has been received from DBIO/DBMS; check the system log for details.