HP OpenVMS Systems Documentation

When using the read verify function, the terminal driver performs inputvalidation based on character attributes. (Read verification bypassesthe optionally specified termination mask (TRM$_TERM).) Validation isperformed one character at a time as data is entered. Invalidcharacters are not echoed, and cause the read operation to complete. Itis then up to the application program to handle the error appropriately.

The initial string describes the initial contents of the input field.This string may consist of data and marker characters. The clearcharacter is displayed on the screen for each occurrence of the fillcharacter in the initial string buffer.

The picture string is a string of bytes where each byte corresponds toone character of the field being entered. Each byte specifies a mask oflegal character types for that character position. If the byte is leftas zero, then that position is a marker character, and the characterfrom the initial string is echoed for that position.

For left-justified fields, the prompt data is output to the terminal,followed by an optional number (TRM$_INIOFFSET) of initial stringcharacters. Leading marker characters are always output following theprompt, leaving the cursor at the leftmost data position. As eachcharacter is entered, it is validated and then echoed, advancing thecursor position. Additional marker characters are skipped as they areencountered. If an input character fails the validation, the readoperation is completed with the invalid character as the terminator.

For right-justified fields, the prompt is output and is followed by theinitial string. (In general, TRM$_INIOFFSET is set to the length ofTRM$_INISTRNG for right-justified fields.) The cursor position remainsone position to the right of the initial string. For proper operation,right-justified fields cannot have mixed picture definitions. Aftereach character is input, the entire prompt and input fields are output.Therefore, the prompt should include a cursor positioning escapesequence.

The definition of full field is different for left- and right-justifiedread operations. For left-justified fields, full field is detected whenthe character corresponding to the last nonmarker position in thepicture string has been entered. For right-justified fields, full fieldis detected when a character other than the fill character is shiftedinto the leftmost, nonmarker position in the field.

If the modifier TRM$M_TM_AUTO_TAB is set in TRM$_MODIFIERS, thendetection of a full field terminates the read operation. In the eventof autotab termination, the terminator character in the IOSB is null.If the autotab option is not selected, then termination occurs when onemore character is typed to a full field. Applications can detect thiscondition when the terminating character index is one character beyondthe end of the field. The extra character is reported as theterminator. In a left-justified field, the IOSB index to the terminatoris zero-based; in a right-justified field, this index is one-based.

If a read verify function is interrupted by an asynchronous writeoperation, the read verify is completed with status SS$_OPINCOMPL.

No line editing functions other than the delete character function aresupported for read verify.

5.4.2 Write

Write operations display the contents of a user-specified buffer on theassociated terminal. The operating system provides the following writeI/O functions, which are listed with their function codes:

• IO$_WRITEVBLK---Write virtual block
• IO$_WRITELBLK---Write logical block
• IO$_WRITEPBLK---Write physical block

The write function codes can take the following device- orfunction-dependent arguments:

• P1---The starting virtual address of the buffer that is to be written to the terminal.
• P2---The number of bytes that are to be written to the terminal. (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.)
• P4---Carriage control specifier except for write physical block operations. (Write function carriage control is described in Section 5.4.2.2.)

P3, P5, and P6 are not meaningful for terminal write operations.

In write virtual block and write logical block operations, the buffer(P1 and P2) is formatted for the selected terminal and includes thecarriage control information specified by P4.

Unless TT$M_MECHFORM is specified, multiple line feeds are generatedfor form feeds. The number of line feeds generated depends on thecurrent page position and the length of the page. By producing acarriagereturn after the last line feed, a form feed also moves the cursor tothe left margin. Multiple spaces are generated for tabs if thecharacteristics of the selected terminal do not include TT$M_MECHTAB(this does not apply to write physical block operations). Tab stopsoccur every eight characters or positions.

CTDRIVER and Buffered Output

CTDRIVER, a component of the SET HOST facility, buffers output fromremote terminals in order to package multiple output requests into asingle network transfer. As a result, control is returned early to theuser with a status of SS$_NORMAL when the output buffer has been filledand successfully queued.

Note that this output might not be displayed if the user enters anabort character or a Ctrl/O.

5.4.2.1 Function Modifier Codes for Write QIO Functions

Five function modifiers can be specified with IO$_WRITEVBLK,IO$_WRITELBLK, and IO$_WRITEPBLK. Table 5-9 lists these functionmodifiers. All write function modifiers are supported for LAT devices.

The P4 argument is a longword that specifies carriage control. Carriagecontrol determines the next printing position on the terminal.P4 is ignored in a write physical block operation. Figure 5-5 showsthe P4 longword format.

Figure 5-5 P4 Carriage Control Specifier

Only bytes 0, 2, and 3 in the longword are used. Byte 1 is ignored. Ifthe low-order byte (byte 0) is not 0, the contents of the longword areinterpreted as a Fortran carriage control specifier. Table 5-10lists the possible byte 0 values (in hexadecimal) and their meanings.

