|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
GETS(channel, data_area[, label][, WAIT:wait_spec][, MASK:act_char]) [[error_list]]
Arguments
channel
The channel from which to get the data. The channel must already have been opened in input, output, or append mode or updated if it is a file. (n)
On OpenVMS, channel must be opened to a file with stream record format or to a serial or terminal device.
data_area
A variable that will contain the data. The size of the variable determines how many characters are received. For example, a data area of 623 receives the next 623 characters. If the data area is a file and the file contains too few characters, the remainder of the file is transferred into the data area, but an “End of file” error ($ERR_EOF) is generated. (a)
label
(optional) A label to which control is transferred if an “End of file” error ($ERR_EOF) occurs.
WAIT
(optional) The time to wait for serial or terminal input. See WAIT for a complete description.
MASK
(optional) Activation characters at the statement level. See MASK for a complete description. (traditional Synergy only)
error_list
(optional) An I/O error list. If any one of the specified errors occurs during the GETS, control is transferred to the associated label.
Discussion
The GETS statement reads sequential binary data from the specified channel to the designated data area. It does not interpret the data being transmitted, except that it terminates on activation characters. GETS assumes that each character is an 8-bit binary value.
During GETS processing, record terminators are not automatically attached or stripped. Your program can maintain complete control of the input file’s contents and can process every character in the input file with the GETS statement.
The MASK qualifier enables you to specify your own activation characters to replace those specified by the ACCHR, ACESC, DACHR, or DAESC subroutines. This only applies to a serial or terminal device. The termination character is not returned in the data buffer and is not included in the number of characters (%RSIZE or %RDLEN), but this character can be obtained by calling %RTERM (or %RDTRM). If the GETS MASK is all zeros (nulls) and FLAGS flag 9 is set, no standard activation characters are honored and the input is terminated on input buffer full or EOF.
If you specify the WAIT qualifier with a value of zero, GETS reads all currently pending characters. If the WAIT value is nonzero, the runtime waits either for the field to be filled, an activation character to be found, or the time to elapse. If the time expires, the runtime generates a “Terminal input operation timeout” error ($ERR_TIMOUT), which you can trap. Use %RSIZE (or %RDLEN) to return the number of characters read.
If the channel is opened to the console terminal (TT:), the GETS statement works much like the READS statement, with one exception. When a nonterminating character exceeds the receiving data area, the READS statement ignores the character and echoes an ASCII bell character to warn the user. The GETS statement, on the other hand, immediately stops the input and suppresses echoing of the typed character. GETS is not binary-capable from TT: and would need to use the FLAGS routine to disable echo and automatic uppercasing of input. GETS always terminates on CR or LF to TT: and honors 127 (delete).
|
Avoid doing single-character GETS/ACCEPT sequences with the TTSTS subroutine (which slows down the system). A computer may be slowed noticeably by trying to accept characters at 9600 baud. Instead, use GETS with the WAIT and MASK qualifiers for timed I/O to a serial port. In this mode, several devices at 9600 baud can be handled simultaneously. For more information about serial ports on Unix, see INITPORT. |
In Synergy .NET, the GETS statement is for console applications only and is not intended to be used in low-level windowing applications (i.e., those that use the Synergy windowing API). WD_GETS should be used instead of GETS in this scenario.
For Windows non-interactive and .NET runtimes, GETS does not honor the WAIT qualifier and will wait forever for a terminating condition. (However, WAIT does work when running a .NET application on Linux.) In addition, GETS from a channel opened to TT: does not honor activation characters.
For the regular runtime (dbr) on Windows, certain Windows reserved characters, such as tab, cannot be input with GETS from TT:.
On OpenVMS, GETS is not allowed from TT: when the input is redirected.
See also
Input and output statement qualifiers
Examples
The first two examples below use the following data division.
record
area1 ,a38
area2 ,a1967
area3 ,a5
The following example receives the next 38 characters from the specified channel. It returns only when all 38 characters are received or when one of the characters matches an activation character. If fewer than 38 characters are left on the channel, the program terminates with an “End of file” error ($ERR_EOF).
gets(CHN, area1)
The following example transmits the next 1967 characters from the specified channel. If fewer than 1967 characters remain, control transfers to the statement labeled end_data.
gets(CHN, area2) [eof=end_data]
In the next example, the GETS statement terminates if and when the buffer is full or a plus (+) character is read.
record
.align LONG
actchars ,[32]i2
.
.
.
clear actchars[]
actchars[2] = 2048 ;Activate on '+'
gets(chan, in_field, eof_label, WAIT:Q_WAIT, MASK:actchars)
