The READ command transfers input from the current device to a global or local variable specified as a READ argument. For convenience, READ also accepts arguments that perform limited output to the current device.
The format of the READ command is:
R[EAD][:tvexpr] glvn|*glvn|glvn#intexpr|strlit|fcc[,...]
The optional truth-valued expression immediately following the command is a command postconditional that controls whether or not GT.M executes the command.
A subscripted or unsubscripted global or local variable name specifies a variable into which to store the input; the variable does not have to exist prior to the READ; if the variable does exist prior to the READ, the READ replaces its old value.
For fixed format files, READ X always read WIDTH characters.
For VARIABLE or STREAM format files, READ X reads up to WIDTH characters, stopping if a line terminator or end of file is found first.
When an asterisk (*) immediately precedes the variable name, READ accepts one character of input and places the ASCII code for that character in the variable.
When a number sign (#) and a non-zero integer expression immediately follow the variable name, the integer expression determines the maximum number of characters accepted as input to the read; such reads terminate when GT.M reads the number of characters specified by the integer expression or a terminator in the input stream, whichever occurs first.
To provide a concise means of issuing prompts, GT.M sends string literal and format control character (!,?intexpr,#) arguments of a READ to the current device as if they were arguments of a WRITE.
An indirection operator and an expression atom evaluating to a list of one or more READ arguments form a legal argument for a READ.
The maximum length of the input string is the smaller of the device buffer size limitation or the GT.M maximum string size (1,048,576 bytes). If a record is longer than the maximum record length, GT.M returns the record piece by piece during sequential reads, for devices that allow it.
When a string literal appears as an argument to a READ, M writes the literal to the current device. String literals appear as READ arguments to serve as prompts for input. GT.M does not permit expression arguments on a READ to act as prompts. Variable prompts must appear as arguments to a WRITE. If a variable appears as an argument to a READ, GT.M always interprets it as input, never as output. This facility is used mostly with terminal I/O.
The READ commands adjust $X and $Y, based on the length of the input read.
In UTF-8 mode, the READ command uses the character set value specified on the device OPEN as the character encoding of the input device. If character set "M" or "UTF-8" is specified, the data is read with no transformation. If character set is "UTF-16", "UTF-16LE", or "UTF-16BE", the data is read with the specified encoding and transformed to UTF-8. If the READ command encounters an illegal character or a character outside the selected representation, it produces a run-time error. The READ command recognizes all Unicode™ line terminators for non-FIXED devices. See “Line Terminators” section for more details. In M mode, characters and bytes have a one-to-one relationship and therefore READ can be used to read bit-streams of non-character data.
The READ * command reads one character from the current device and returns the decimal ASCII representation of that character into the variable specified for the READ * command. READ * appears most frequently in communication protocols, or in interactive programs where single character answers are appropriate.
In UTF-8 mode, the READ * command accepts one character in Unicode of input and puts the numeric code-point value for that character into the variable. The READ * command reads one to four bytes, depending on the encoding and returns the numeric code-point value of the character. If ICHSET specifies "UTF-16", "UTF-16LE" or "UTF-16BE", the READ * command reads a byte pair or two byte pairs (if it is a surrogate pair) and returns the numeric code-point value. If ICHSET is M, the READ * command reads a single byte and returns the numeric byte value just like in M mode.
The following example reads the value "A", and returns the decimal ASCII representation of "A" in the variable X.
Example:
GTM> READ *X A GTM> WRITE X 65
If a timeout occurs before GT.M reads a character, the READ * returns a negative one (-1) in the variable.
GTM>Set filename="mydata.out"; assume that mydata.out contains "主要雨在西班牙停留在平原".
GTM>Open filename:(readonly:ichset="UTF-16LE")
GTM>Use filename
GTM>Read *x
GTM>Close filename
GTM>Write $char(x)
主In this example, the READ * command reads the first character of the file mydata.out according to the encoding specified by ICHSET.