READ LINE FROM TERMINAL (COBOL)

The READ LINE FROM TERMINAL statement requests a synchronous, line-by-line transfer of data from the terminal to the issuing program.
idmscu
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-max-length
 ─┘  ►─┬───────────────────────────────────────────────┬─ . ──────────────────────►◄    └─ RETURN LENGTH into 
input-data-actual-length
 ─┘
Parameters
  • ECHO
    Saves the line of data being input in the current page (as displayed on the screen). If you do not specify ECHO, the entered data is not retained and is not available for review by the user. This parameter applies only to 3270-type devices.
  • NOBACKPAGE
    Does not save previously input pages in a scratch area. If you specify NOBACKPAGE, the user can view only the current page of data. NOBACKPAGE is valid only with the first input request in a line mode session. This parameter applies only to 3270-type devices.
  • INTO 
    input-data-location
    Indicates the WORKING-STORAGE SECTION or LINKAGE SECTION entry that is reserved for the input data. Specify the symbolic name of a user-defined field.
  • TO 
    end-input-data-location
    Indicates the end of the WORKING-STORAGE SECTION or LINKAGE SECTION that is reserved for the input data. Specify the symbolic name of a user-defined dummy byte field or a field containing a data item that is not associated with the reserved data area.
  • MAX LENGTH 
    input-data-max-length
    Defines the length of the input data stream in bytes. Specify 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 that is reserved in the WORKING-STORAGE SECTION or LINKAGE SECTION, the data is truncated to fit the available space.
  • RETURN LENGTH into 
    input-data-actual-length
    Indicates where to return the actual length of the input data stream. Specify the symbolic name of a user-defined field. If the data stream has been truncated, the field contains the original length before truncation.
Examples
The following examples illustrate the use of the READ LINE FROM TERMINAL statement.
  • Example 1
    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.
  • Example 2
    The following statement reads the specified data into the program but does not save the pages that are 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
After completion of the READ LINE FROM TERMINAL function, the ERROR-STATUS field in the IDMS-DC communications block indicates the outcome:
Status code
Meaning
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 that was 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 parameters.
4732
The derived length of the specified line input area is zero or negative.
4738
The specified 01-level LINKAGE SECTION 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 user has pressed CLEAR (3270s), ATTENTION (2741s), or BREAK (teletypes).