This section describes the following GT.M I/O commands:
OPEN establishes a connection from a GT.M process to a device.
USE declares a device as the current source of input and destination for output.
READ accepts characters from the current device into a global or local variable.
WRITE sends characters to the current device.
CLOSE breaks the connection between a GT.M process and a device.
The OPEN command establishes a connection from a GT.M process to a device.
The format of the OPEN command is:
O[PEN][:tvexpr] expr[:[(keyword[=expr][:...])][:numexpr][:expr]][,...]
The optional truth-valued expression immediately following the command is a command postconditional that controls whether or not GT.M executes the command.
The required expression specifies the device to OPEN.
The optional keywords specify deviceparameters that control device behavior; some deviceparameters take arguments delimited by an equal sign (=); if the argument only contains one deviceparameter, the surrounding parentheses are optional.
The optional numeric expression specifies a time in seconds after which the command should timeout if unsuccessful; 0 provides a single attempt to open the device.
When an OPEN command specifying a timeout contains no deviceparameters, double colons (::) separate the timeout numeric expression from the device expression.
The optional expression specifies a mnemonicspace that selects a device binding. The only mnemonicspaces that GT.M currently accepts are SOCKET and PIPE.
When an OPEN command specifies a mnemonicspace with no timeout, double colons separate the mnemonicspace string expression from the deviceparameters; if there are neither a timeout nor deviceparameters, triple colons separate the SOCKET mnemonicspace from the device expression.
A triple colon for the PIPE menemonicspace produces an error.
An indirection operator and an expression atom evaluating to a list of one or more OPEN arguments form a legal argument for an OPEN.
For sequential files, multiple processes can open the same file for reading with the OPEN command.
By default, when a device is unavailable, GT.M retries the OPEN indefinitely at approximately one second intervals. A device is unavailable when another process is using it exclusively, or when the OPENing process does not have the resources left to open the device.
All other errors on OPEN raise an error condition and interrupt program flow. A timeout is a tool that lets a GT.M routine regain program control when a device remains unavailable. When the OPEN specifies a timeout, GT.M keeps retrying until either the OPEN succeeds or the timeout expires.
If OPEN establishes a connection with a device before the timeout expires, GT.M sets $TEST to TRUE (1). If the timeout expires, GT.M sets $TEST to FALSE (0). If an OPEN command does not specify a timeout, the execution of the command does not affect $TEST.
If a process has not previously OPENed a device, any deviceparameters not supplied on the OPEN take their default values. When reOPENing a device that it previously closed, a GT.M process restores all characteristics not specified on the OPEN to the values the device had when it was last CLOSEd, except with SD, FIFO, and PIPE. If you have a menu-driven application that OPENs and CLOSEs devices based on user selections, take care that every OPEN explicitly includes all deviceparameters important to the application.
GT.M treats sequential disk files differently and uses defaults for unspecified sequential disk file characteristics on every OPEN (i.e., GT.M does not retain sequential disk file characteristics on a CLOSE).
If a process OPENs an already OPEN device, GT.M modifies any characteristics that accept changes when a device is OPEN to reflect any new deviceparameter specifications.
In UTF-8 mode, the OPEN command recognizes ICHSET, OCHSET, and CHSET as three additional deviceparameters to determine the encoding of the the input / output devices.
In M mode, the OPEN command ignores ICHSET, OCHSET, CHSET, and PAD device parameters.
If an I/O device uses a multi-byte character encoding, every READ and WRITE operation of that device checks for well-formed characters according to the specified character encoding with ICHSET or OCHSET. If the I/O commands encounter an illegal sequence of bytes, they always trigger a run-time error; a VIEW "NOBADCHAR" does not prevent such errors. Strings created by $ZCHAR() and other Z equivalent functions may contain illegal sequences. The only way to input or output such illegal sequences is to specify character set "M" with one of these deviceparameters.
Example:
set sd="report.dat" open sd:newversion
This OPENs a NEWVERSION of a sequential disk file named report.dat for both read and write access.
APPEND Applies to: SD
Positions the file pointer at the end-of-file. This deviceparameter only affects the device on the first OPEN command. Re-OPENing an already OPEN device with this deviceparameter has no effect.
By default, OPEN sets the file pointer to the beginning-of-file.
Example:
set sd="foo.txt" open sd:(append:recordsize=70:wrap) use sd
This example open file foo.txt and positions the file pointer at the end of the file. Note that $ZEOF evaluates to TRUE (or 1) immediately after the USE command.
ATTACH=expr Applies to: SOC
ATTACH assigns expr as the handle name to the newly created socket. When ATTACH is used and one of LISTEN or CONNECT is specified on the same OPEN, the value of expr becomes the identifier of the newly created socket. If neither LISTEN nor CONNECT is specified, ATTACH is ignored.
For information on using the ATTACH with USE, refer to “ATTACH” in the USE Deviceparameters section.
Example:
open tcpdev:(ichset="M":connect=hostname_":"_portno_":TCP":attach="client"):timeout:"SOCKET"
This example uses the ATTACH deviceparameter to specify "client" as the identifier of the newly created socket. Note that GT.M recognizes ICHSET only in UTF-8 mode.
CHSET=expr Applies to: All devices
Establishes a common encoding for both input and output devices for the device being OPENed in UTF-8 mode. The value of the expression can be M, UTF-8, UTF-16, UTF-16LE, or UTF-16BE. For more information, refer to “ICHSET” and “OCHSET”.
COMMAND=expr Applies to: PIPE
Specifies the UNIX command the newly created shell process performs. An invalid command value triggers an error in the new process, not the process issuing the OPEN. This can make diagnosis difficult - see the “PARSE” deviceparameter for potential assistance.
CONNECT=expr Applies to: SOC
Creates a client connection with a server, which is located by the information provided by expr. A new socket is allocated for the client connection and is made the current socket for the device, if the operation is successful.
expr specifies the protocol and the protocol-specific information. Currently, GT.M supports TCP/IP and LOCAL (also known as UNIX domain) socket protocols. For TCP/IP sockets, specify expr in the form of "<host>:<port>:TCP", where host is an IPv4 or IPv6 address optionally encapsulated by square-brackets ([]) like "127.0.0.1", "::1", "[127.0.0.1]", or "[::1]" or a IPv4 or IPv6 hostname like server.fis-gtm.com. When a hostname is specified, GT.M uses the IP version of the first address returned by DNS:
that is supported by the operating system, and
for which a network interface exists.
For LOCAL sockets, specify expr in the form of "<pathname>:LOCAL", where <pathname> is the name of the file to be used for communication. <pathname> may contain a dollar sign ($) followed by the name of an environment variable which GT.M expands in the same way as the device name for a sequential file. The maximum allowed length of the expanded path name depends on the OS.
For LOCAL sockets, CONNECT attempts to open the specified file. If it doesn't exist or there is no listener, CONNECT retries until it succeeds or a specified timeout expires.
![[Note]](../common/images/note.jpg) | Note |
|---|---|
CONNECT is not compatible with LISTEN. |
If the OPEN does not specify a timeout, a SOCKET OPEN waits for the connection to complete or an event that terminates the attempt.
Example:
open tcpdev:(connect=hostname_":"_portno_":TCP":attach="client":ioerror="TRAP"):timeout:"SOCKET"
This example establishes a client connect with the server using the connection string in the format of "hostname:port:TCP".
[NO]DELIMITER=expr Applies to: SOC
DELIMITER establishes or replaces the list of delimiters used by the newly created socket. The default is NODELIMITER. The delimiter list on a preexisting device remains the same until it is explicitly replaced or deleted.
expr is a string where the following characters have special interpretation:
':' is used to separate delimiters (it is the delimiter for delimiters).
'/' serves as an escape character.
| Note |
|---|---|
expr "ab:/:://:bc" is interpreted as four delimiters, which are "ab", ":", "/", and "bc". One socket can have 0-64 delimiters and each delimiter can contain 1-64 characters. |
Example:
open tcpdev:(connect=host_":"_portno_":TCP":delim=$c(13):attach="client"):timeout:"SOCKET"
This command specifies $CHAR(13) as the delimiter for the socket tcpdev.
EXCEPTION=expr Applies to: All devices
Defines an error handler for an I/O device. The expression must contain a fragment of GT.M code (for example, GOTO ERRFILE) that GT.M XECUTEs when GT.M detects an error, or an entryref to which GT.M transfers control, as appropriate for the current gtm_ztrap_form.
A device EXCEPTION gets control after a non-fatal device error and $ETRAP/$ZTRAP get control after other non-fatal errors.
For more information on error handling, refer to Chapter 13: “Error Processing”.
Example:
open file:(EXCEPTION="s err=""open"" do error")
This example sets the following code to XECUTE when there is an error while opening the file.
set err="open" do error
[NO]EMPT[ERM] Applies to: TRM
Allows an "Erase" character on an empty input line to terminate a READ or READ # command. The default is NOEMPTERM. The gtm_principal_editing environment variable specifies the initial setting of [NO]EMPTERM. The TERMINFO specified by the current value of the TERM environment variable defines capnames values "kbs" and/or "kdch1" with character sequences for "Erase." If "kbs" or "kdch1" are multi-character values, you must also specify the ESCAPE or EDIT deviceparameters for EMPTERM recognition.
The erase character as set and shown by stty also terminates a READ command with an empty input line. You can set this erase character to various values using the stty shell command. Typical values of an erase character are <CTRL-H> and <CTRL-?>. Characters set and shown with stty setting must match what the terminal emulator sends.
The environment variable TERM must specify a terminfo entry that matches both what the terminal (or terminal emulator) sends and expects.
FIFO Applies to: FIFO
Specifies that the device for the OPEN is a FIFO name. GT.M creates the FIFO if it does not already exist and if the process has adequate privileges. However, in the event that the process does not have adequate privileges, the process generates a run-time error. A process does not require any special privileges to OPEN an existing FIFO. The FIFO needs to be readable (or writeable) just like any other file.
Example:
open file:(fifo:read:recordsize=1048576):100
[NO]FIXED Applies to: SD FIFO PIPE
Selects a fixed-length record format for sequential disk files. FIXED does not specify the actual length of a record. Use RECORDSIZE to specify the record length.
NOFIXED specifies a variable-length record format for sequential disk files. NOFIXED is a synonym for VARIABLE. FIXED is incompatible with STREAM and VARIABLE. By default, records have VARIABLE length record format.
| Note |
|---|---|
FIXED length records do not implicitly use embedded record terminators such as line feeds. |
In UTF-8 mode, GT.M I/O enforces a more record-oriented view of the file, treating each record as RECORDSIZE bytes long. Note that a Unicode code-point never splits across records. If a multi-byte character (when CHSET is UTF-8) or a surrogate pair (when CHSET is UTF-16) does not fit into the record (either logical as given by WIDTH or physical as given by RECORDSIZE), the WRITE command uses the byte values as specified by the PAD deviceparameter to fill the physical record. A combining character may end up in the subsequent record if it does not fit in the current record.
| Note |
|---|---|
PAD is effective only for devices opened with a Unicode CHSET. In M mode PAD is always <SP> |
Example:
GTM>do ^fixedex
fixedex;
zprint ^fixedex
set file="fix.txt"
open file:(newversion:fixed:recordsize=4)
use file
write "Hello, World",!
close file
set file="fixnowrap.txt"
open file:(newversion:fixed:recordsize=4:nowrap)
use file
write "Hel",!
write "lo, World",! ; This writes only 'lo, '
close file
zsystem ("more fix*.txt")
zsystem ("od -cb fix.txt")
zsystem ("od -cb fixnowrap.txt")
quit
::::::::::::::
fix.txt
::::::::::::::
Hello, World
::::::::::::::
fixnowrap.txt
::::::::::::::
Hel lo,
0000000 H e l l o , W o r l d
110 145 154 154 157 054 040 127 157 162 154 144
0000014
0000000 H e l l o ,
110 145 154 040 154 157 054 040
0000010Example:
GTM>zprint ^gtmcp gtmcp ; Copy a binary file using GT.M new dest,line,max,src if 2>$length($zcmdline," ") write "$gtm_dist/mumps -r source target",! set dest=$piece($zcmdline," ",2) set src=$piece($zcmdline," ",1) set max=1024*1024 ; the maximum GT.M string size open src:(readonly:FIXED:WRAP:CHSET="M") ; open dest:(newversion:FIXED:WRAP:CHSET="M") ; use FIXED format because it does not insert carriage control characters after $X reaches its maximum value. for use src read line#max quit:$zeof use dest write line close src use dest set $x=0 close dest quit
This example copies a binary file using GT.M.
[NO]FOLLOW Applies to: SD
Configures READ to return only when it has a complete record or reaches any specified timeout; it waits for more input rather than terminating on an EOF (end-of-file) condition.
The USE command can switch a device from NOFOLLOW to FOLLOW or from FOLLOW to NOFOLLOW. This provides a READ mode of operation similar to a tail -f in UNIX.
GROUP=expr Applies to: SOC(LOCAL) SD FIFO
Specifies access permission on a UNIX file for other users in the file owner's group. The expression is a character string evaluating to null or to any combination of the letters RWX, indicating respectively Read, Write, and eXecute access. When permission controlling deviceparameters (OWNER,GROUP,WORLD) appears on an OPEN of a new file, any user category (OWNER, SYSTEM, WORLD), that is not explicitly specified is given the default access permissions. When any one of these deviceparameters appears on an OPEN of an existing device, any user category that is not explicitly specified remains unchanged.
In order to modify file security, the user who issues the OPEN must have ownership.
If none of GROUP, SYSTEM, OWNER, or WORLD are specified on OPEN, GT.M does not modify the permissions on an existing file and new files are created using the standard UNIX rules.
Example:
open "test52.txt":(append:group="rw")
This examples open file test52.txt in append mode with Read Write group access. Note that the user who opens file text52.txt must have ownership permissions for it.
ICHSET=expr Applies to: All devices
Establishes the character encoding of the input device being OPENed in the UTF-8 mode. The value of the expression can be M, UTF-8, UTF-16, UTF-16LE, or UTF-16BE. In M mode, ICHSET has no effect.
If ICHSET is not specified, GT.M assumes UTF-8 as the default character set for input from the device.
If expr is set to a value other than M, UTF-8, UTF-16, UTF-16LE or UTF-16BE, GT.M produces a run-time error. UTF-16, UTF-LE, and UTF-16BE are not supported for $Principal and Terminal devices.
| Note |
|---|---|
ICHSET is a deviceparameter of the OPEN command and not the USE command. Since GT.M implicitly OPENs $PRINCIPAL before any application code is executed, ICHSET does not apply to $Principal. |
INDEPENDENT Applies to: PIPE
The INDEPENDENT deviceparameter specifies that the newly created process will not be terminated by the CLOSE of the device. The input and output of INDEPENDENT processes should be handled in such a way that it runs independently even after the CLOSE of the device. By default, CLOSE terminates the process associated with the PIPE device.
IOERROR=expr Applies to: SOC
Enables exception handling in socket devices. expr specifies the I/O error trapping mode. A value equal to "TRAP" specifies that I/O errors on a device raise error conditions. A value equal to "NOTRAP", or when IOERROR is not specified, indicates that I/O error on a device does not raise error conditions.
| Note |
|---|---|
The IOERROR setting is associated with sockets while EXCEPTION is associated with the SOCKET device. In other words, IOERROR can be turned on or off for each of the sockets associated with a SOCKET device but there is only one EXCEPTION value which is used for all the sockets. |
Example:
open sock:(connect=host_":"_port_":TCP":delim=$char(13,10):ioerror="TRAP")::"SOCKET"
This example opens a socket connection and specifies that I/O errors on the device raises error conditions.
LISTEN=expr Applies to: SOC
A new socket is allocated to listen for a connection. It is made the current socket for the device, if the operation is successful. Upon successful completion, $KEY is set to the format of "LISTENING|<socket_handle>|{<portnumber>|</path/to/LOCAL_socket>}" otherwise, $KEY is assigned the empty string.
expr specifies the protocol and protocol specific information. Currently, GT.M supports TCP/IP and LOCAL (also known as UNIX domain) socket protocols. For TCP/IP sockets, specify expr in the form of "<port>:TCP".
If <port>=0 is specified, the system chooses the port for the TCP/IP socket.
For LOCAL sockets:
Specify expr in the form of "<pathname>:LOCAL", where <pathname> is the name of the file to be used for communication. <pathname> may contain a dollar sign ($) followed by the name of an environment variable which GT.M expands in the same way as the device name for a sequential file. The maximum allowed length of the expanded path name depends on the OS.
LISTEN creates the file if it doesn't exist. If the OPEN command specifies the NEWVERSION deviceparameter, the file specified by the pathname exists, and is a socket file, that file is deleted and GT.M creates a new file.
LISTEN with an OPEN processes the GROUP, OWNER, SYSTEM, WORLD, UIC, and NEWVERSION deviceparameters the same as OPEN for sequential files.
MOREREADTIME=intexpr Applies to: SOC
MOREREADTIME specifies the polling interval (in milliseconds) that a SOCKET device uses to check for arriving packets.
With no MOREREADTIME specified, SOCKET READ implements a dynamic approach of using a longer first interval of 200 ms when it finds no data, then shortening the interval to 10 ms when data starts to arrive.
If an interval is specified, the SOCKET device always uses the specified interval and doesn't adjust dynamically. This applies to any SOCKET READ. For more information on implementing SOCKET READ, refer to “Socket Read Operation”.
If a SOCKET READ is not subject to any of the defined terminating conditions, it terminates either after it has at least one character followed by an interval with no new packets, or reading 1,048,576 bytes.
If you use the MOREREADTIME behavior, bear in mind that:
Usually, it is more efficient and responsive for an application to wait and process input in larger chunks. Therefore, a larger value for MOREREADTIME can bring larger chunks of input to the application. However, large values may make for sluggish response.
A short value for MOREREADTIME may consume considerable CPU cycles, especially on a lightly loaded system.
The maximum value of MORETREADTIME is 999 (basically 1 second). Never set MOREREADTIME to 0 as it causes excessive CPU "spinning".
Example:
Use tcpdev:morereadtime=200
This example specifies that all READs for socket device tcpdev must wait for 200 milliseconds for input.
NEWVERSION Applies to: SD FIFO SOC(LOCAL)
The NEWVERSION deviceparameter assures that when an existing file is used, it is empty upon the OPEN.
By default, if any version of the file exists, OPEN accesses the current version. If no version of the file exists, OPEN without READONLY creates a new file.
Example:
GTM>file1="foo.txt" GTM>open file1:newversion:recordsize=5000 GTM>
This example creates a new version of sequential file foo.txtwith RECORDSIZE of 5000 bytes.
Example:
GTM>set delim=$c(13) GTM>set tcpdev="server$"_$j,timeout=30 GTM>open tcpdev:(LISTEN="local.socket"_":LOCAL":delim=$c(13):attach="server":newversion):timeout:"SOCKET"
This example deletes the old local.socket file (if it exists) and creates a new LISTENING local.socket file.
OCHSET=expr Applies to: All devices
Establishes the character encoding of the output device being OPENed in the UTF-8 mode. The value of the expression can be M, UTF-8, UTF-16, UTF-16LE, or UTF-16BE. In M mode, OCHSET has no effect.
If *CHSET is not specified, GT.M assumes UTF-8 as the default character set for all the input / output devices.
If expr is set to a value other than M, UTF-8, UTF-16, UTF-16LE or UTF-16BE, GT.M produces a run-time error. UTF-16, UTF-LE, and UTF-16BE are not supported for $Principal and Terminal devices.
| Note |
|---|---|
OCHSET is a deviceparameter of the OPEN command not the USE command. Since GT.M implicitly OPENs $PRINCIPAL before any application code is executed, OCHSET does not apply to $Principal. |
Example:
GTM>SET file1="mydata.out"
GTM>SET expr="UTF-16LE"
GTM>OPEN file1:(ochset=expr)
GTM>SET DS=$CHAR($$FUNC^%HD("0905"))_$CHAR($$FUNC^%HD("091A"))
GTM>SET DS=DS_$CHAR($$FUNC^%HD("094D"))_$CHAR($$FUNC^%HD("091B"))_$CHAR($$FUNC^%HD("0940"))
GTM>USE file1 WRITE DS,!
GTM>CLOSE file1 This example opens a new file called mydata.out and writes Devanagari characters in the UTF-16LE encoding.
OWNER=expr Applies to: SOC(LOCAL) SD FIFO
Specifies access permission on a UNIX file for the owner of the file. The expression is a character string evaluating to null or to any combination of the letters RWX, indicating Read, Write, and eXecute access. When any one of these deviceparameters appears on an OPEN of a new file, any user category that is not explicitly specified is given the default mask. When any one of these deviceparameters (OWNER, GROUP, , WORLD) appears on an OPEN of an existing file, any user category that is not explicitly specified remains unchanged.
To modify file security, the user who issues the OPEN must have ownership.
If none of GROUP, SYSTEM, OWNER, or WORLD are specified on OPEN, GT.M does not modify the permissions on an existing file and new files are created using the standard UNIX rules.
Example:
open "test49.txt":(newversion:owner="rw":group="rw":world="rw")
This example opens a new version of test49.txt with Read Write acess for the owner.
PAD=expr Applies to: SD FIFO PIPE
For FIXED format sequential files when the character set is not M, if a multi-byte character (when CHSET is UTF-8) or a surrogate pair (when CHSET is UTF-16) does not fit into the record (either logical as given by WIDTH or physical as given by RECORDSIZE) the WRITE command uses bytes with the value specified by the PAD deviceparameter to fill out the physical record. READ ignores the pad bytes when found at the end of the record. The value for PAD is given as an integer in the range 0-127 (the ASCII characters). PAD is always a byte value and the default is $ZCHAR(32) or [SPACE].
In UTF-8 mode, there are three cases that cause GT.M to insert PAD characters when WRITEing. When READing GT.M attempts to strip any PAD characters. This stripping only works properly if the RECORDSIZE and PAD are the same for the READ as when the WRITEs occurred. WRITE inserts PAD characters when:
The file is closed and the last record is less than the RECORDSIZE. Records are padded (for FIXED) by WRITE ! as well as when the file is closed.
$X exceeds WIDTH before the RECORDSIZE is full.
The next character won't fit in the remaining RECORDSIZE.
| Note |
|---|---|
In all UTF-16 character sets, RECORDSIZE must be even and PAD bytes occupy two bytes with the high order byte zero. |
Example:
GTM>do ^padexample
padexample
zprint ^padexample
set a="主要雨在西班牙停留在平原"
set encoding="UTF-8"
set filename="bom"_encoding_".txt"
open filename:(newversion:fixed:record=8:pad=66:chset=encoding)
use filename
write a
close filename
halt
$ cat bomUTF-8.txt
主要BB雨在BB西班BB牙停BB留在BB平原
$ od -tcd1 bomUTF-8.txt
0000000 344 270 273 350 246 201 B B 351 233 250 345 234 250 B B
-28 -72 -69 -24 -90 -127 66 66 -23 -101 -88 -27 -100 -88 66 66
0000020 350 245 277 347 217 255 B B 347 211 231 345 201 234 B B
-24 -91 -65 -25 -113 -83 66 66 -25 -119 -103 -27 -127 -100 66 66
0000040 347 225 231 345 234 250 B B 345 271 263 345 216 237
-25 -107 -103 -27 -100 -88 66 66 -27 -71 -77 -27 -114 -97 32 32
0000060In this example, the local variable a is set to a string of three-byte characters. PAD=66 sets padding byte value to $CHAR(66)
PARSE Applies to: PIPE
The PARSE deviceparameter invokes preliminary validation of the COMMAND value. When debugging, PARSE provides more accessible diagnosis for COMMAND values. By default, OPEN does not validate command values before passing them to the newly created process. PARSE has certain limitations, which may, or may not map to, those of the shell.
PARSE searches for the command in the environment variables PATH and gtm_dist and produces an error if it is not found.
PARSE does not resolve aliases, so they produce an error.
PARSE does not resolve environment variables, except $gtm_dist (as mentioned above), so they trigger an error.
PARSE does not recognize built-in commands other than nohup and cd unless $PATH or $gtm_dist contain a version with the same name (as the built-in). In the case of nohup, PARSE looks for the next token in $PATH and $gtm_dist. "When PARSE encounters cd it ignores what follows until the next "|" token (if one appears later in the COMMAND value).
PARSE rejects parentheses around commands.
The following example fails:
OPEN p:(COMM="(cd; pwd)":WRITEONLY)::"PIPE"which could be specified without a PARSE error as:
OPEN p:(COMM="cd; pwd":WRITEONLY)::"pipe"This restriction does not include parentheses embedded in character strings as in:
OPEN p:(COMM="echo ""(test)""":WRITEONLY)::"pipe"or parameters to a command as in:
OPEN p:(COMM="tr -d '()'":WRITEONLY)::"PIPE"The following are examples of valid OPEN commands using PARSE:
OPEN a:(COMM="tr e j | echoback":STDERR=e:exception="g BADOPEN":PARSE)::"PIPE" OPEN a:(SHELL="/usr/local/bin/tcsh":COMM="/bin/cat |& nl":PARSE)::"PIPE" OPEN a:(COMM="mupip integ -file mumps.dat":PARSE)::"PIPE" OPEN a:(COMM="$gtm_dist/mupip integ -file mumps.dat":PARSE)::"PIPE" OPEN a:(COMM="nohup cat":PARSE)::"PIPE"
[NO]READONLY Applies to: SD FIFO PIPE
OPENs a device for reading only (READONLY) or reading and writing (NOREADONLY).
To open a sequential file using the READONLY parameter, the file must exist on the disk. If it does not, GT.M issues a run-time error.
When GT.M encounters a WRITE directed to a file, OPENed READONLY, GT.M issues a run-time error.
By default, OPEN accesses the device or file NOREADONLY (read-write).
Example:
GTM>set filename="foo.txt" GTM>open filename:(readonly:recordsize=1048576) GTM>
This example open the file foo.txt with read permission
RECORDSIZE=intexpr Applies to: SD FIFO PIPE
Overrides the default record size for a disk.
If the character set is M, RECORDSIZE specifies the initial WIDTH.
The RECORDSIZE of a fixed length record for a GT.M sequential disk device is always specified in bytes, rather than characters.
For all UTF-16 CHSET values, RECORDSIZE must be even and PAD characters each occupy two bytes in the record.
The maximum size of intexpr is 1,048,576 bytes. GT.M produces an error if you specify a value greater than 1,048,576.
When a Unicode CHSET is in use, GT.M treats RECORDSIZE as a byte limit at which to wrap or truncate output depending on [Z][NO]WRAP. For any Unicode character set, GT.M ignores RECORDSIZE for a device which is already open if any I/O has been done.
If the character set is not UTF-16, UTF-16LE, UTF-16BE, the default RECORDSIZE is 32K-1bytes.
If the character set is UTF-16, UTF-16LE or UTF16-BE, the RECORDSIZE must always be in multiples of 2. For these character sets, the default RECORDIZE is 32K-4 bytes.
For all UTF-16 CHSET values, RECORDSIZE must be even and PAD characters each occupy two bytes in the record.
REWIND Applies to: SD
REWIND positions the file pointer of a sequential disk.
By default, OPEN does not REWIND.
Example:
OPEN "test40.txt":(REWIND:RECORDSIZE=70:NOWRAP)
This example opens file test40.txt and places the file pointer at the beginning of the file.
SHELL Applies to: PIPE
The SHELL deviceparameter specifies the shell for the new process. By default the newly created process uses the shell specified by the $SHELL environment variable, otherwise, if the environment variable SHELL is undefined the process uses /bin/sh.
STDERR Applies to: PIPE
The STDERR deviceparameter specifies that the stderr output from the created process goes to a PIPE device with the name of the STDERR value. This PIPE device acts as a restricted device that can appear only as the argument to USE, READ and CLOSE commands. It is implicitly READONLY and an attempt to WRITE to it triggers an error. If it has not previously acted as the argument to an explicit CLOSE command, the CLOSE of the PIPE device implicitly closes the the STDERR device.
[NO]STREAM Applies to: SD FIFO PIPE
STREAM and VARIABLE are semantically equivalent unless WRAP is disabled. As long as records do not exceed the WIDTH, they are also equivalent.
When WRAP is disabled and a WRITE exceeds the WIDTH, both truncate the line at the WIDTH, however in STREAM format, each WRITE argument truncates after WIDTH characters regardless of whether the cursor exceeds the WIDTH, while in VARIABLE format, no output ever exceeds the WIDTH.
While each WRITE argument is truncated if it exceeds the WIDTH, the total record can be of arbitrary length. Note that, for efficiency, the compiler combines sequential literal arguments of a single WRITE into a single string so that the run-time system considers the combined length of the sequence.
For STREAM or VARIABLE record format files, a READ returns when it encounters an EOL, or has read #length characters for a READ #(fixed length READ), or WIDTH characters if #length is not specified, whichever occurs first.
By default, records are VARIABLE, NOSTREAM.
Example:
set sd="foo.txt" open sd:(newversion:stream) use sd:(width=20:nowrap) for i=1:1:10 write " the quick brown fox jumped over the lazy dog ",$x,! use sd:(rewind:width=100) for i=1:1 use sd read x quit:$zeof use $principal write !,i,?5,x close sd quit
The output of this example is as follows:
1 the quick brown fox20 2 the quick brown fox20 3 the quick brown fox20 4 the quick brown fox20 5 the quick brown fox20 6 the quick brown fox20 7 the quick brown fox20 8 the quick brown fox20 9 the quick brown fox20 10 the quick brown fox20
If you change the FORMAT to VARIABLE, the same example produces the following output.
1 the quick brown fox 2 the quick brown fox 3 the quick brown fox 4 the quick brown fox 5 the quick brown fox 6 the quick brown fox 7 the quick brown fox 8 the quick brown fox 9 the quick brown fox 10 the quick brown fox
If you remove the "!" format from the WRITE sequence for VARIABLE, the same example produces the following output:
1 the quick brown fox
With STREAM, the same example produces the following output:
1 the quick brown fox20 the quick brown fox42 the quick brown fox64 the quick brown fox86 the quick b 2 rown fox108 the quick brown fox131 the quick brown fox154 the quick brown fox177 the quick brown fox 3 200 the quick brown fox223
With STREAM, changing the $X to "abc", the same example produces the following output:
1 the quick brown fox the quick brown fox the quick brown fox the quick brown fox the quick brown fox 2 the quick brown fox the quick brown fox the quick brown fox the quick brown fox the quick brown fox 3
With STREAM, turning the comma between ".. lazy dog" and "abc" into a separate WRITE statement produces:
1 the quick brown foxabc the quick brown foxabc the quick brown foxabc the quick brown foxabc the qui 2 ck brown foxabc the quick brown foxabc the quick brown foxabc the quick brown foxabc the quick brown 3 foxabc the quick brown foxabc
SYSTEM=expr Applies to: SOC(LOCAL) SD FIFO
This deviceparameter is a synonym for OWNER that is provided in the UNIX version of GT.M for compatibility with OpenVMS applications.
Example:
GTM> set perm="rwx" GTM>OPEN "test52.txt":(NEWVERSION:SYSTEM="r":GROUP=perm:WORLD=perm) GTM>ZSYSTEM "ls -la test52.txt"
-r--rwxrwx 1 user group 0 Aug 20 18:36 test52.txt GTM>
This example opens file test52.txt and sets read access for the owner, while others have complete access.
[NO]TRUNCATE Applies to: SD
Truncates the file destroying all data beyond the current file pointer. If APPEND is also specified, the file pointer will be positioned at the end of the file even if TRUNCATE is before APPEND in the list of device parameters.
UIC=expr Applies to: SOC(LOCAL) SD FIFO
Specifies the owner and group for the file.
Specifies the group that has access to the file. The format of the string is "o,g" where g is a decimal number representing the group portion of the UIC and o is a decimal number representing the owner portion. The super-user can set the file UIC to any value. See the man page for the chown() system call for the rules for regular users since they vary by platform and system configuration.
VARIABLE Applies to: SD FIFO PIPE
Specifies the VARIABLE record length format for sequential disk files.
By default, records have variable length format.
For more information, refer to “STREAM”.
WORLD=expr Applies to: SOC(LOCAL) SD FIFO
Specifies access permissions for users other than the owner who are not in the group specified for a file. This category of users is usually referred to as other in UNIX. The expression is a character string evaluating to null or to any combination of the letters RWX, indicating respectively Read, Write, and eXecute access. When any one of these deviceparameters appear on an OPEN of an existing file, any user category that is not explicitly specified remains unchanged.
To modify file security, the user who issues the OPEN must have ownership.
By default, OPEN and CLOSE do not modify the permissions on an existing file. Unless otherwise specified, when OPEN creates a new file, it establishes security using standard defaulting rules.
Example:
OPEN "test51.txt":(NEWVERSION:WORLD="rw")
This example opens file test51.txt and specifies Read Write permission for users not in owner's group.
[Z][NO]WRAP Applies to: TRM SD FIFO PIPE SOC
Enables or disables automatic record termination. When the current record size ($X) reaches the maximum WIDTH and the device has WRAP enabled, GT.M starts a new record, as if the routine had issued a WRITE ! Command. When reading, WRAP only determines whether $X remains within the range of zero to WIDTH.
Note that WRAP is enabled by default for SD, FIFO, and SOCKET. For TRM, WRAP is enabled by default if the terminfo variable auto_right_margin (capname "am") is set.
NOWRAP causes GT.M to require a WRITE ! to terminate the record. NOWRAP allows $X to become greater than the device WIDTH for terminals and null devices.
The combination of STREAM, NOWRAP and WIDTH=65535 options on disk files allows you to write data of arbitrary length. With other WIDTHs, STREAM and NOWRAP truncate single arguments to WIDTH, but ignore $X. Without the STREAM option, the WRAP option determines the action taken when the record length exceeds the device WIDTH. NOWRAP causes GT.M to truncate the record, while WRAP causes GT.M to insert a format control character except for FIXED format.
When reading, WRAP only determines whether $X remains within the range of zero to WIDTH.
[NO]WRITEONLY Applies to: PIPE
The WRITEONLY deviceparameter specifies that the PIPE acts only to send its output to the created process. Any attempt to READ from such a PIPE triggers an error. Note that when you open a PIPE with both STDERR and WRITEONLY you can still READ from the STDERR device.
ZBFSIZE Applies to: SOC
Allocates a buffer used by GT.M when reading from a socket. The ZBFSIZE deviceparameter should be at least as big as the largest message expected.
By default, the size of ZBFSIZE is 1024 and the maximum it can be is 1048576.
Z[NO]DELAY Applies to: SOC(TCP)
Controls buffering of data packets by the system TCP stack using the TCP_NODELAY option to the setsockopt system call. This behavior is sometimes known as the Nagle algorithm. The default is ZDELAY. This delays sending additional packets until either an acknowledgment of previous packets is received or an interval passes. If several packets are sent from one end of a connection before the other end responds, setting ZNODELAY may be desirable though at the cost of additional packets being transmitted over the network. ZNODELAY must be fully spelled out.
LOCAL sockets ignore the ZDELAY deviceparameter.
Example:
open tcpdev:(LISTEN=portno_":TCP":attach="server":zbfsize=2048:zibfsize=1024):timeout:"SOCKET"
This example opens the socket device tcpdev and allocates a buffer size of 2048 bytes.
Z[NO]FF=expr Applied to: SOC
expr specifies a string of characters, typically in $CHAR() format to send to socket device, whenever a routine issues a WRITE #. When no string is specified or when ZFF="", then no characters are sent. The default in GT.M is ZNOFF.
ZIBFSIZE Applies to: SOC(TCP)
Allocates a buffer used by GT.M when reading from a socket. The ZBFSIZE deviceparameter should be at least as big as the largest message expected.
By default, the size of ZBFSIZE is 1024 and the maximum it can be is 1048576.
Note that LOCAL sockets ignore the ZIBFSIZE deviceparameter.
|
OPEN Deviceparameters | ||||||
|---|---|---|---|---|---|---|
|
OPEN DEVICEPARAMETER |
TRM |
SD |
FIFO | PIPE |
NULL |
SOC |
|
TRM: Valid for terminals and printers SD: Valid for sequential disk files FIFO: Valid for FIFOs NULL: Valid for null devices PIPE: Valid for PIPEs SOC: Valid for Socket devices | ||||||
|
APPEND |
X | |||||
|
ATTACH=expr |
X | |||||
CHSET=encoding | X | X | X | X | X | X |
COMMAND=expr | X | |||||
|
CONNECT=expr |
X | |||||
|
[NO]DELIMITER |
X | |||||
|
[NO]EMPT[ERM] |
X | |||||
|
EXCEPTION=expr |
X |
X |
X |
X |
X | |
|
FIFO |
X | |||||
|
[NO]FIXED |
X |
X | X | |||
|
[NO]FOLLOW |
X | |||||
|
GROUP=expr |
X |
X | ||||
ICHSET=encoding | X | X | X | X | X | X |
INDEPENDENT | X | |||||
|
IOERROR=expr |
X | |||||
|
[NO]NEWVERSION |
X |
X | ||||
OCHSET=encoding | X | X | X | X | X | X |
|
OWNER=expr |
X |
X | ||||
PARSE | X | |||||
|
[NO]READONLY |
X |
X | X | |||
|
RECORDSIZE=intexpr |
X |
X | X | |||
|
REWIND |
X | |||||
SHELL=expr | X | |||||
STDERR=expr | X | |||||
|
[NO]STREAM |
X | |||||
|
SYSTEM=expr |
X |
X | ||||
|
[NO]TRUNCATE |
X |
X | ||||
|
UIC=expr |
X |
X | ||||
|
VARIABLE |
X | X | X | |||
|
WORLD=expr |
X |
X | ||||
|
[NO]WRITEONLY | X | |||||
|
[Z][NO]WRAP |
X |
X |
X | X |
X |
X |
|
ZBFSIZE |
X | |||||
|
Z[NO]DELAY |
X | |||||
|
Z[NO]FF |
X | |||||
|
ZIBFSIZE |
X | |||||
|
LISTEN=expr |
X | |||||
The USE command selects the current device for READs (input) and WRITEs (output).
The format of the USE command is:
U[SE][:tvexpr] expr[:(keyword[=expr][:...])][,...]
The optional truth-valued expression immediately following the command is a command postconditional that controls whether or not GT.M executes the command.
The required expression specifies the device to make the current device.
A USE that selects a device not currently OPENed by the process causes a run-time error.
The optional keywords specify deviceparameters that control device behavior; some deviceparameters take arguments delimited by an equal sign (=). If there is only one deviceparameter, the surrounding parentheses are optional.
An indirection operator and an expression atom evaluating to a list of one or more USE arguments form a legal argument for a USE.
The intrinsic special variable $IO identifies the current device, so GT.M directs all READs and WRITEs to $IO. When a GT.M image starts, $PRINCIPAL is implicitly OPENed and USEd. Once the GT.M image USEs a device, $IO holds the name of that device until the next USE command.
A USE command modifies the device in accordance with the deviceparameters that apply to the device type and ignores those that do not apply. Characteristics set with USE deviceparameters persist until another USE for the same device with the corresponding deviceparameter. Characteristics persist through USEs of other devices and, except for SD, FIFO, and PIPE, through a subsequent CLOSE and re-OPEN.
Example:
USE $P:(X=0:Y=$Y-1:NOECHO)
This example USEs the principal device. If that device is a terminal, the deviceparameters turn off echo and position the cursor to the beginning of the previous line.
ATTACH=expr Applies to: SOC
expr specifies the handle for a socket in the socketpool. ATTACH looks up expr in the socketpool's collection of sockets and brings the one found to the current SOCKET device. If an ATTACH operation is successful, the attached socket becomes the current socket for the device.
ATTACH is not compatible with any other device parameters in the USE command.A socket can move from one device to another using DETACH/ATTACH.
| Note |
|---|---|
A socket does not carry I[O]CHSET with it while being moved. Such a socket uses the I[O]CHSET of the device it is ATTACHed to. If there is input still buffered, this may cause unintentional consequences in the application if I[O]CHSET changes. GT.M does not detect (or report) a change in I[O]CHSET due to DETACH/ATTACH. |
For information on using the ATTACH with OPEN, refer to “ATTACH” in the OPEN Deviceparameters section.
[NO]CANONICAL Applies to: TRM
Enables or disables canonical input as controlled by the ICANON terminal attribute. See the documentation on your platform for details, but in general this would be erase and kill edit functions, and lines delimited by NL (usually <LF>), EOF (usually ^D), and EOL (usually not defined).
By default, canonical input is enabled (that is [NO]CANONICAL is the default).
[NO]CENABLE Applies to: TRM
Enables or disables the ability to force GT.M into Direct Mode by entering <CTRL-C> at $PRINCIPAL.
If CENABLE is set, <CTRL-C> interrupts process execution. For more information on interrupt handling, refer to “Interrupt Handling”.
By default, CENABLE is set. If CTRAP contains $C(3), CENABLE is disabled.
Example:
use $principal:(nocenable:ctrap="":exception="")
CLEARSCREEN Applies to: TRM
Clears the terminal screen from the present cursor position to the bottom of the screen. The CLEARSCREEN deviceparameter does not change the cursor position or the $X and $Y variables.
Example:
U $P:(X=0:Y=0:CLEAR)
This example positions the cursor to "home" in the upper left corner of a VDT and clears the entire current screen "page."
CONNECT=expr Applies to: SOC
Enables a client connection with a server, which is located by the information provided by expr. A new socket is allocated for the client connection and is made the current socket for the device, if the operation is successful.
expr specifies the protocol and the protocol-specific information. Currently, GT.M supports TCP/IP and LOCAL (also known as UNIX domain) socket protocols.
For more information, refer to “CONNECT”.
| Note |
|---|---|
CONNECT is not compatible with LISTEN. |
Although CONNECT can be used with USE command, FIS recommends not to use it that way, because unlike the OPEN command, there is no way to specify a timeout to the USE command. CONNECT in the USE command take a default timeout value of 0.
Example:
Refer to the "CONNECT" examples in “Examples of OPEN”.
[NO]CONVERT Applies to: TRM
Enables or disables GT.M from converting lowercase input to uppercase during READs.
By default, the terminal device driver operates NOCONVERT.
Example:
use $principal:(convert) READ X
This example converts all lowercase to uppercase during READ X.
CTRAP=expr Applies to: TRM
Establishes the <CTRL> characters in the expression as trap characters for the current device. When GT.M receives a trap character in the input from a device, GT.M issues a run-time exception. The device does not have to be the current device, that is $IO.
The <CTRL> characters are ASCII 0 though 31.
For example, the command U $P:CTRAP=$C(26,30,7,19) sets a trap for the ASCII characters <SUB>, <RS>, <BEL> and <DC3>.
Specifying CTRAP completely replaces the previous CTRAP list. Setting CTRAP to the null string ("") disables character trapping.
A trap character enabled by CTRAP produces one of the following actions:
If an EXCEPTION deviceparameter has been issued for the device, the process executes the EXCEPTION argument.
Otherwise, if $ETRAP is not the empty string, execute $ETRAP.
Otherwise, if $ZTRAP is not the empty string, the process executes $ZTRAP.
Otherwise, the GT.M image terminates.
For more information on error handling, refer to Chapter 13: “Error Processing”.
When CTRAP includes <CTRL-C>, [NO]CENABLE has no effect. CTRAPping <CTRL-C> also takes precedence over CENABLE.
[NO]DELIMITER Applies to: SOC
DELIMITER establishes or replaces the list of delimiters used by the current socket. The default is NODELIMITER.
expr must be a string of the following format:
':' is used to separate delimiters (it is the delimiter for delimiters).
'/' serves as an escape character.
| Note |
|---|---|
expr "ab:/:://:bc" is interpreted as four delimiters, which are "ab", ":", "/", and "bc". One socket can have 0-64 delimiters and each delimiter can contain 1-64 characters. |
Example:
See "Socket (server.m)" example.
DETACH=expr Applies to: SOC
Removes the socket identified by expr from the current socket device, without affecting any existing connection of that socket. The removed socket is placed in the socketpool and may be attached to another socket device. If the socket being removed is the current socket, then GT.M does the following:
The socket ATTACHed prior to the removed socket, is made current, if one such exists.
The socket ATTACHed after the removed socket, is made current, if the removed one was the first socket.
$PRINCIPAL is made the current device ($IO), if the removed socket was the only one in the current socket device.
| Note |
|---|---|
A socket can move from one device to another using DETACH/ATTACH. A socket does not carry I[O]CHSET with it while being moved. Such a socket uses the I[O]CHSET of the device it is ATTACHed to. If there is input still buffered, this may cause unintentional consequences in the application if I[O]CHSET changes. GT.M does not detect (or report) a change in I[O]CHSET due to DETACH/ATTACH. |
Example:
GTM>set tcp="seerv" open tcp:(listen="6321:TCP":attach="serv")::"SOCKET"
GTM>zshow "D"
/dev/pts/9 OPEN TERMINAL NOPAST NOESCA NOREADS TYPE WIDTH=80 LENG=24
seerv OPEN SOCKET TOTAL=1 CURRENT=0
SOCKET[0]=serv DESC=3 BOUND PASSIVE NOTRAP PORT=6321
ZDELAY ZBFSIZE=1024 ZIBFSIZE=87380 NODELIMITER
GTM>set tcp="seerv" o tcp:(listen="6322:TCP":attach="serv2")::"SOCKET"
GTM>zshow "D"
/dev/pts/9 OPEN TERMINAL NOPAST NOESCA NOREADS TYPE WIDTH=80 LENG=24
seerv OPEN SOCKET TOTAL=2 CURRENT=1
SOCKET[0]=serv DESC=3 BOUND PASSIVE NOTRAP PORT=6321
ZDELAY ZBFSIZE=1024 ZIBFSIZE=87380 NODELIMITER
SOCKET[1]=serv2 DESC=4 BOUND PASSIVE NOTRAP PORT=6322
ZDELAY ZBFSIZE=1024 ZIBFSIZE=87380 NODELIMITERAt this point, the socket device "seerv" has two sockets associated with it.
The following command moves the "serv" socket to the "socketpool" device.
GTM>use tcp:detach="serv"
GTM>use 0 zshow "D"
/dev/pts/9 OPEN TERMINAL NOPAST NOESCA NOREADS TYPE WIDTH=80 LENG=24
seerv OPEN SOCKET TOTAL=1 CURRENT=0
SOCKET[0]=serv2 DESC=4 BOUND PASSIVE NOTRAP PORT=6322
ZDELAY ZBFSIZE=1024 ZIBFSIZE=87380 NODELIMITER
socketpool OPEN SOCKET TOTAL=1 CURRENT=0
SOCKET[0]=serv DESC=3 BOUND PASSIVE NOTRAP PORT=6321
ZDELAY ZBFSIZE=1024 ZIBFSIZE=87380 NODELIMITERNotice how socket "serv" is now associated with the pseudo socket device "socketpool". Its only purpose is to hold detached sockets.
GTM>set tcp2="s2" o tcp2:::"SOCKET"
This creates a new socket device.
GTM>zshow "D"
/dev/pts/9 OPEN TERMINAL NOPAST NOESCA NOREADS TYPE WIDTH=80 LENG=24
s2 OPEN SOCKET TOTAL=0 CURRENT=0
seerv OPEN SOCKET TOTAL=1 CURRENT=0
SOCKET[0]=serv2 DESC=4 BOUND PASSIVE NOTRAP PORT=6322
ZDELAY ZBFSIZE=1024 ZIBFSIZE=87380 NODELIMITER
socketpool OPEN SOCKET TOTAL=1 CURRENT=0
SOCKET[0]=serv DESC=3 BOUND PASSIVE NOTRAP PORT=6321
ZDELAY ZBFSIZE=1024 ZIBFSIZE=87380 NODELIMITERThe following command moves the serv socket from the socketpool to the tcp2 device.
GTM>use tcp2:attach="serv"
GTM>use 0 zshow "D"
/dev/pts/9 OPEN TERMINAL NOPAST NOESCA NOREADS TYPE WIDTH=80 LENG=24
s2 OPEN SOCKET TOTAL=1 CURRENT=0
SOCKET[0]=serv DESC=3 BOUND PASSIVE NOTRAP PORT=6321
ZDELAY ZBFSIZE=1024 ZIBFSIZE=87380 NODELIMITER
seerv OPEN SOCKET TOTAL=1 CURRENT=0
SOCKET[0]=serv2 DESC=4 BOUND PASSIVE NOTRAP PORT=6322
ZDELAY ZBFSIZE=1024 ZIBFSIZE=87380 NODELIMITER
socketpool OPEN SOCKET TOTAL=0 CURRENT=-1DOWNSCROLL Applies to: TRM
If $Y=0, DOWNSCROLL does nothing. Otherwise, DOWNSCROLL moves the cursor up one line on the terminal screen and decrements $Y by one. DOWNSCROLL does not change the column position or $X. Some terminal hardware may not support DOWNSCROLL.
[NO]ECHO Applies to: TRM
Enables or disables the echo of terminal input. If you disable ECHO, the EDITING functions will be disabled and any input is not available for later recall.
By default, terminal input ECHOes.
Example:
use $principal:noecho
This example disables the echo of terminal input.
[NO]EDITING Applies to: TRM
Enables the EDITING mode for the $PRINCIPAL device. If you enable EDITING, GT.M allows the use of the left and right cursor movement keys and certain <CTRL> characters within the current input line. You can recall the last input line using the up or down arrow key. The editing functions are the same as during direct mode command input as described in the "Line Editing" section of the "Operating & Debugging in Direct Mode" chapter except that backspace is not treated the same as the erase character from terminfo which is usually delete (ASCII 127). NOECHO disables EDITING mode.
Set the environment variable gtm_principal_editing to specify the mode for EDITING. For example, gtm_principal_editing="EDITING" enables EDITING mode at GT.M startup. You can also specify the mode for INSERT. For example, gtm_principal_editing="NOINSERT:EDITING". If you specify both modes then separate them with a colon (":") and put them in any order.
By default, EDITING mode is disabled.
If you enable the EDITING mode, escape sequences do not terminate READs.
Enabling PASTHRU mode supersedes EDITING mode.
If any of the EDITING <CTRL> characters are in the CTRAP list, their editing functions are not available since CTRAP takes precedence. However the EDITING <CTRL> characters takes precedence over the TERMINATOR list.
| Note |
|---|---|
M READ EDITING depends on the values of $X and $Y being correct. If the application sends its own escape sequences or control characters, which change the cursor position, it must properly update $X and $Y before doing a M READ with EDITING enabled to ensure correct formatting during input. |
[NO]EMPT[ERM] Applies to: TRM
Allows an "Erase" character on an empty input line to terminate a READ or READ # command. The default is NOEMPTERM. The gtm_principal_editing environment variable specifies the initial setting of [NO]EMPTERM. The TERMINFO specified by the current value of the TERM environment variable defines capnames values "kbs" and/or "kdch1" with character sequences for "Erase." If "kbs" or "kdch1" are multi-character values, you must also specify the ESCAPE or EDIT deviceparameters for EMPTERM recognition.
The erase character as set and shown by stty also terminates a READ command with an empty input line. You can set this erase character to various values using the stty shell command. Typical values of an erase character are <CTRL-H> and <CTRL-?>. Characters set and shown with stty setting must match what the terminal emulator sends.
The environment variable TERM must specify a terminfo entry that matches both what the terminal (or terminal emulator) sends and expects.
ERASELINE Applies to: TRM
Clears the current line from the physical cursor position to the end of the line. ERASELINE does not affect the physical cursor position, or $X and $Y.
[NO]ESCAPE Applies to: TRM
Enables or disables GT.M processing of escape sequences.
The following events result when a terminal has ESCAPE sequence processing enabled. When an <ESC> or <CSI> arrives in the terminal input, the device driver verifies the sequence that follows as a valid ANSI escape sequence, terminates the READ, and sets $ZB to contain the entire escape sequence. In the case of a READ * when ESCAPE sequence processing is enabled and an escape introducer is read, the entire escape sequence is returned in $ZB and the ASCII representation of the first character is returned in the argument of the READ *.
When escape processing is disabled, READ *x returns 27 in x for an <ESC>. If the escape introducer is also a TERMINATOR, $ZB has a string of length one (1), and a value of the $ASCII() representation of the escape introducer; otherwise, $ZB holds the empty string. For single character and short fixed reads with NOESCAPE, the remaining characters in the escape sequence will be in the input stream for subsequent READS regardless of [NO]TYPEAHEAD.
An application that operates with (NOESCAPE:TERM=$C(13)) must provide successive READ * commands to remove the remaining characters in the escape sequence from the input stream.
By default, ESCAPE processing is disabled.
Example:
use $principal:(noescape:term=$c(13))
This example disables the escape sequence processing and set $c(13) as the line terminator.
EXCEPTION=expr Applies to: All devices
Defines an error handler for an I/O device. The expression must contain a fragment of GT.M code (for example, GOTO ERRFILE) that GT.M XECUTEs when the driver for the device detects an error, or an entryref to which GT.M transfers control, as appropriate for the current gtm_ztrap_form.
For more information on error handling, refer to Chapter 13: “Error Processing”.
[NO]FILTER[=expr] Applies to: TRM SOC NULL
Specifies character filtering for specified cursor movement sequences. Filtering requires character by character examination of all output and reduces I/O performance.
Each FILTER deviceparameter can have only one argument. However, multiple FILTER deviceparameters can appear in a single USE command, each with different arguments.
The valid values for expr:
[NO]CHARACTERS enables or disables maintenance of $X and $Y according to the M ANSI standard for the characters <BS>, <LF>, <CR> and <FF>. CHARACTERS causes the device driver to examine all output for the above characters, and to adjust $X and $Y accordingly. By default, GT.M performs special maintenance on $X and $Y only for M format control characters, WRAPped records, and certain action deviceparameters.
In UTF-8 mode, the usual Unicode line terminators are recognized.
[NO]ESCAPE alters the effect of ANSI escape sequences on $X and $Y. ESCAPE causes GT.M to filter the output, searching for ANSI escape sequences and preventing them from updating $X and $Y. By default, GT.M does not screen output for escape sequences.
By default, GT.M does not perform output filtering. For GT.M to maintain $X for non-graphic characters as described by the standard, FILTER="CHARACTERS" must be enabled. Output filtering adds additional overhead to I/O processing.
Example:
use tcpdev:filter="NOESCAPE"
This example removes the effect of escape sequences on the maintenance $X and $Y.
[NO]FOLLOW Applies to: SD
Configures READ to return only when it has a complete record or reaches any specified timeout; it waits for more input rather than terminating on an EOF (end-of-file) condition.
The USE command can switch a device from NOFOLLOW to FOLLOW or from FOLLOW to NOFOLLOW. This provides a READ mode of operation similar to a tail -f in UNIX.
[NO]HOSTSYNC Applies to: TRM
Enables or disables the use of XON/XOFF by the host to throttle input and prevent impending buffer overruns for a terminal. This deviceparameter provides a control mechanism for the host over asynchronous communication lines to help prevent data loss when hardware is slow and/or processing load is high.
By default, HOSTSYNC is disabled.
IOERROR=expr Applies to: SOC
Enables exception handling in socket devices. expr specifies the I/O error trapping mode. A value equal to "TRAP" specifies that I/O errors on a device raise error conditions. A value equal to "NOTRAP", or when IOERROR is not specified, indicates that an I/O error on a device does not raise error conditions.
| Note |
|---|---|
GT.M currently handles exception handling at device level instead of socket level. |
Example:
use sock:(ioerror="TRAP":exception="zgoto "_$zlevel_":error")
This example enables exception handling in socket device sock and specifies that all I/O errors on sock raise the error condition.
[Z]LENGTH=intexpr Applies to: TRM SOC SD FIFO PIPE NULL
Sets the virtual page length for an I/O device to the integer expression. You can specify the virtual page length up to 1,048,576. The page length controls the point at which the device driver automatically resets $Y to 0.
By default, for terminals, GT.M uses the terminfo variable lines (which may be from the terminal definition or from a stty command) as the initial value for LENGTH. The default length for null device and socket device is 66.
Setting LENGTH to zero prevents resetting $Y to zero.
Example:
use sock:(zwidth=80:znoff:zlength=24)
This example sets the virtual page length to 24 for socket device sock.
LISTEN=expr Applies to: SOC
A new socket is allocated to listen for a connection. It is made the current socket for the device, if the operation is successful.
expr specifies the protocol and the protocol-specific information. Currently, GT.M supports TCP/IP and LOCAL (also known as UNIX domain) socket protocols.
For more information, refer to “LISTEN”.
Example:
GTM>set tcp="seerv" open tcp:(listen="6321:TCP":attach="serv")::"SOCKET"
GTM>use tcp:listen="6322:TCP"
GTM>use 0 zshow "D"
/dev/pts/9 OPEN TERMINAL NOPAST NOESCA NOREADS TYPE WIDTH=80 LENG=24
seerv OPEN SOCKET TOTAL=2 CURRENT=1
SOCKET[0]=serv DESC=3 BOUND PASSIVE NOTRAP PORT=6321
ZDELAY ZBFSIZE=1024 ZIBFSIZE=87380 NODELIMITER
SOCKET[1]=h12185825450 DESC=4 BOUND PASSIVE NOTRAP PORT=6322
ZDELAY ZBFSIZE=1024 ZIBFSIZE=87380 NODELIMITER[NO]PASTHRU Applies to: TRM
Enables or disables interpretation of the ERASE character for a terminal. PASTHRU shifts management of handling and response to ERASE characters in the input stream from GT.M to the application code.
Exercise caution with PASTHRU in debugging, because using a PASTHRU terminal in Direct Mode is somewhat awkward.
[NO]TTSYNC must be used with [NO]PASTHRU to control XON/XOFF handling.
By default, the device driver operates NOPASTHRU.
PASTHRU supersedes line editing.
[NO]READSYNC Applies to: TRM
Enables or disables automatic output of <XON> before a READ and <XOFF> after a READ.
By default, the terminal drivers operate NOREADSYNC.
REWIND Applies to: SD
REWIND places the file pointer to the beginning of the file.
By default, USE does not REWIND.
SOCKET=expr Applies to: SOC
Makes the socket specified by the handle named in expr the current socket for the Socket device . If the named socket is a listening socket, it checks for an incoming connection request and if one is available, it accepts the request and creates a new connected socket in which case $KEY provides information on the new socket Specifying a socket handle not contained in the Socket device generates an error.
| Note |
|---|---|
SOCKET is compatible with DELIMITER only. |
For a usage example, refer to the socketexamplemulti2.m in the Section : “Socket Device Examples”.
[NO]TERMINATOR[=expr] Applies to: TRM
Specifies which of the 256 ASCII characters terminate a READ. For example, TERMINATOR=$C(0) makes <NUL> the terminator.
When NOESCAPE is in effect, TERMINATOR controls whether or not <ESC> or <CSI> are treated as terminators, however, when ESCAPE processing is enabled, the entire escape sequence is treated as a terminator regardless of the TERMINATOR specification.
When EDITING is enabled, the control characters used for editing are not treated as terminators even if they are in the TERMINATOR list.
You can define any control character as a terminator, but they are all single character.
When the terminal is in UTF-8 mode (chset=utf8,) GT.M limits the terminator characters to the first 127 which are common between ASCII and Unicode. In M mode, any of the 256 characters may be specified a terminator.
In UTF-8 mode, if CR is in the terminator list (either by default or explicitly,) GT.M ignore the following LF to keep with the standard Unicode line terminator scheme.
NOTERMINATOR eliminates all terminators. When a terminal has all terminators disabled, fixed length READ and READ * terminate on receipt of some number of characters, and a timed READ terminates on timeout, but any other READ only terminates when the input fills the terminal read buffer.
By default, terminals recognize <CR>, <LF>, and <ESC> as terminators (that is, TERMINATOR=$C(10, 13,27)). TERMINATOR="" restores the default. In UTF-8 mode, the usual Unicode line terminators are also included in the default set of terminators.
Example:
GTM> USE $P:TERM=$C(26,13,11,7)
This example enables the ASCII characters <SUB>, <CR>, <VT> and <BEL> as READ terminators.
[NO]TRUNCATE Applies to: SD
Enables or disables overwriting of existing data in sequential files. Because the position of each record depends on the prior record, a WRITE destroys the ability to reliably position to subsequent records in a file. Therefore, by default (NOTRUNCATE), GT.M permits WRITEs only when the file pointer is positioned at the end-of-file. When a device has TRUNCATE enabled, a WRITE issued when the file pointer is not at end-of-file truncates the file by destroying all data from the file pointer to the end-of-file.
By default, OPEN accesses files NOTRUNCATE, which does not allow overwriting of sequential files.
This deviceparameter may not be supported by your platform.
[NO]TTSYNC Applies to: TRM
Enables or disables recognition of XON/XOFF for terminal output.
| Note |
|---|---|
A terminal may have its own handling of XON/XOFF, controlled by a set-up mode or by switches. If an application requires program recognition of <CTRL-S> and <CTRL-Q>, the terminals may require reconfiguration. |
[NO]TYPEAHEAD Applies to: TRM
Enables or disables type-ahead buffering for a terminal. When TYPEAHEAD is disabled, any pending input which has not yet been read will be discarded before input is read for each READ argument. When TYPEAHEAD is enabled, any input not read by one READ argument will remain available for the next READ argument or command.
The size of the type-ahead buffer limits the amount of data entered at the terminal that the device driver can store in anticipation of future READs.
By default, the terminal device driver accepts TYPEAHEAD.
UPSCROLL Applies to: TRM
Moves the cursor down one line on the terminal screen. If $Y=LENGTH-1, UPSCROLL sets $Y=0. Otherwise UPSCROLL increments $Y by one. If the cursor is physically at the bottom of the page, the screen scrolls up one line. UPSCROLL does not change the column position or $X.
[Z]WIDTH=intexpr Applies to: TRM SOC NULL SD FIFO PIPE
Sets the device's logical record size and enables WRAP. The default WIDTH for SD and FIFO is taken from the RECORDSIZE.
NOWRAP and WIDTH supersede each other. When WIDTH and NOWRAP appear together on the same USE command, the final one controls the device behavior. For a terminal, WIDTH=0 is equivalent to WIDTH=n:NOWRAP, where n is the default length of a logical record on that terminal.
Terminals inherit their default WIDTH in GT.M from the invoking shell environment. The default WIDTH for null and socket device is 255.
For SD and SOC which support 1MB strings, you can specify WIDTH up to 1,048,576.
For non fixed format, always include the line terminator in WIDTH otherwise you get NULL reads after records which are WIDTH wide.
In UTF-8 mode and TRM, SD, and FIFO output, the WIDTH deviceparameter is in units of display-columns and is used with $X to control truncation and WRAPing for output and maintenance of $X and $Y for input.
In UTF-8 mode and SOC, the WIDTH deviceparameter is in units of Unicode code points and is used with $X to control truncation and wrapping for output and maintenance of $X and $Y for input.
In M mode if WIDTH is set to 0, GT.M uses the default WIDTH of the TRM and SOC devices. USE x:WIDTH=0 is equivalent to USE x:(WIDTH=<device-default>:NOWRAP. For SD and FIFO devices in M mode, the device default is the RECORDSIZE.
GT.M format control characters, FILTER, and the device WIDTH and WRAP also have an effect on $X.
In UTF-8 mode and SOC output, the WIDTH deviceparameter specifies the number of characters in Unicode.
[Z][NO]WRAP Applies to: TRM SOC NULL SD FIFO
Enables or disables automatic record termination. When the current record size ($X) reaches the maximum WIDTH and the device has WRAP enabled, GT.M starts a new record, as if the routine had issued a WRITE ! command.
NOWRAP causes GT.M to require a WRITE ! to terminate the record. NOWRAP allows $X to become greater than the device WIDTH for terminals.
By default, WIDTH sets WRAP. When WIDTH and NOWRAP appear together on the same USE command, the last one controls the device behavior.
By default, records WRAP.
Example:
See WRAP examples in the OPEN deviceparameters section.
X=intexpr Applies to: TRM
$X positions the cursor to a vertical column on the terminal. If NOWRAP is enabled or intexpr<WIDTH, GT.M sets $X=intexpr. If WRAP is enabled and intexpr>WIDTH, GT.M sets $X=intexpr#WIDTH, where # is the GT.M modulo operator. The resulting $X determines the actual physical position.
To ensure that $Y and $X match what is occurring visually on the terminal, the GT.M deviceparameters and the device characteristics must match at all times.
The terminal hardware may affect physical cursor positioning. The X deviceparameter does not change the cursor row or update $Y.
Y=intexpr Applies to: TRM
Positions the cursor to a horizontal row on the terminal.
GT.M sets $Y=intexpr#LENGTH, where # is the GT.M modulo operator. If intexpr<LENGTH, the resulting $Y determines the physical position. If intexpr>LENGTH, the cursor is positioned so that $Y=intexpr#LENGTH, where # is the GT.M module operator. The terminal hardware may affect physical cursor positioning.
To ensure that $Y and $X match what is occurring visually on the terminal, the GT.M deviceparameters and the device characteristics must match at all times. For example, if a process initiates a subprocess that changes the terminal wrap setting from NOWRAP, previously set with the GT.M USE command to WRAP , GT.M does not reflect the change when the subprocess completes. Therefore, wraps on the terminal do not reflect in the values of $X and $Y.
The Y deviceparameter does not change the cursor column or update $X.
ZBFSIZE Applies to: SOC
Allocates a buffer used by GT.M when reading from a socket. The ZBFSIZE deviceparameter should be at least as big as the largest message expected.
By default, the size of ZBFSIZE is 1024 and the maximum it can be is 1048576.
Z[NO]DELAY Applies to: SOC
Controls buffering of data packets by the system TCP stack using the TCP_NODELAY option to the SETSOCKOPT system call. This behavior is sometimes known as the Nagle algorithm. The default is ZDELAY. This delays sending additional packets until either an acknowledgement of previous packets is received or an interval passes. If several packets are sent from one end of a connection before the other end responds, setting ZNODELAY may be desirable though at the cost of additional packets being transmitted over the network. ZNODELAY must be fully spelled out.
Z[NO]FF=expr Applies to: SOC
expr specifies a string of characters, typically in $CHAR() format to send to socket device, whenever a routine issues a WRITE #. When no string is specified or when ZFF="", then no characters are sent. The default in GT.M is ZNOFF.
Example:
u tcpdev:(zwidth=80:zff=$char(13):zlength=24)
This example sends $char(13) to the current socket of device tcpdev on every WRITE #.
|
USE Deviceparameters | ||||||
|---|---|---|---|---|---|---|
|
USE DEVICEPARAMETER |
TRM |
SD |
FIFO | PIPE |
NULL |
SOC |
|
TRM: Valid for terminals and printers SD: Valid for sequential files FIFO: Valid for FIFOs PIPE: Valid for PIPE devices NULL: Valid for null devices SOC: Valid for socket devices | ||||||
|
ATTACH |
X | |||||
|
CANONICAL |
X | |||||
|
[NO]CENABLE |
X | |||||
|
CLEARSCREEN |
X | |||||
|
CONNECT |
X | |||||
|
[NO]CONVERT |
X | |||||
|
CTRAP=expr |
X | |||||
|
[NO]DELIMITER |
X | |||||
|
DETACH=expr |
X | |||||
|
DOWNSCROLL |
X | |||||
|
[NO]EBCDIC | ||||||
|
[NO]ECHO |
X | |||||
|
[NO]EMPT[ERM] |
X | |||||
|
ERASELINE |
X | |||||
|
ERASETAPE | ||||||
|
[NO]ESCAPE |
X | |||||
|
EXCEPTION=expr |
X |
X |
X |
X |
X | |
|
[NO]FILTER[=expr] |
X |
X |
X | |||
|
FLUSH |
X | |||||
|
[NO]FOLLOW |
X | |||||
|
[NO]HOSTSYNC |
X | |||||
|
IOERROR |
X | |||||
|
[Z]LENGTH=expr |
X |
X |
X |
X |
X | |
|
[NO]PASTHRU |
X | |||||
|
[NO]RCHK | ||||||
|
[NO]RETRY | ||||||
|
REWIND |
X | |||||
|
SKIPFILE=intexpr | ||||||
|
SOCKET |
X | |||||
|
SPACE=intexpr | ||||||
|
[NO]STREAM |
X | |||||
|
TERMINATOR[=expr] |
X | |||||
|
[NO]TRUNCATE |
X | |||||
|
[NO]TYPEAHEAD |
X | |||||
|
UPSCROLL |
X | |||||
|
[NO]WCHK | ||||||
|
[Z]WIDTH=intexpr |
X |
X |
X | X |
X |
X |
|
[Z][NO]WRAP |
X |
X |
X |
X |
X | |
|
WRITELB=expr | ||||||
|
WRITETM | ||||||
|
X=intexpr |
X |
X | ||||
|
Y=intexpr |
X |
X | ||||
|
ZBFSIZE |
X | |||||
|
Z[NO]DELAY |
X | |||||
|
Z[NO]FF |
X | |||||
|
ZIBUFSIZE |
X | |||||
|
LISTEN |
X | |||||
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.
The READ X#maxlen command limits the maximum size of the input to a maximum of "maxlen" characters, where maxlen is an integer expression.
If a READ follows a READ X#maxlen command, the READ returns the remainder of the current record.
If a terminator arrives before maxlen characters are received the READ X#maxlen terminates.
For fixed format files, If WIDTH - $X is greater than len, READ X#maxlen reads maxlen characters otherwise READ reads WIDTH - $X characters. Fewer may be returned if end of file is reached.
For VARIABLE or STREAM format files, READ X#maxlen reads up to MIN(maxlen, WIDTH - $X) characters, stopping if it finds line terminator or end of file.
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 |
|---|---|
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.
When the argument of a WRITE command consists of a leading asterisk (*) followed by an integer expression, the WRITE command outputs the character represented by the code-point value of that integer expression.
With character set M specified at device OPEN, the WRITE * command transfers the character (byte) associated with the numeric value of the integer expression. With character UTF-8 specified at device OPEN, the WRITE command outputs the character associated with the numeric code-point value. If character set "UTF-16", "UTF-16LE" or "UTF-16BE" is specified, WRITE * transforms the character code to the mapping specified by that character set.
The CLOSE command breaks the connection between a process and a device.
The format of the CLOSE command is:
C[LOSE][:tvexpr] expr[:(keyword[=expr][:...])][,...]
The optional truth-valued expression immediately following the command is a command postconditional that controls whether or not GT.M executes the command.
The required expression specifies the device to CLOSE.
The optional keywords specify deviceparameters that control device behavior; some deviceparameters take arguments delimited by an equal sign (=); if there is only one keyword, the surrounding parentheses are optional.
An indirection operator and an expression atom evaluating to a list of one or more CLOSE arguments form a legal argument for a CLOSE.
When a CLOSE is issued, GT.M flushes all pending output to the device, and processes any deviceparameters. CLOSEing a device not currently OPEN has no effect.
If a partial record has been output, a WRITE ! is done to complete it. To suppress this action, set $X to zero before the CLOSE.
GT.M retains the characteristics of all device types, except a sequential file, for use in case of subsequent re-OPENs. If the device is a sequential file, characteristics controlled by deviceparameters are lost after the CLOSE.
If the device being CLOSEd is $IO, GT.M implicitly USEs $PRINCIPAL. GT.M ignores CLOSE $PRINCIPAL.
Example:
CLOSE SD:RENAME=SD_".SAV"
This closes the device and, if it is a disk file, renames it to have the type .SAV.
Example:
CLOSE SOCKDEV:(SOCKET="LOCALSOCK1":DELETE)
This deletes the socket file associated with LOCALSOCK1 if it is a listening socket and closes only the named socket on the socket device.
DELETE Applies to: SD FIFO SOC(LOCAL)
Instructs GT.M to delete the disk file after GT.M closes it.
[NO]DESTROY Applies to: SD, FIFO, SOC
Determines whether the process retains device characteristics after CLOSE. The default is DESTROY for sequential disk files and FIFO devices and NODESTROY for SOCKET devices. While NODESTROY allows the re-OPEN of previously CLOSE'd device with the same characteristics as when it was last CLOSE'd, as described by the M standard, every tracked device uses process memory. A device that has been DESTROYed on CLOSE cannot be re-opened with the previous characteristics, but reclaims memory used by the process for that device. [NO]DESTROY is ignored for CLOSE of a specific socket rather than the entire socket device.
The default is DESTROY for PIPE devices. NODESTROY does not apply to PIPE devices.
EXCEPTION=expr Applies to: All devices
Defines an error handler for an I/O device. The expression must contain a fragment of GT.M code (for example, GOTO ERRFILE) that GT.M XECUTEs when the driver for the device detects an error, or an entryref to which GT.M transfers control, as appropriate for the current gtm_ztrap_form.
The expression must contain a fragment of GT.M code (for example, GOTO ERRFILE) that GT.M XECUTEs when the driver for the device detects an error, or an entryref to which GT.M transfers control, as appropriate for the current gtm_ztrap_form.
For more information on error handling, refer to Chapter 13: “Error Processing”.
GROUP=expr Applies to: SOC(LOCAL), SD, FIFO
Specifies access permission on a UNIX file for other users in the file owner's group. The expression is a character string evaluating to null or to any combination of the letters RWX, indicating respectively Read, Write, and eXecute access. When any one of these deviceparameters (OWNER, GROUP, WORLD) appear on a CLOSE of an existing file, any user category, that is not explicitly specified remains unchanged.
In order to modify file security, the user who issues the CLOSE must have ownership.
By default, CLOSE does not modify the permissions on an existing file.
OWNER=expr Applies to: SOC(LOCAL) SD FIFO
Specifies access permission on a UNIX file for the owner of the file. The expression is a character string evaluating to null or to any combination of the letters RWX, indicating respectively Read, Write, and eXecute access. When any one of these deviceparameters appear on a CLOSE of an existing file, any user category (GROUP, SYSTEM, WORLD), that is not explicitly specified remains unchanged.
In order to modify file security, the user who issues the CLOSE must have ownership.
By default, CLOSE does not modify the permissions on an existing file.
RENAME=expr Applies to: SD
Changes the file name to the name contained in the argument string. When the expression omits part of the pathname, GT.M constructs the full pathname by applying the defaults discussed in the section on device specifications.
If the process has sufficient access permissions, it may use RENAME to specify a different directory as well as file name. RENAME cannot move a file to a different filesystem.
SOCKET=expr Applies to: SOC
The socket specified in expr is closed. Specifying a socket that has not been previously OPENed generates an error. If no SOCKET deviceparameter is specified on a CLOSE for a socket device, the socket device and all sockets associated with it are closed.
SYSTEM=expr Applies to: SOC(LOCAL) SD FIFO
This deviceparameter is a synonym for OWNER that is maintained in UNIX for compatibility with VMS applications.
By default, CLOSE does not modify the permissions on an existing file.
TIMEOUT=expr Applies to: PIPE
Performs a timed check (in seconds) on the termination status of the PIPE co-process of a PIPE device that is not OPEN'd with the INDEPENDENT deviceparameter. intexpr specifies time in seconds. The default is 2 seconds if TIMEOUT is not specified.
UIC=exprgroup number Applies to: SOC(LOCAL) SD FIFO
Specifies the group that has access to the file. The format of the string is "g,i" where g is a decimal number representing the group portion of the UIC and i is a decimal number representing the individual portion.
Specifies the owner and affects access to the file. The expression evaluates to the numeric identifier of the new owner.
WORLD=expr Applies to: SOC(LOCAL) SD FIFO
Specifies access permissions for users not in the owner's group on a UNIX file. The expression is a character string evaluating to null or to any combination of the letters RWX, indicating respectively Read, Write, and eXecute access. When any one of these deviceparameters (OWNER, GROUP, WORLD) appears on a CLOSE of a new file, any user category that is not explicitly specified is given the default character string. When any one of these deviceparameters (OWNER, GROUP, WORLD) appears on a CLOSE of an existing file, any user category , that is not explicitly specified remains unchanged.
In order to modify file security, the user who issues the CLOSE must have ownership.
By default, CLOSE and CLOSE do not modify the permissions on an existing file. Unless otherwise specified, when CLOSE creates a new file, it establishes security using standard defaulting rules.
In order to modify file security, the user who issues the CLOSE must have ownership.
|
CLOSE Deviceparameters | ||||
|---|---|---|---|---|
|
CLOSE DEVICEPARAMETER |
TRM |
SD |
FIFO |
SOC |
|
SD: Valid for sequential disk files TRM: Valid for terminals and printers FIFO: Valid for FIFOs NULL: Valid for NULL devices SOC: Valid for Socket devices | ||||
|
DELETE |
X |
X | ||
|
DESTROY |
X |
X | X | |
|
ERASETAPE=expr | ||||
|
EXCEPTION=expr |
X |
X |
X |
X |
|
GROUP=expr |
X | |||
|
OWNER=expr |
X | |||
|
RENAME=expr |
X | |||
|
REWIND | ||||
|
SOCKET |
X | |||
|
SPACE | ||||
|
SYSTEM=expr |
X | |||
|
UIC=group name |
X | |||
|
WORLD=expr |
X | |||
| Note |
|---|---|
Since EXCEPTION is the only CLOSE deviceparameter that applies to NULL, the NULL device column is not shown in the table above. |
The following table lists all of the deviceparameters and shows the commands to which they apply.
|
Deviceparameter Summary | |||
|---|---|---|---|
|
DEVICEPARAMETER |
OPEN |
USE |
CLOSE |
|
APPEND |
X | ||
|
ATTACH |
X | ||
|
BLOCKSIZE=intexpr |
X | ||
|
[NO]CENABLE |
X | ||
|
CLEARSCREEN |
X | ||
|
CONNECT |
X |
X | |
|
[NO]CONVERT |
X | ||
|
CTRAP |
X | ||
|
DELETE |
X | ||
|
[NO]DELIMITER |
X |
X | |
|
DETACH |
X | ||
|
DOWNSCROLL |
X | ||
|
[NO]ECHO |
X | ||
|
ERASELINE |
X | ||
|
[NO]ESCAPE |
X | ||
|
EXCEPTION=expr |
X |
X |
X |
|
[NO]FILTER[=expr] |
X | ||
|
[NO]FIXED |
X | ||
|
FLUSH |
X | ||
|
GROUP=expr |
X |
X |
X |
|
IOERROR=expr |
X |
X | |
|
[NO]HOSTSYNC |
X | ||
|
[Z]LENGTH=intexpr |
X | ||
|
NEWVERSION |
X | ||
|
OWNER=expr |
X |
X |
X |
|
[NO]PASTHRU |
X | ||
|
[NO]RCHK |
X |
X | |
|
[NO]READONLY |
X | ||
|
RECORDSIZE=intexpr |
X | ||
|
RENAME=expr |
X | ||
|
[NO]RETRY |
X |
X | |
|
REWIND |
X |
X |
X |
|
SKIPFILE=intexpr |
X | ||
|
SOCKET |
X |
X | |
|
SPACE=intexpr |
X |
X | |
|
[NO]STREAM |
X | ||
|
SYSTEM=expr |
X |
X | |
|
TERMINATOR=expr |
X | ||
|
TIMEOUT=expr | X | ||
|
[NO]TRUNCATE |
X |
X | |
|
[NO]TTSYNC |
X | ||
|
[NO]TYPEAHEAD |
X | ||
|
UIC=expr |
X |
X | |
|
UPSCROLL |
X | ||
|
VARIABLE |
X | ||
|
[Z]WIDTH=intexpr |
X | ||
|
WORLD=expr |
X |
X | |
|
[Z][NO]WRAP |
X |
X | |
|
WRITELB=expr |
X | ||
|
X=intexpr |
X | ||
|
Y=intexpr |
X | ||
|
ZBFSIZE |
X |
X | |
|
Z[NO]DELAY |
X |
X | |
|
Z[NO]FF |
X |
X | |
|
ZIBFSIZE |
X |
X | |
|
LISTEN=expr |
X |
X | |
