COMREAD

The COMREAD instruction retrieves data from the communications device. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

comfile

Required. A previously defined and opened COMFILE definition.

eot

Optional. A Character String Variable or Literal containing a list of characters that act as End-of-Text (EOT) characters.

filter

Optional. A Character String Variable or Literal containing a list of characters that are stripped from the input stream before being placed in the {comlist} variable(s).

comlist

Required. A list of Character String Variables, individual character string array elements, entire character string array, VARLIST of character strings, or COMREAD List Controls.

;

Optional. A semicolon indicating Partial I/O.

Flags Affected: EOS, OVER, ZERO

Note the following:

1. If one of the optional {eot} characters in the list is received, the COMREAD instruction is terminated. Any data in the buffer beyond the {eot} character is ignored.

2. The optional {filter} variable contains a list of characters that are stripped from the input stream before being placed into the variable. The characters in {filter} may be the same or all of the same characters in {eot}. If they are, they terminate the COMREAD but are not placed in the data variable.

3. Individual items within {comlist} are separated with commas. The list may be continued on additional lines by ending each continued line with a colon (:).

4. The {comfile} variable specifies the input device that must have been previously opened via the COMOPEN instruction.

5. The OVER flag is set if a time-out occurs during the COMREAD operation.

6. The EOS flag is set if a defined End-Of-Text character is received.

7. The ZERO flag is set if the last variable was filled completely when the End-Of-Text character was received.

8. {comlist} character variables are processed as follows:

• The data is stored beginning with the first physical character of the string.

• The number of characters placed in a variable cannot exceed the Physical Length.

• If a null string is received, both the Form Pointer and Length Pointer are set to zero (0).

• If data is received, the Form Pointer is set to one (1) and the Length Pointer points to the last character received.

• If an item within the list is a character string ARRAY and no specific array element has been specified, every array element is used.

9. If a semi-colon (;) terminates the list, the communication buffer pointers are positioned immediately after the last character processed. This allows another COMREAD instruction to retrieve any remaining data in the communication buffer. Without the semi-colon, any trailing data would be discarded.

10. Under Windows, it is not possible for a user to interrupt a time-out.

11. When using a Linux runtime where the {comfile} is opened for a file/device, the *T timeout read control is not used.

See Also: COMREAD List Controls, COMWRITE, Communication I/O Instructions