If the low-order byte (byte 0) is 0, bytes 2 and 3 of the P4 longwordare interpreted as the prefix and postfix carriage control specifiers.The prefix (byte 2) specifies the carriage control before the buffercontents are printed. The postfix (byte 3) specifies the carriagecontrol after the buffer contents are printed. The sequence is asfollows:

1. Prefix carriage control
2. Print
3. Postfix carriage control

The prefix and postfix bytes, although interpreted separately, use thesame encoding scheme. Table 5-11 shows this encoding scheme inhexadecimal.

With several exceptions, Figure 5-6 shows the prefix and postfixhexadecimal coding that produces the carriage control functions listedin Table 5-10. Prefix and postfix coding provides an alternative wayto achieve these controls.

In the first example in Figure 5-6, the prefix/postfix hexadecimalcoding for a single-space carriage control (carriage-return/line-feedcombination, print buffer contents, return) is obtained by placing thevalue 1 in the second (prefix) byte and the sum of the bit 7 value (80)and the return value (D) in the third postfix byte.

 80  (bit 7 = 1)+ D  (return)---- 8D  (postfix = return)

Set mode operations affect the operation and characteristics of theassociated terminal line. The operating system provides two types ofset mode functions: set mode and set characteristics.

The set mode function affects the mode and temporary characteristics ofthe associated terminal line. Set mode is a logical I/O function andrequires no privilege. (If you do not have LOG_IO or PHY_IO privilege,the terminal driver does not accept a set mode request to a terminalthat does not have the extended terminal characteristicTT2$M_SETSPEED---even if no request for a change of speed is made.Privilege is not required if TT2$M_SETSPEED is set but no attempt tochange the speed is made.) The following function code is provided:

IO$_SETMODE

The set characteristics function affects the permanent characteristicsof the associated terminal line. Set characteristics is a physical I/Ofunction and requires the privilege necessary to perform physical I/O.The following function code is provided:

IO$_SETCHAR

Figure 5-6 Write Function Carriage Control (Prefix and PostfixCoding)

The set mode and set characteristics functions take the followingdevice- or function-dependent arguments if no function modifiers arespecified:

• P1---Address of characteristics buffer
• P2---Length of characteristics buffer (default length is 8 bytes)
• P3---Speed specifier (bits 0 through 7 = transmit; 8 through 15 = receive)
• P4---Fill specifier (bits 0 through 7 = CR fill count; bits 8 through 15 = LF fill count)
• P5---Parity flags

The P1 argument points to a variable-length block, as shown inFigure 5-7. With the exception of terminal characteristics, thecontents of the block are the same for both the set mode and setcharacteristics functions.

Figure 5-7 Set Mode and Set Characteristics Buffers

In the buffer, the device class is DC$_TERM, which is defined by the$DCDEF macro. The terminal type is defined by the $TTDEF macro; forexample, TT$_LA36. The page width is a value in the range of 1 through511. The page length is a value in the range of 0 through 255.Table 5-5 lists the values forterminal characteristics. Table 5-6 lists the extended terminalcharacteristics. Characteristics values are defined by the $TTDEF and$TT2DEF macros.

The P3 argument defines the device speed, such as TT$C_BAUD_300. Thelow eight bits specify the transmit speed, and the high eight bitsspecify the receive speed. If no receivespeed is specified, the indicated transmit speed is used for bothtransmitting and receiving. If neither the transmit nor the receivespeed is specified (P3 = 0), the baud rate is not changed. The terminaldriver ignores the receive speed bits for interfaces that do notsupport split-speed operation. While speeds up to 19.2 K baud can bespecified, not all controllers support all speed combinations. Refer tothe associated hardware documentation to determine which speeds aresupported by your controller.

P4 contains fill counts for the carriage-return and line-feedcharacters. Bits 0 through 7 specify the number of fill characters usedafter a carriage return. Bits 8 through 15 specify the number of fillcharacters used after a line feed.

P4 is applicable only if TT$M_CRFILL or TT$M_LFFILL is specified as aterminal characteristic for the current QIO request; see Table 5-5.

Several parity flags can be specified in the P5 argument:

• TT$M_ALTRPAR---Alter parity. If set, check the state of TT$M_PARITY and TT$M_ODD and, if indicated, change the parity. Otherwise, ignore these bits.
• TT$M_PARITY---Enable parity on terminal line if set, disable if clear.
• TT$M_ODD---Parity is odd if set.
• TT$M_ALTDISPAR---Alter dismiss parity errors. If set, check the state of TT$M_DISPARERR.
• TT$M_DISPARERR---Dismiss parity errors. If this mode is set, a character with a parity error is passed to the reader. An error message is not reported.

  Note If parity is enabled, the DZ11 generates a parity check bit to detectparity mismatch. Unless TT$M_DISPARERR is enabled, parity errors thatoccur during an I/O read operation are fatal to the operation. Parityerrors that occur on input characters (that is, keys pressed on thekeyboard) when no I/O operation is in progress might result in acharacter loss.

