WRITE TRANSACTION

Purpose

(CA ADS/Batch only) Performs the following sequence of functions:

Terminates the current process
Performs a mapout operation
- If the dialog's current input file record contains no errors and the keyword SUSPENSE is not included in the command, the mapout writes a record to the dialog's associated output file, according to the output file map definition.
- If the input file record contains errors or the keyword SUSPENSE is included in the command, the mapout writes the input record to the dialog's suspense file and sends applicable error messages to the log file.
Passes control within the application. Control can be passed to:
- The dialog's premap process or mapin operation
- A higher level dialog or application function

Syntax

►►──── WRITE TRANsaction ─────┬───────────────┬───────────────────────────────►
                              └─ to SUSpense ─┘

 ►──┬─────────────────────────────────────────────────────────────────┬───────►
    ├─ CONTinue ──────────────────────────────────────────────────────┤
    └─ RETurn ────┬──────────────────┬─┬───────────┬─┬────────────┬───┘
                  ├─ TO dialog-name ─┤ └┬─ CLEAR ─┬┘ └─ CONTinue ─┘
                  └┬─ to TOP ─┬──────┘  └─ CLR ───┘
                   └─ ALL ────┘

 ►──┬─────────────────────────────────┬── . ──────────────────────────────────►◄
    └┬ MESSAGE ─┬── message-options ──┘
     └ MSG ─────┘

Expansion of Message-Options

►►────┬─ TEXT ─────┬──────┬────────── message-text ───────────────────────────►
      │            ├─ IS ─┤
      │            └─ =  ─┘
      └─ CODE ─────┬──────┬────────── message-code ───────────────────────────
                   ├─ IS ─┤
                   └─ =  ─┘

 ►────────────────────────────────────────────────────────────────────────────►
  ────┬───────────────────────────────────────────────┬───────────────────────
      │                         ┌──────────────┐      │
      └─ PARMS ────┬─────┬─── (─▼── parameter ─┴─ ) ──┘
                   └─ = ─┘

 ►────────────────────────────────────────────────────┬───────────────────────►◄
  ────┬────────────────────────────────────────┬──────┘
      └─ PREFIX ───┬──────┬─────── prefix ─────┘
                   ├─ IS ─┤
                   └─ =  ─┘

Parameters

to SUSpense

Specifies that the dialog's input record is written to the suspense file even if it does not contain errors. Nothing is written to the dialog's output file.

CONTinue

Specifies that control is passed to the dialog's premap process after mapout operation.

RETurn

Specifies that control is returned to a higher level dialog or application function after mapout operation.

TO dialog-name

Either the name of a variable data field that contains the dialog name to which control is passed or the dialog name itself, enclosed in single quotation marks.

to TOP

Specifies the highest level to which control can pass.

ALL can be used in place of to TOP.

CLEAR

Specifies that record buffers are reinitialized and currencies are released for the dialog receiving control.

CLEAR is ignored if the receiving dialog is at the top of a nested application structure.

CLR can be used in place of CLEAR.

CONTinue

Specifies that control returns to the first command in the premap process of the dialog receiving control. If not specified, control returns to the mapout operation of the dialog that receives control. If the receiving dialog is at the top of a nested application structure, CONTINUE is ignored.

If neither CONTINUE nor RETURN is specified, control passes to the dialog's mapin operation. The runtime system maps the next record into variable storage, then selects the next application function or dialog response process to be executed.

Note: For applications defined using the application compiler, the runtime system first examines the current record's response field. If the field selects an immediately executable function that is not the same as the current function, the runtime system passes control to the selected function. The next time a mapin operation is performed for the file, the runtime system immediately maps in the record.

MESSage message-options

Identifies message to be displayed.

MSG can be used in place of MESSAGE.

Expanded syntax for message-options is shown above immediately following the CONTINUE syntax.

TEXT IS message-text

Specifies the text of a message to be displayed in an online map's message field or sent to a batch application and a system log file.

Message-text specifies either the name of a variable data field containing the message text or the text string itself, enclosed in single quotation marks.

The text string can contain up to 240 displayable characters.

IS or = are optional keywords and have no effect on processing.

CODE IS message-code

Specifies the message dictionary code of a message to be displayed in an online map's message field or sent to the log file in a batch application.

In a batch application, the message is also sent to the operator, if directed by the destination specified in the dictionary.

Message-code specifies either the name of a variable data field that contains the message code or the 6-digit code itself, expressed as a numeric literal.

IS or = are optional keywords and have no effect on processing.

PARMS = parameter

Specifies a replacement parameter for each variable field in the stored message identified by message-code.

Up to nine replacement parameters can be specified for a message. Multiple parameters must be specified in the order in which they are numbered and separated by blanks or commas.

Parameter specifies either the name of an EBCDIC or unsigned zoned decimal variable data field that contains the parameter value or the actual parameter value, enclosed in single quotation marks.

The parameter value must contain displayable characters. At run time, each variable data field in a stored message expands or contracts to accommodate the size of its replacement parameter. A replacement parameter can be a maximum of 240 bytes.

PREFIX IS prefix

Overrides the default prefix of a dialog and a map.

Prefix must either specify an EBCDIC or unsigned zoned decimal variable data field that contains a 2-character prefix or the 2-character prefix itself, enclosed in single quotation marks

IS or = are optional keywords and have no effect on processing.

Usage

Considerations

The named dialog must not be higher than the top of a nested application structure in which the issuing dialog participates.
If the named dialog is operative at more than one higher level, control passes to the lowest level dialog with the specified name.
If the write operation results in a physical output-error condition, the application terminates.
A WRITE TRANSACTION command can be issued in a dialog that is not associated with an output file. In this case, the command is used only to write an input record to the suspense file. If the input record is not in error, nothing is written to the suspense file.
The WRITE TRANSACTION command also allows specification of a message to be sent to the log file or to the operator's console.
The destination of the message depends on the routing codes specified using ADSOBSYS or at run time in a control statement.
If the issuing dialog participates in a nested application structure, control returns to the top of the nested structure.
If the issuing dialog does not participate in a nested structure, control returns to the mainline dialog at the top of the application thread.
If a RETURN statement does not specify a receiving dialog or TOP, control passes to the next higher level dialog or function.
If the mainline dialog at the top of an application thread issues a RETURN command, the RETURN command is treated as a LEAVE APPLICATION command.
Up to nine replacement parameters can be specified for a message.
Multiple parameters must be separated by blanks or commas.
Multiple parameters must be specified in the order in which they occur in the stored message.