Data Manipulation Language Statements › READ LINE FROM TERMINAL (DC/UCF)

READ LINE FROM TERMINAL (DC/UCF)

The READ LINE FROM TERMINAL statement requests a synchronous, line-by-line transfer of data from the terminal to the issuing program.

Syntax

►►─── READ LINE FROM TERMINAL ─┬────────┬─┬──────────────┬────────────────────►
                               └─ ECHO ─┘ └─ NOBACKPAGE ─┘

 ►─ INTO (input-data-location) ┬ TO (end-input-data-location) ──────────────┬─►
                               └ MAX LENGTH (input-data-location-max-length)┘

 ►─┬─────────────────────────────────────────────────┬─ ; ────────────────────►◄
   └─ RETURN LENGTH INTO (input-data-actual-length) ─┘

Parameters

ECHO

Requests (for 3270-type devices only) that the system to save the line of data being input in the current page (as displayed on the screen). If ECHO is not specified, data entered will not be retained and, therefore, will not be available for review by the terminal operator.

NOBACKPAGE

Requests (for 3270-type devices only) that the system not save previously input pages in a scratch area. If NOBACKPAGE is specified, the terminal operator can view only the current page of data. NOBACKPAGE is valid only with the first input request in a line mode session.

INTO (input-data-location)

Indicates the program variable-storage entry reserved for the input data. Input-data-location is the symbolic name of a user-defined field. The length of the data area is determined by one of the following specifications:

TO (end-input-data-location)

Indicates the end of program variable storage reserved for the input data stream and is specified following the last data-item entry in input-data-location. End-input-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 data area reserved for the input data stream.

MAX LENGTH (input-data-location-max-length)

Defines the length, in bytes, of the input data stream. Input-data-max-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.

If the input data stream is larger than the data area reserved in program variable storage, the system truncates the data to fit the available space.

RETURN LENGTH INTO (input-data-actual-length)

Indicates the location to which the system will return the actual length of the input data stream. Input-data-actual-length is the symbolic name of a user-defined field. If the data stream has been truncated, input-data-actual-length contains the original length before truncation.

Example

The following statement reads the specified data from a 3270-type device into the specified location in the program and echoes the input data on the screen:

READ LINE FROM TERMINAL
  ECHO
  INTO (EMPL_DATA) TO (END_EMPL_DATA);

The following statement reads the specified data into the program without saving pages associated with the line I/O session:

READ LINE FROM TERMINAL
  NOBACKPAGE
  INTO (EMPL_DATA) MAX LENGTH (8)
  RETURN LENGTH INTO (REC_DATA_LENGTH);

Status Codes

Upon completion of the READ LINE FROM 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.

4707

A logical or permanent I/O error has been encountered in the input data stream.

4719

The input area specified for the return of data is too small; the returned data has been truncated to fit the available space.

4731

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

4732

The derived length of the specified line input area is zero or negative.

4738

The specified program variable-storage entry has not been allocated as required. A prior GET STORAGE request must be issued.

4743

The line I/O session has been canceled; the terminal operator has pressed CLEAR (3270s), ATTENTION (2741s), or BREAK (teletypes).