The WRITE command transfers a character stream specified by its arguments to the current device.
The format of the WRITE command is:
W[RITE][:tvexpr] expr|*intexpr|fcc[,...]
The optional truth-valued expression immediately following the command is a command postconditional that controls whether or not GT.M executes the command.
An expression argument supplies the text of a WRITE.
When a WRITE argument consists of a leading asterisk (*) followed by an integer expression, WRITE outputs one character associated with the ASCII code specified by the integer evaluation of the expression.
WRITE also accepts format control characters as arguments; format control characters modify the position of a virtual cursor: an exclamation point (!) produces the device specific record terminator (for example, new line for a terminal), a number sign (#) produces device specific page terminator (for example, form feed for a terminal) and a question mark (?) followed by an expression moves the virtual cursor to the column specified by the integer evaluation of the expression if the virtual cursor is to the "left" of the specified column.
When directed to a device bound to a mnemonicspace, WRITE also accepts controlmnemonics, which are keywords specific to the binding – they are delimited by a slash (/) prefix and optionally followed by a parenthetical list of arguments. The parentheses "( )" are optional when there are no arguments, but must appear even if there is a single argument
An indirection operator and an expression atom evaluating to a list of one or more WRITE arguments form a legal argument for a WRITE.
GT.M can write up to 1,048,576 bytes (the GT.M maximum string size) as a result of a single WRITE argument. GT.M buffers output into a "logical record" for all devices except sockets without DELIMITERs and sequential devices with STREAM enabled. The WRITE command appends a string to the current record of the current device. GT.M does not write to the output device until the buffer is full, a GT.M format control character forces a write, a USE command, a CLOSE command, or, for terminals, the buffer becomes stale .
Each device has a WIDTH and a LENGTH that define the virtual "page". The WIDTH determines the maximum size of a record for a device, while the LENGTH determines how many records fit on a page. When the current record size ($X) reaches the maximum WIDTH and the device has WRAP enabled, GT.M starts a new record. When the current line ($Y) reaches the maximum LENGTH, GT.M starts a new page.
For devices OPENed with a Unicode CHSET, WRITE * takes intexpr as a code-point and writes the associated Unicode character in the encoding specified by CHSET. For devices OPENed in M mode, WRITE * takes intexpr as an ASCII value and writes the associated ASCII character.
The WRITE command also has several format control characters that allow the manipulation of the virtual cursor. For all I/O devices, the GT.M format control characters do the following:
WRITE !: Clears $X and increments $Y and terminates the logical record in progress. The definition of "logical record" varies from device to device, and is discussed in each device section.
WRITE #: Clears $X and $Y and terminates the logical record in progress.
WRITE ?n: If n is greater than $X, writes n-$X spaces to the device, bringing $X to n. If n is less than or equal to $X, WRITE ?n has no effect. When WRAP is enabled and n exceeds the LENGTH of the line, WRITE ?n increments $Y.
![[Note]](images/note.jpg) | |
If $X is less than WIDTH, WRITE ! writes WIDTH - $X spaces. |
For devices OPENed with a Unicode CHSET, WRITE * takes intexpr as a code-point and writes the associated Unicode character in the encoding specified by CHSET. For devices OPENed in M mode, WRITE * takes intexpr as an ASCII value and writes the associated ASCII character.
In UTF-8 mode, if a WRITE command encounters an illegal character, it produces a run-time error irrespective of the setting of VIEW "BADCHAR".
For more information, see the sections on specific I/O devices.