Document revision date: 30 March 2001

## OpenVMS I/O User's Reference Manual

Previous | Contents | Index

### 5.3.1 Terminal Characteristics Categories

The set mode and set characteristics functions (see Section 5.4.3) and the DCL command SET TERMINAL are used to change terminal characteristics. The OpenVMS DCL Dictionary describes the SET TERMINAL command.

To customize terminal behavior and usage, the operating system divides terminal characteristics into the following categories:

- Format effectors---The following characteristics allow you to specify terminal-dependent formatting requirements:

  TT$M_CRFILL | TT$M_EIGHTBIT | TT$M_LFFILL
  TT$M_LOWER | TT2$M_LOCALECHO | TT$M_MECHFORM
  TT$M_MECHTAB | TT$M_NOECHO | TT$M_SCOPE
  TT$M_WRAP |  |

- Generic terminal capabilities---The following characteristics specify generic terminal features available to applications programs:

  TT2$M_ANSICRT | TT2$M_AVO | TT2$M_BLOCK
  TT2$M_DECCRT | TT2$M_DECCRT2 | TT2$M_DECCRT3
  TT2$M_DECCRT4 | TT2$M_DRCS | TT2$M_EDIT
  TT2$M_PRINTER | TT2$M_REGIS | TT2$M_SIXEL

  Their use allows execution of these programs without knowledge of the actual terminal type. For example, a program should check for TT2$M_DECCRT rather than for VT100 or VT101.
- Protocol---The following characteristics control protocols used by the terminal:

  TT$M_ESCAPE | TT$M_HALFDUP | TT$M_HOSTSYNC
  TT2$M_PASTHRU | TT$M_TTSYNC |

- System management---The following characteristics, normally set only at system startup, allow the system manager to regulate terminal usage:

  TT2$M_ALTYPEAHD | TT2$M_AUTOBAUD | TT2$M_DIALUP
  TT2$M_DISCONNECT | TT2$M_DMA | TT2$M_HANGUP
  TT$M_MODEM | TT$M_NOTYPEAHD | TT2$M_MODHANGUP
  TT2$M_SECURE | TT2$M_SETSPEED | TT2$M_SYSPWD
  TT2$M_COMMSYNC |  |

- User preference---The following characteristics allow you to customize the terminal operating mode:

  TT2$M_APP_KEYPAD | TT2$M_FALLBACK | TT2$M_EDITING
  TT2$M_INSERT | TT$M_NOBRDCST |

- Miscellaneous---The following characteristics provide greater program control of terminal operations:

  TT2$M_BRDCSTMBX | TT$M_MBXDSABL | TT2$M_XON

## 5.4 Terminal Function Codes

The basic terminal I/O functions are read, write, set mode, set characteristics, sense mode, and sense characteristics. All I/O functions can take function modifiers.

### 5.4.1 Read

When a read function code is issued, the user-specified buffer is filled with characters from the associated terminal. The operating system provides the following read function codes:

- IO$_READVBLK---Read virtual block
- IO$_READLBLK---Read logical block
- IO$_READPROMPT---Read with prompt

Read operations are terminated if either of the following two conditions occurs:

- The user buffer is full.
- The received character is included in a specified terminator mask (see Section 5.4.1.2).

The following device- or function-dependent arguments are used with the read function codes. The codes can take all six arguments (P1 through P6) on QIO requests. The descriptions for these arguments differ when itemlist read operations are performed (see Section 5.4.1.3).

- P1---The starting virtual address of the buffer that is to receive the data read.
- P2---The size of the buffer that is to receive the data read in bytes. (The system generation parameter, MAXBUF, and the terminal driver limit the maximum size of the buffer. The terminal driver will only function with buffer sizes less than 32718 bytes.)
- P3---Read with timeout, timeout count (see Table 5-7, IO$M_TIMED).
- P4---The read terminator descriptor block address (see Section 5.4.1.2).
- P5---The starting virtual address of the prompt buffer that is to be written to the terminal; for read with prompt operations using the IO$_READPROMPT function code. (This argument is specified as a value rather than an address as in the P1 argument.)
- P6---The size of the prompt buffer that is to be written to the terminal; for read with prompt operations using the IO$_READPROMPT function code.

In a read with prompt operation, the P5 and P6 arguments specify the address and size of a prompt string buffer containing data to be written to the terminal before the input data is read. In a read with prompt operation, both read and write operations are performed on the specified terminal. The prompt string buffer is formatted like any other write buffer. If cursor position specifiers are supplied, they are not interpreted by the driver but passed to the terminal.

