Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

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:

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:

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

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

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:

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:

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

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6136PRO_018.HTML