GET statements

Syntax

GET[X] read.var[ , length ] [ SETTING read.count ] FROM device 
[ UNTIL eop.char.list ] [ RETURNING last.char.read ]
[ WAITING seconds ] [ THEN statements ] [ ELSE 
statements ]

Description

Use GET statements to read a block of data from an input stream associated with a device, such as a serial line or terminal. The device must be opened with the OPENDEV statement or OPENSEQ statement. Once the device has been opened, the GET statements read data from the device. The GET statements do not perform any pre- or postprocessing of the data stream, nor do they control local echo characteristics. These aspects of terminal control are handled either by the application or by the device driver. The behavior of certain devices can be managed through the TTYSET statement/TTYGET statement interface.

Note: The WAITING clause is not supported on Windows.

Use the GETX statement to return the characters in ASCII hexadecimal format. For example, the sequence of 8-bit character "abcde" is returned as the character string "6162636465". However, the value returned in the last.char.read variable is in standard ASCII character form.

read.var is the variable into which the characters read from device are stored. If no data is read, read.var is set to the empty string.

length is the expression evaluating to the number of characters read from the data stream; if length and timeout are not specified, the default length is 1. If length is not specified, but an eop.char.list value is included, no length limit is imposed on the input.

read.count is the variable that records the actual count of characters read and stored in read.var. This might differ from length when a timeout condition occurs or when a recognized end-of-packet character is detected.

device is a valid file variable resulting from a successful OPENDEV or OPENSEQ statement. This is the handle to the I/O device that supplies the data stream for the operation of the GET statements.

eop.char.list is an expression that evaluates to a recognized end-of-packet delimiters. The GET operation terminates if a valid end-of-packet character is encountered in the data stream before the requested number of characters is read.

last.char.read is a variable that stores the last character read by the GET operation. If no data is read, read.var is set to the empty string. If the input terminated due to the maximum number of characters being read or because of a timeout condition, an empty string is returned.

seconds specifies the number of seconds the program should wait before the GET operation times out.

Terminating Conditions

GET statements read data from the device's input stream until the first terminating condition is encountered. The following table lists the possible terminating conditions:

Table 1. GET Statements Terminating Conditions
Condition	Description
Requested read length has been satisfied	The read is fully satisfied. read.var contains the characters read, and last.char.read contains an empty string. Program control passes to the THEN clause if present. The default requested read length is one character unless an end-of-packet value has been selected (in which case, no length limit is used).
Recognized end-of-packet character has been processed	The read is terminated by a special application-defined character in the data stream. The data read to this point, excluding the end-of-packet character, is stored in read.var. The end-of-packet character is stored in last.char.read. Program control passes to the THEN clause if present. This terminating condition is only possible if the UNTIL clause has been specified. If there is no UNTIL clause, no end-of-packet characters are recognized.
Timeout limit has expired	The read could not be satisfied within the specified time limitation. If no characters have been read, read.var and last.char.read are set to the empty string, and read.count is set to 0. The system status code is set to 0 and might be checked with the STATUS function. Control passes to the ELSE clause if present. This condition is only possible if the WAITING clause is specified. In the absence of a WAITING clause, the application waits until one of the other terminating conditions is met.
Device input error	An unrecoverable error occurred on the device. Unrecoverable errors can include EOF conditions and operating system reported I/O errors. In this case, the data read to this point is stored in read.var, and the empty string is stored in last.char.read. If no characters have been read, read.var and last.char.read are set to the empty string, and read.count is set to 0. The system status code is set to a nonzero value and might checked with the STATUS function. Control passes to the ELSE clause if present.

Note: Under all termination conditions, read.count is set to the number of characters read from the input data stream.

THEN and ELSE Clauses

For GET statements, the THEN and ELSE clauses are optional. They have different meanings and produce different results, depending on the conditions specified for terminal input.

The following rules apply only if the THEN or ELSE clauses are specified:

If the UNTIL clause is used without a WAITING clause or an expected length, the GET statement behaves normally. The program waits indefinitely until a termination character is read, then executes the THEN clause. The ELSE clause is never executed.
If the WAITING clause is used, the GET statement behaves normally, and the ELSE clause is executed only if the number of seconds for timeout has elapsed. If the input terminates for any other reason, it executes the THEN clause.
If the WAITING clause is not used and there is a finite number of characters to expect from the input, then only the type-ahead buffer is examined for input. If the type-ahead buffer contains the expected number of characters, it executes the THEN clause; otherwise it executes the ELSE clause. If the type-ahead feature is turned off, the ELSE clause is always executed.
In a special case, the ELSE clause is executed if the line has not been attached before executing the GET statement.

In summary, unless the WAITING clause is used, specifying the THEN and ELSE clauses causes the GET statement to behave like an INPUTIF statement...FROM statement. The exception to this is the UNTIL clause without a maximum length specified, in which case the GET statement behaves normally and the ELSE clause is never used.

Example

The following code fragment shows how the GET statement reads a number of data buffers representing a transaction message from a device:

DIM SAVEBUFFER(10)
SAVELIMIT = 10
OPENDEV "TTY10" TO TTYLINE ELSE STOP "CANNOT OPEN 
TTY10"
I = 1
LOOP
      GET BUFFER,128 FROM TTYLINE UNTIL CHAR(10) 
WAITING 10
      ELSE
         IF STATUS()
         THEN PRINT "UNRECOVERABLE ERROR DETECTED ON 
DEVICE,
"IM SAVEBUFFER(10)
SAVELIMIT = 10
OPENDEV "TTY10" TO TTYLINE ELSE STOP "CANNOT OPEN 
TTY10"
I = 1
LOOP
      GET BUFFER,128 FROM TTYLINE UNTIL CHAR(10) 
WAITING 10
      ELSE
         IF STATUS()
         THEN PRINT "UNRECOVERABLE ERROR DETECTED ON 
DEVICE,":
         ELSE PRINT "DEVICE TIMEOUT HAS OCCURRED, ":
         PRINT "TRANSACTION CANNOT BE COMPLETED."
         STOP
      END
   WHILE BUFFER # "QUIT" DO
      IF I > SAVELIMIT
      THEN
         SAVELIMIT += 10
         DIM SAVEBUFFER(SAVELIMIT)
      END
      SAVEBUFFER(I) = BUFFER
      I += 1
REPEAT