During a read with prompt operation, pressing Ctrl/O (which is turned off at the start of any read operation) stops the prompt string. If you press either Ctrl/U or Ctrl/X, the entire prompt string is written out again, and the current input is ignored. If you press Ctrl/R, the current prompt string and input are written to the terminal.

Depending on the terminal type and your input, the prompt string can be very simple or quite complex---from single command prompts to screen fills followed by input data. Compaq recommends that prompt strings contain only one leading line feed.

In PASTHRU mode, data received from the associated terminal is placed in the user buffer as binary information without interpretation. (Prompts are not refreshed after a broadcast in PASTHRU mode.)

#### 5.4.1.1 Function Modifier Codes for Read QIO Functions

Eight function modifiers can be specified with IO$_READVBLK, IO$_READLBLK, and IO$_READPROMPT. Table 5-7 lists these function modifiers and IO$_EXTEND, which is described in Section 5.4.1.3. All read function modifiers are supported for LAT devices.

Table 5-7 Read QIO Function Modifiers for the Terminal Driver
Code | Consequence
--- | ---
IO$M_CVTLOW | Lowercase alphabetic characters (hexadecimal 61 to 7A) are converted to uppercase when transferred to the user buffer or echoed. This characteristic is used only for IO$_READLBLK, IO$_READVBLK, and IO$_READPROMPT.
IO$M_DSABLMBX | The mailbox is disabled for unsolicited data.
IO$M_ESCAPE | A valid ANSI escape sequence is recognized as a valid delimiter for the read operation. The TT$M_ESCAPE characteristic is overridden by this modifier for the current read operation.
IO$M_EXTEND | This characteristic provides additional functionality for read operations (see Section 5.4.1.3). Do not specify IO$M_EXTEND with other function modifiers.
IO$M_NOECHO | Characters are not echoed as they are entered at the keyboard. The terminal line can also be set to a "no echo" mode by the set mode characteristic TT$M_NOECHO, which inhibits all read operation echoing. Setting IO$M_NOECHO also disables line editing.
IO$M_NOFILTR | The terminal does not interpret Ctrl/U, Ctrl/R, or DEL. They are passed to the user. IO$M_NOFILTR explicitly disables line editing.
IO$M_PURGE | The type-ahead buffer is purged before the read operation begins.
IO$M_TIMED | The P3 argument specifies the maximum time (seconds) that can elapse between characters received from the terminal (the timeout value for the operation). Because driver timing operates on a 1-second timer, a 2-second timeout must be specified to guarantee a 1-second wait. The timer starts when the prompt echo is started. If the read time exceeds the time specified in P3, a timeout error (SS$_TIMEOUT) is returned in the read IOSB. All input characters received before the read operation timed out are returned in the user's buffer. A read with timeout operation, in which the timeout value is 0, empties the type-ahead buffer into the user buffer until the proper termination condition is reached (buffer full, termination character detected, or type-ahead buffer empty). The read operation then returns the count of characters read and, if a terminator is read, SS$_NORMAL; SS$_TIMEOUT is returned if no terminator is read. In either case the offset to terminator in the IOSB always indicates the number of characters read. If a write request is active and there is no prompt string, the read request generally times out with zero bytes of data being returned. If a read operation is interrupted by either a broadcast write or a synchronous write request, the timer operation is restarted.
IO$M_TRMNOECHO | The termination character (if any) is not echoed. There is no formal terminator if the buffer is filled before the terminator is typed.

#### 5.4.1.2 Read Function Terminators

The P4 argument to a read QIO function either specifies the terminator set for the read function or points to the location containing the terminator set. If P4 is 0, all ASCII characters with a code in the range 0 through 31 (hexadecimal 0 through 1F) except LF, VT, FF, TAB, and BS, are terminators (see Appendix C). This is the RMS standard terminator set. The delete character (hexadecimal 7F) and 8-bit controls in the range 128 through 159, and 255 (hexadecimal 80 through 9F, and FF) are also terminators. If line editing is enabled, only Return, Ctrl/Z, or an escape sequence terminates a read operation.

