Updated: 11 December 1998

OpenVMS I/O User's Reference Manual

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

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

• 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. The terminal driver will only function correctly 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

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.

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 sysgen 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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6136PRO_018.HTML