HP OpenVMS Systems Documentation
OpenVMS I/O User's Reference Manual
188.8.131.52 Read Verify Function
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.
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, 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.
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.
1Any interruption caused by the execution of the $BRDCST orthe $BRKTHRU system service broadcasting messages to terminals isreferred to as a "write breakthrough."
184.108.40.206 Write Function Carriage Control
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.
1A carriage-return/line-feed combination is a carriagereturn followed by a line feed.
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:
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.
5.4.3 Set Mode
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:
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:
Figure 5-6 Write Function Carriage Control (Prefix and PostfixCoding)
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.
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:
The following instruction then resets the parity to its original state:
See Section 5.2.5 for information about the SET TERMINAL/FRAME command.
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.
220.127.116.11 Hangup Function Modifier
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:
The hangup function modifier takes no arguments. SS$_NORMAL is returnedin the I/O status block.
18.104.22.168 Enable Ctrl/C AST and Enable Ctrl/Y AST Function Modifiers
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:
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
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 22.214.171.124 describes other effects of Ctrl/C and Ctrl/Y.