If P4 does not equal 0, it contains the address of a quadword that either specifies a terminator character bit mask or points to a location containing that mask. (Note that if P4 references an address in a MACRO program, a number sign (#) must precede the address; for example, P4=#TMASK.) The quadword has a short form and a long form, as shown in Figure 5-3. In the short form, the correspondence is between the bit number and the binary value of the character; the character is a terminator if the bit is set. For example, if bit 0 is set, NULL is a terminator; if bit 9 is set, TAB is a terminator. If a character is not specified, it is not a terminator. Since ASCII control characters are in the range 0 through 31, the short form can be used in most cases.

The long form allows use of a more comprehensive set of terminator characters. Any mask equal to or greater than 1 byte is acceptable. For example, a mask size of 16 bytes allows all 7-bit ASCII characters to be used as terminators; a mask size of 32 bytes allows all 8-bit characters to be used as terminators for 8-bit terminals.

If the terminator mask is all zeros, there are no specified terminators. The read operation ends when the specified number of bytes (characters) have been transferred to the input buffer.

Certain control keys will not act as terminators unless IO$M_NOFILTR is specified or the line has the TT2$M_PASTHRU characteristic (see Section 5.2.1.2).

Figure 5-3 Short and Long Forms of Terminator Mask Quadwords

#### 5.4.1.3 Itemlist Read Operations

Itemlist read operations provide expanded software features to read QIO requests. The operating system provides the following combination of function code and modifier:

> IO$_READVBLK!IO$M_EXTEND---Itemlist read virtual block

No other function modifiers can be specified in an itemlist read request.

Note Itemlist read features supported by the terminal driver are not supported by all DECnet terminal emulators.

The itemlist read function code and modifier combination takes the following device- or function-dependent arguments:

- P1---The starting virtual address of the buffer that is to receive the data read.
- P2---The size of the buffer that is to receive the data read in bytes. If required, the P2 size includes additional space for an overflow buffer to hold an escape sequence terminator (see item code TRM$_ESCTRMOVR in Table 5-8).

  Note The IO$_READxBLK and IO$_WRITExBLK are limited by the system parameter MAXBUF as well as the terminal driver. The terminal driver will only function with buffer sizes less than 32718 bytes.

- P3---The access mode at which the itemlist is to be probed (optional).
- P5---The address of the itemlist buffer.
- P6---The length in bytes of the itemlist buffer.

P4 is not meaningful for itemlist read operations. P5 points to a series of item descriptors. Figure 5-4 shows the format for these descriptors. You cannot repeat the same item code in the same item list.

Figure 5-4 Itemlist Read Descriptor

Table 5-8 lists the item codes that can be specified in the first longword of the item descriptors.

Table 5-8 Item Codes for Itemlist Read Operations for the Terminal Driver
Item Code | Meaning
--- | ---
TRM$_ALTECHSTR | Alternate echo string. The buffer length word contains the length of the string. The data address word contains the address of the string. The alternate echo string is written to the terminal after the first character is entered. This item code for character validating read mode (TRM$K_EM_RDVERIFY) editing only.
TRM$_EDITMODE | Extended editing modes. The immediate data longword specifies extended editing mode values. The buffer length word must be zero. The following editing modes are supported:
TRM$K_EM_DEFAULT | Normal read mode. This is the default if TRM$_EDITMODE is not present in the itemlist.
TRM$K_EM_RDVERIFY | Character validating read mode. See Section 5.4.1.4.
TRM$_ESCTRMOVR | Escape terminator overflow size. Specifies the number of bytes that may be used to hold an escape sequence terminator. This number should be included in P2, the buffer size argument, in addition to the space required for the data to be read. Note that this overflow area is for the terminator only; it is not available for user data. TRM$_ESCTRMOVR is useful in preventing partial escape errors, which return SS$_PARTESCAPE. This overflow buffer ensures that all the characters in an escape sequence terminator will fit in the user buffer, thus eliminating the need for additional single-character read operations.
TRM$_FILLCHR | A 2-byte value that indicates the fill and clear character for TRM$K_EM_RDVERIFY. The first byte of the immediate data longword specifies the clear character; the second byte specifies the fill character. This item code is for character validating read mode (TRM$K_EM_RDVERIFY) editing only.
TRM$_INIOFFSET | Indicates the character in the initial string where echoing starts. The immediate data longword specifies the character.
TRM$_INISTRNG | Specifies a string to preload into the read buffer (P1). The buffer length word contains the length of the string. The data longword contains the address of the string. TRM$_INISTRNG must be specified if the edit mode is TRM$K_EM_RDVERIFY, and must be the same length as specified by TRM$_PICSTRNG.
TRM$_MODIFIERS | Read modifiers. The immediate data longword contains a 32-bit value that specifies modifiers to read operations. The read operations are defined in $TRMDEF. The buffer length word must be zero. The following bits are defined:
TRM$M_TM_ARROWS | The terminal interprets the left and right arrow keys (TRM$K_EM_RDVERIFY mode only). The arrow keys are not put in the buffer and do not terminate the read. TRM$_ESCTRMOVR must be greater than or equal to 5.
TRM$M_TM_AUTO_TAB | This bit creates an auto-tab mode field (TRM$K_EM_RDVERIFY mode only).
TRM$M_TM_CVTLOW | Lowercase alphabetic characters (hexadecimal 61 to 7A) are converted to uppercase when transferred to the user buffer or echoed.
TRM$M_TM_DSABLMBX | The mailbox is disabled for unsolicited data and for receiving hangup messages.
TRM$M_TM_ESCAPE | A valid ANSI escape sequence is recognized as a valid delimiter for the read operation.
TRM$M_TM_NOCLEAR | Fill characters are not replaced with clear characters after a nonfill character occurs (TRM$K_EM_RDVERIFY mode only).
TRM$M_TM_NOECHO | Characters are not displayed as they are entered at the keyboard.
TRM$M_TM_NOEDIT | This bit inhibits advanced editing for this read operation.
TRM$M_TM_NOFILTR | The terminal does not interpret DEL, Ctrl/U, or Ctrl/R, but passes them to you. This characteristic explicitly disables line editing.
TRM$M_TM_NORECALL | This bit inhibits command recall (Ctrl/B) by the terminal driver.
TRM$M_TM_OTHERWAY | This bit sets left-justify fields to insert mode and right-justify fields to overstrike mode (TRM$K_EM_RDVERIFY mode only). TRM$M_TM_TOGGLE must equal 1.
TRM$M_TM_PURGE | The type-ahead buffer is purged before the read operation begins.
TRM$M_TM_R_JUST | This bit creates a right-justified field (TRM$K_EM_RDVERIFY mode only).
TRM$M_TM_TERM_ARROW | The read operation is terminated when the left arrow key is pressed at the left margin or when the right arrow key is pressed at the right margin (TRM$K_EM_RDVERIFY mode only). TRM$M_TM_ARROWS must be enabled.
TRM$M_TM_TERM_DEL | The read operation is terminated when the DELETE key is pressed at the left margin (TRM$K_EM_RDVERIFY mode only).
TRM$M_TM_TOGGLE | Enables Ctrl/A to function as a toggle key between insert mode and overstrike mode (TRM$K_EM_RDVERIFY mode only). Left-justify insert mode shifts characters to the right; right-justify insert mode shifts characters to the left. Shifted characters are not checked for validity in their new positions.
TRM$M_TM_TIMED | TRM$_TIMEOUT specifies the maximum time (seconds) that can elapse between characters received from the terminal; that is, the timeout value for the operation. TRM$M_TM_TIMED is assumed set if TRM$_TIMEOUT is included in the itemlist. See the description of IO$M_TIMED in Table 5-7.
TRM$M_TM_TRMNOECHO | The termination character (if any) is not displayed. There is no formal terminator if the buffer is filled before the terminator is typed. All other bits must be zero.
TRM$_PICSTRNG | Character validation string. The buffer length word contains the length of the string, which must be the same as the length specified by TRM$_INISTRNG. The data address word contains the address of the string. TRM$_PICSTRNG must be specified if the edit mode is TRM$K_EM_RDVERIFY. Note that this item code is for character validating read mode (TRM$K_EM_RDVERIFY) editing only. The format of the character validation string is 1 byte per input character. Each byte is a bit mask. The following values are provided:
Value | Meaning
--- | ---
TRM$M_CV_UPPER | Uppercase alphabetic
TRM$M_CV_LOWER | Lowercase alphabetic
TRM$M_CV_NUMERIC | Numeric (0---9)
TRM$M_CV_NUMPUNC | Numeric punctuation (+ - .)
TRM$M_CV_PRINTABLE | Printable ASCII character
TRM$M_CV_ANY | Any character
If no values are set, the corresponding character specified by TRM$_INISTRNG is used. Appendix C lists the multinational character set.
TRM$_PROMPT | Specifies a prompt string. The buffer length word contains the length of the prompt. The data address word contains the address of the prompt string. See Section 5.4.1 for information on how carriage control specifiers in a prompt string are handled.
TRM$_TERM | The buffer length word determines the format of the nondefault terminator mask. If the buffer length word is zero, then the data longword is used as a short form mask. If the buffer length word is nonzero, then a mask n bytes long is available at the specified address.
TRM$_TIMEOUT | Read timeout. See the description of IO$M_TIMED in Table 5-7.

Previous | Next | Contents | Index

| privacy and legal statement |
6136PRO_018.HTML