Updated March 2024; see History
xcall GET, buffer {,chan, bytes'req, bytes'rcvd, timeout, flags}
GET is useful for simple or sophisticated input of raw characters from the keyboard or a file. Under Unix/Linux, it may also be used for Inputting from a serial device. See COMIO for serial I/O under Windows.
Parameters
buffer (String, may be dynamic) [out]
receives the byte(s) input. Note that no trailing null byte is added by the subroutine, so you may want to pre-clear this variable before calling GET. In the simplest case of GET where no parameters beyond buffer are specified, it will input a single character from the keyboard, waiting as long as necessary.
chan (Num) [in] (optional)
File channel number of a file that has been opened for input, and from which the character(s) are to be read. If not specified, or zero, input is from the keyboard.
bytes’requested (Num) [in] (optional)
Number of bytes to input. If not specified, default is 1. You can specify 0 in conjunction with the timeout feature if you just want to know if a character is available without actually inputting it. Two special values are supported: -1 requests a line of input terminating with LF (and ignoring CR); -2 requests a line of input terminating with CR (and ignoring LF). Note that for the special values -1 and -2, the terminating CR and/or LF will not be included in buffer, but will be included in the count in bytes'received.
bytes’ received (Num) [out] (optional)
Returns the number of bytes that were actually input (and returned into the Buffer parameter). Normally this will be the same as bytes’requested, except in the following circumstances:
If bytes’requested was 0, then bytes’received will be 1 if there was one or more characters available to be input, or 0 to indicate no characters available.
If we hit the end of the input file, or the timeout period expires before reading the number of requested bytes, then bytes’received will be less than bytes’requested.
If an I/O error occurs, or if a timeout period is specified and no characters are input because the file was already at the end-of-file mark, bytes’received will be set to -1. This distinguishes the case of end-of-file from timeout.
When bytes'requested is set to -1 or -2, bytes'received will be set to the total number of bytes received, including the terminating character(s). However, the terminating characters (CR and/or LF) are not returned in buffer.
timeout (Num) [in] (optional)
Number of milliseconds to wait for input before aborting. If set to 0 or not specified, there is no timeout. Note that the actual elapsed time may be substantially longer that the specified period. This is both because of CPU time dedicated to other processes and because the total timeout period is actually divided into slices equal to the number of characters to be input, with each slice being used up only if no characters are available.
For example, if you have a 5000 millisecond (5 second) timeout and are requesting 5 characters, then you will actually be allotted 5 one-second timeout periods, and each period is only spent if no characters are input during that period. If exactly one character arrived every 0.75 seconds, then you would still have five unused seconds after four characters had be input, even though three seconds had actually elapsed. This scheme may seem a bit strange, but is actually a reasonable compromise between the two extreme approaches of treating the timeout period as an absolute maximum or of resetting it entirely after each character.
Note: In order for the timeout to be reliable when inputting from a device such as a serial port, you must first disable buffering on the input channel (see MX_NOBUF). Failure to do so could result in apparently flaky behavior, since the timeout mechanism may not be aware of buffered characters, thus leading to false timeouts.
flags (Num) [in] (optional)
Value |
Description |
|---|---|
&h01 |
Raw mode. See notes below. |
&h02 |
Convert CRLF to CR. |
Raw mode eliminates all input processing and filtering such as function key support, terminal driver input translations, and adds the ability to input null bytes. Otherwise, null bytes are stripped out of the input stream before your application gets a chance to see them. Note the following restrictions on the flags parameter:
| • | Under Unix, setting flags=1 and bytes'req=0 (in order to check if any characters are available without inputting anything) will properly return bytes'rcvd=1 if anything is available to input, but if the first byte available is a null, it will be lost. So it is best to just set bytes'req to the number of bytes you want, and use timeout to avoid getting stuck in an input wait. |
| • | Under Windows, input processing occurs asynchronously as characters arrive, not as they are requested by the application. So the raw flag will only be useful if the XCALL GET occurs before the characters in question arrive. |
Comments
| • | When inputting from the keyboard, NOECHO will be set automatically and left that way on exit. |
| • | GET may also be used to check if a character is available without waiting and without actually inputting the character, by setting bytes’requested and timeout to zero. This is equivalent to GETKEY(-2). |
History
2024 March, A-Shell 7.0.1757: Add flags value &h02.