• TT$M_BREAK---Generate a break if set. The break is in effect until this bit is turned off. TT$M_BREAK is supported by the LTDRIVER for terminal servers that support the break capability, such as the DECserver 200 and DECserver 500. However, in the case of LAT terminals, the terminal server controls the duration of the break.
• TT$M_ALTFRAME---If set, the four low-order bits of P5 become the frame size. Note that the frame size is for data bits only and is exclusive of parity. TT$M_ALTFRAME is supported for frame sizes of 7 and 8 for LAT devices.

To take the existing parity settings, modify them, and use them in theset mode or set characteristic function, move the byte starting at thesecond nibble of the buffer that is going to be used in the P5argument. For example, the following instructions change the parityfrom even to odd:

insv    iosb+6, #4, #8, flagsbisl    #tt$m_altrpar!tt$m_odd!tt$m_parity, flags

The following instruction then resets the parity to its original state:

bicl    #tt$m_odd!tt$m_parity, flags

See Section 5.2.5 for information about the SET TERMINAL/FRAME command.

Application programs that change terminal characteristicsshould perform the following steps:

1. Use the IO$_SENSEMODE function to read the current characteristics.
2. Modify the characteristics.
3. Use the set mode function to write back the results.
4. If the characteristic is intended to be reset when the image exits, the application must perform this operation.

Failure to follow this sequence will result in clearing any previouslyset characteristic.

Two stop bits are used only for data rates less than or equal to 150baud; higher data rates default to one stop bit.

The set mode and set characteristics functions can take the enableCtrl/C AST, enable Ctrl/Y AST, enable out-of-band AST, hangup, setmodem, broadcast, and loopback function modifiers that are described inthe following sections.

The hangup function disconnects a terminal that is on adialup line. (Dialup lines are described in Section 5.2.3.) Thefollowing combinations of function code and modifier are provided:

• IO$_SETMODE!IO$M_HANGUP
• IO$_SETCHAR!IO$M_HANGUP

The hangup function modifier takes no arguments. SS$_NORMAL is returnedin the I/O status block.

Both set mode functions cantake the enable Ctrl/C AST and enable Ctrl/Y AST function modifiers.These function modifiers request the terminal driver to queue an ASTfor the requesting process when you press Ctrl/C or Ctrl/Y. Thefollowing combinations of function code and modifier are provided:

• IO$_SETMODE!IO$M_CTRLCAST---Enable Ctrl/C AST
• IO$_SETMODE!IO$M_CTRLYAST---Enable Ctrl/Y AST

These function code modifier pairs take the following device- orfunction-dependent arguments:

P1---Address of the AST service or 0 if the corresponding AST is disabled
P2---AST parameter
P3---Access mode to deliver AST (maximized with caller's access mode)

If the respective enabling is in effect, pressing Ctrl/C or Ctrl/Y gains the attention of the enabling process (see Table 5-2).

Enable Ctrl/C and Ctrl/Y AST are one-time enabling function modifiers. After the AST occurs, it must be explicitly reenabled by one of the two function code combinations before an AST can occur again. This function code is also used to disable the AST. The function is subject to AST quotas.

You can have more than one Ctrl/C or Ctrl/Y enabled; pressing Ctrl/C,for example, results in the delivery of all Ctrl/C ASTs. ASTs arequeued and delivered to the user process on a first-in/first-out basisfor each access mode. However, ASTs are processed in the reverse orderof the Ctrl/C AST or Ctrl/Y AST requests that have been issued to theterminal driver (on a last-in/first-out basis).

If no enable Ctrl/C AST is present, the holder of an enable Ctrl/Y ASTreceives an AST when Ctrl/C is pressed; carriage-return/line-feedcombination, ^Y, and Return are echoed.

Figure 5-8 shows the relationship of Ctrl/C and Ctrl/Y with theout-of-band function. If Ctrl/C or Ctrl/Y is an enabled out-of-bandcharacter, any out-of-band ASTs specified for this character aredelivered. If IO$M_INCLUDE function modifier is included in theout-of-band AST request for this character, an enabled Ctrl/C or Ctrl/YAST is also delivered.

Figure 5-8 Relationship of Out-of-Band Function with ControlCharacters

Enable Ctrl/C AST requests are flushed by the Cancel I/O on the Channel($CANCEL) system service. Enable Ctrl/Y AST requests are flushed by theDeassign I/O Channel ($DASSGN) system service.

Ctrl/Y is normally used to gain the attention of the commandinterpreter and to input special commands such as DEBUG, STOP, andCONTINUE. Programs that are run from a command interpreter should notenable Ctrl/Y. Because ASTs are delivered on a first-in/first-outbasis, the command interpreter's AST routine gets control first, andmight not allow the program's AST to be delivered at all. Programs thatrequire the use of Ctrl/Y should use the LIB$DISABLE_CTRL RTL routineto disable DCL recognition of Ctrl/Y.

Section 5.2.1.2 describes other effects of Ctrl/C and Ctrl/Y.