GET

Receive data from a channel

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
GET(channel, data_area, record) [[error_list]]

Arguments

channel

The channel from which to get the data. The channel must already have been opened in input, output, append, or update mode, with no submode specified. (n)

On OpenVMS, if channel is open to a disk file, the file must have a stream record format.

data_area

A variable that will contain the input characters. The size of the data area determines how many characters are received. If the file contains too few characters, you’ll get an “End of file” error ($ERR_EOF). (a)

record

An expression defining which record is read. If the value is less than 1, you’ll get an “Illegal record number specified” error ($ERR_RECNUM). (n)

error_list

(optional) An I/O error list. If any one of the specified errors occurs during the GET, control is transferred to the associated label.

Discussion

The GET statement receives or reads data from the specified channel and places it in the designated data area. It performs random‑access, binary input. It does not interpret the data being transmitted, and assumes that each character is an 8‑bit binary value.

The record number is interpreted according to the size of the data area. The starting position is calculated as follows:

((record - 1) * (size of data_area)) + 1

During GET processing, record terminators are not automatically attached or stripped. Your program can maintain complete control of the output file’s contents and can process every character in the input file with the GET statement.

See also

I/O error lists.

Examples

The examples below use the following data division.

record
    area1       ,a38
    area2       ,a1967
    area3       ,a5

The following example receives the 123rd 38‑byte record from the specified channel. If less than 123 records (of 38 bytes each) are left in the file, the program terminates with an “End of file” error ($ERR_EOF).

get(CHN, area1, 123)

The next example reads a 1967‑byte record, whose record number is given in recno. If the record is beyond the end‑of‑file, control is transferred to the statement labeled end_data.

get(CHN, area2, recno) [eof=end_data]