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

WRITE TERMINAL (DC/UCF)

The WRITE TERMINAL statement requests a synchronous or asynchronous data transfer from program variable storage to the terminal buffer.

Syntax

►►─── WRITE TERMINAL ─┬──────────┬─┬─────────────────────────────┬────────────►
                      ├─ WAIT ◄ ─┤ ├─┬─ NEWPAGE ─┬───────────────┤
                      └─ NOWAIT ─┘ │ └─ ERASE ───┘               │
                                   └─┬─ EAU ───────────────────┬─┘
                                     └─ ERASE ALL UNPROTECTED ─┘

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

Parameters

WAIT/NOWAIT

Indicates whether the write operation is to be synchronous or asynchronous.

WAIT

Specifies that the write operation will be synchronous; the issuing task will automatically relinquish control to the system and wait for completion of the write operation before continuing processing. WAIT is the default.

NOWAIT

Specifies that the write operation will be asynchronous; the issuing task will continue executing.

Note: If NOWAIT is specified, the program must issue a CHECK TERMINAL request (described earlier in this section) before performing any other I/O operation.

NEWPAGE/EAU

Specifies the mechanism to be used with the write operation.

NEWPAGE

Activates the page-eject (SYSINOUT devices) or erase-write (3270-type devices) mechanism to erase the contents of a screen. If NEWPAGE is not specified, the WRITE TERMINAL request will write over rather than erase data displayed on the terminal. The keywords NEWPAGE and ERASE are synonymous.

EAU

Activates (for 3270-type devices only) the erase-all-unprotected mechanism. Following a WRITE TERMINAL EAU function, only protected fields remain on the terminal. If EAU is specified, the FROM clause (described below) need not be specified.

FROM (output-data-location)

Specifies the program variable-storage entry of the output data stream. Output-data-location is the symbolic name of a user-defined field. The length of the output data stream is determined by one of the following specifications:

TO (end-output-data-location)

Indicates the end of the output data stream and is specified following the last data-item entry in output-data-location. End-output-data-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 output data stream.

LENGTH (output-data-length)

Defines the length, in bytes, of the output data stream. Output-data-length is either the symbolic name of a user-defined field that contains the length of the data area, or the length itself expressed as a numeric constant.

Example

The following statement illustrates an asynchronous basic mode request to write data to the terminal from the specified location in program variable storage:

WRITE TERMINAL
  NOWAIT
  FROM (TERM_LINE) LENGTH (72);

Status Codes

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

0000

The request has been serviced successfully.

4525

The output operation has been interrupted; the terminal operator has pressed ATTENTION or BREAK.

4526

A logical error (for Example, an invalid control character) has been encountered in the output data stream.

4527

A permanent I/O error has occurred during processing.

4528

The dial-up line for the terminal has been disconnected.

4531

The terminal request block (TRB) contains an invalid field, indicating a possible error in the program's parameters.

4532

The derived length of the specified output data area is zero or negative.

4539

The terminal associated with the issuing task is out of service.