ATTACH=expr Applies to: SOC

When ATTACH is used and one of ZLISTEN and CONNECT is specified at the same time, the value of expr becomes the identifier of the newly created socket. If neither ZLISTEN nor CONNECT is specified, expr specifies the socket to be moved from the socketpool to the socket device argument of USE.

[NO]CENABLE Applies to: TRM

Enables or disables the ability to force GT.M into Direct Mode by entering <CTRL-C> at $PRINCIPAL.

[NO]CENABLE is subordinate to a CTRAP that includes <CTRL-C> ($C(3)).

By default, images have CENABLEd. Linking the image with a GTM$DEFAULTS that has parameter GTM$CTRLC_ENABLE==0 changes the default for the image.

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 protocol specific information. Currently, TCP/IP is the only protocol GT.M supports. expr should be of the format "<host>:<port>:TCP", where host is either an IP address or a hostname like server.sanchez.com.

	CONNECT is not compatible with ZLISTEN.

[NO]CONVERT Applies to: TRM

Enables or disables the terminal device driver from converting lowercase input to uppercase during READs.

By default, the terminal device driver operates NOCONVERT.

CTRAP=expr Applies to: TRM

Establishes the <CTRL> characters in the expression as trap characters for the current device. When the terminal device driver 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:

For more information on error handling, refer "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 sockets associated with the device. The default when the socket device is first OPENed is NODELIMITER. The delimiter list on a preexisting device remains the same until it is explicitly replaced or deleted.

expr must be a string of the following format:

	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.

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:

DOWNSCROLL 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 terminal device driver echo of input.

By default, terminal device drivers ECHO.

[NO]EDITING Applies to: TRM

Enables or disables the VMS terminal line editor. The VMS line editor allows the use of the left and right cursor movement keys, function keys 11 through 14 and certain <CTRL> characters, in modifying the current input line. Note that this is analogous to the /[NO]LINE_EDITING qualifier of the DCL SET TERMINAL command, not the /[NO]EDIT_MODE qualifier.

By default, the terminal device driver supports EDITING.

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 terminal device driver processing of escape sequences.

The following events result when a terminal has ESCAPE sequencing 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 this case, if the sequence starts with an <ESC>, READ * returns the decimal ASCII representation for the character of the escape introducer.

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 terminal device driver places the remaining characters of the escape sequence in the input buffer for subsequent READs, regardless of [NO]TYPEAHEAD."

Since most escape sequences have special VMS interpretations, particularly for VMS line editing, escape sequence processing does not terminate READs, except for single character READs, unless the terminal has NOEDITING or PASTHRU set to turn off VMS interpretation of the sequences.

