HP OpenVMS Systems Documentation

OpenVMS I/O User's Reference Manual

5.3.1 Terminal Characteristics Categories

The set mode and set characteristics functions (see Section 5.4.3) andthe DCL command SET TERMINAL are used to change terminalcharacteristics. 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, setcharacteristics, sense mode, and sense characteristics. All I/Ofunctions can take function modifiers.

5.4.1 Read

When a read function code is issued, the user-specified buffer isfilled with characters from the associated terminal. The operatingsystem 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 twoconditions 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 theread function codes. The codes can take all six arguments (P1 throughP6) on QIO requests. The descriptions for these arguments differ whenitemlist 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 theaddress and size of a prompt string buffer containing data to bewritten to the terminal before the input data is read. In a read withprompt operation, both read and write operations are performed on thespecified terminal. The prompt string buffer is formatted like anyother write buffer. If cursor position specifiers are supplied, theyare not interpreted by the driver but passed to the terminal.

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

Depending on the terminal type and your input, the prompt string can bevery simple or quite complex---from single command prompts to screenfills followed by input data. Compaq recommends that prompt stringscontain only one leading line feed.

In PASTHRU mode, data received from the associated terminal is placedin 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 functionmodifiers 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 terminatorset for the read function or points to the location containing theterminator set. If P4 is 0, all ASCII characters with a code in therange 0 through 31 (hexadecimal 0 through 1F) except LF, VT, FF, TAB,and BS, are terminators (see Appendix C). This is the RMS standardterminator set. The delete character (hexadecimal 7F) and 8-bitcontrols in the range 128 through 159, and 255 (hexadecimal 80 through9F, and FF) are also terminators. If line editing is enabled, onlyReturn, Ctrl/Z, or an escape sequence terminates a read operation.

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

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

If the terminator mask is all zeros, there are no specifiedterminators. 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 isspecified or the line has the TT2$M_PASTHRU characteristic (seeSection 5.2.1.2).

Figure 5-3 Short and Long Forms of Terminator MaskQuadwords

5.4.1.3 Itemlist Read Operations

Itemlist read operations provide expanded software features to read QIOrequests. The operating system provides the following combination offunction code and modifier:

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

No other function modifiers can be specified in an itemlist readrequest.

Note

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

The itemlist read function code and modifier combination takes thefollowing 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 parameterMAXBUF as well as the terminal driver. The terminal driver will onlyfunction 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 aseries of item descriptors. Figure 5-4 shows the format for thesedescriptors. 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 firstlongword 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.

Contents

Index