By default, the VMS terminal device driver performs ESCAPE sequencing.

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 (e.g., 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 "Error Processing".

FIELD=intexpr Applies to: TRM

FIELD sets the maximum length of a single terminal READ operation. By default, the terminal device driver uses a FIELD size of 1024 bytes. Specifying an integer expression of zero (0) resets the FIELD size to 1024 bytes.

Every READ which is not a READ * or an explicit fixed-length READ, is treated as a READ x# FIELD.

[NO]FILTER[=expr] Applies to: TRM SOC NULL

Specifies character filtering for valid filtering expressions. 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:

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. Linking the image with a GTM$DEFAULTS that has a modified GTM$USER_WRITE_FILTER parameter changes the default for the image. A value of 0x80 specifies CHARACTER filtering, a value of 0x01 specifies ESCAPE filtering, and a value of 0x81 specifies both.

FLUSH Applies to: TRM

Discards the contents of the type-ahead buffer. When a terminal has no outstanding READ and has TYPEAHEAD enabled, the device driver stores arriving input entered in a type-ahead buffer. The device driver uses data from the type-ahead buffer for subsequent READs.

The FLUSH deviceparameter can be useful for application error recovery. An application may be designed to detect an error and write a message to the terminal followed by a request for operator action. In this case, a USE $P:FLUSH preceding the READ eliminates type-ahead and prevents the type-ahead from being inappropriately used during error recovery.

[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, the device driver operates HOSTSYNC.

[NO]INSERT Applies to: TRM

Enables or disables insert mode for a terminal. When a terminal has INSERT mode enabled, the device driver inserts input characters at the logical position in the input stream designated by the cursor, .for example in the middle of the line/record. When a terminal has INSERT mode disabled, the device driver overwrites existing characters in the input stream at the logical position designated by the cursor.

By default, the VMS terminal driver operates NOINSERT (OVERSTRIKE).

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.

	GT.M currently handles exception handling at device level instead of socket level.

[Z]LENGTH=intexprApplies to: TRM SOC MBX NULL

Sets the virtual page length for an I/O device to the integer expression. The page length controls the point at which the device driver automatically resets $Y to 0.

By default, GT.M uses the LENGTH specified by the device characteristics at image activation. Sequential files, socket devices, mailboxes and null devices have a default of 66. The terminal default depends on the type of terminal.

OVERSTRIKE Applies to: TRM

Disables INSERT mode for a terminal. OVERSTRIKE is a synonym for NOINSERT.

By default, the VMS terminal driver operates OVERSTRIKE (NOINSERT).

[NO]PASTHRU Applies to: TRM

Enables or disables operating system interpretation of <CTRL> characters for a terminal. When a terminal has PASTHRU enabled, the operating system passes the characters that it normally uses to control terminal interaction through to the application program.

PASTHRU supersedes line editing.

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.

[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 for a disk file is a logical rather than a physical operation.

By default, USE does not REWIND.

SOCKET=expr Applies to: SOC

The socket specified in expr is made the current socket. Specifying a socket that has not been previously OPENed generates an error.

	SOCKET is compatible with DELIMITER only.

[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 [NO]ESCAPE 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.

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> and <ESC> as terminators, (i.e., TERMINATOR=$C(13,27)). TERMINATOR="" restores the default. However, unless the terminal has PASTHRU or NOEDITING, the operating system interprets some escape sequences rather than passing them to the READ.

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.

[NO]TTSYNC Applies to: TRM

Enables or disables recognition of XON/XOFF for terminal output. When a terminal has PASTHRU and NOTTSYNC in effect, the device driver passes <XON> and <XOFF> on to the GT.M application programs. When a terminal does not have PASTHRU enabled, [NO]TTSYNC has no effect on the GT.M process. The following table explains the logic:

	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.

By default, the VMS terminal device driver operates TTSYNC.

[NO]TYPEAHEAD Applies to: TRM

Enables or disables type-ahead buffering for a terminal. With NOTYPEAHEAD and no outstanding READ, the terminal device driver discards input entered at the terminal. With TYPEAHEAD and no outstanding READ, the device driver stores input entered at the terminal in a type-ahead buffer. The device driver uses data from the type-ahead buffer for subsequent READs.

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. When the type-ahead buffer is full, the device driver sends a warning <BEL> character to the terminal and discards input that would overflow the buffer.

FLUSH discards the contents of the type-ahead buffer.

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.

[NO]WAIT Applies to: MBX

Enables or disables synchronization of mailbox WRITEs.

A synchronized WRITE does not return control to the application program until some other process READs the written message. Such mailbox WRITEs serve as a tool for synchronizing two processes. Because GT.M does not have a timeout on the WRITE command, there is no way, other than a READ of the mailbox by another process or a <CTRL-C> on $PRINCIPAL, for the writing program to regain control of its process.

NOWAIT provides asynchronous WRITEs analogous to those always used for other device types.

By default, WRITE to a mailbox operates NOWAIT.

[Z]WIDTH=intexpr Applies to: TRM SOC NULL SD

Sets the device's logical record size and enables WRAP.

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.

By default, disks have a WIDTH of 1024, and sockets have a WIDTH of 255. Terminals inherit their default WIDTH in GT.M from the invoking VMS environment.

The default WIDTH for null and socket device is 255.

[Z][NO]WRAP Applies to: TRM SOC NULL SD

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 and null devices. Sequential files discard any portion of the current output record over the device width.

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.

WRITEOF Applies to: MBX

Writes an end-of-file (EOF) message to a mailbox device. GT.M fulfills the corresponding READ by returning a null string and setting $ZEOF to true.

X=intexpr Applies to: TRM

$X positions the cursor to a vertical column on the terminal. If NOWRAP is enabled or intexpr<WIDTH, the terminal device driver 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. For example, if a process spawns out of GT.M and changes the terminal wrap setting from NOWRAP, to WRAP with the DCL SET TERMINAL/WRAP command, GT.M returns to the NOWRAP condition when the subprocess completes, and wraps on the terminal do not reflect in the values of $X and $Y.

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 NULL

Positions the cursor to a horizontal row on the terminal.

The terminal device driver 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 spawns out of GT.M and changes the terminal wrap setting from NOWRAP, previously set with the GT.M USE command to WRAP with the DCL SET TERMINAL/WRAP command, 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.

ZIBFSIZE Applies to: SOC

Sets the buffer size used by the network software (setsockopt SO_RCVBUF).

The default and the maximum values depend on the platform and/or system parameters.

ZLISTEN=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 "BOUND|<socket handle>|<port number>"otherwise, $KEY is assigned the empty string.

expr specifies the protocol and protocol specific information. Currently, TCP/IP is the only protocol GT.M supports. expr must be of the format "<port>:TCP", where port specifies the port number at which the socket is waiting for a connection.