Document revision date: 19 July 1999

terminator-string

Description

SMG$READ_STRING returns a string of characters read from a virtual display. Note that display batching for both the pasteboard and the virtual display must be off when you use SMG$READ_STRING.

The text read by SMG$READ_STRING is saved for later recall with SMG$READ_COMPOSED_LINE. Rendition applies to both the prompt (if there is one) and echoing of input characters.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SS$_ABORT	I/O operation aborted during execution (by SMG$CANCEL_INPUT).
SS$_CANCEL	I/O operation canceled while queued (by SMG$CANCEL_INPUT).
SMG$_EOF	End of file.
SMG$_ILLBATFNC	Input not allowed from a batched display.
SMG$_INVARG	Invalid value for display-id was specified.
SMG$_INVCOL	Invalid column. The input occurs outside the virtual display.
SMG$_INVKBD_ID	Invalid keyboard-id.
SMG$_INVKTB_ID	Invalid key-table-id.
SMG$_INVMAXLEN	Maximum length specified was greater than 512.
SMG$_KBDIN_USE	On a second or subsequent read operation, multiple QIOs were attempted on the same channel.
SMG$_WRONUMARG	Wrong number of arguments.

Any condition values returned by LIB$SCOPY_R_DX, $GET (except RMS$_EOF), or $QIOW.

Examples

1       OPTION TYPE=EXPLICIT 
 
        !+ 
        ! This VAX BASIC program demonstrates the use of 
        ! SMG$READ_STRING to read either a string, 
        ! a control key, or a keypad key. 
        ! 
 
        DECLARE LONG KB_ID, RET_STATUS, STR_LEN, TERM_CODE, MODIFIER, I, TIMER 
        DECLARE STRING DATA_STR, TERM_SET 
        EXTERNAL LONG CONSTANT IO$M_TIMED 
        EXTERNAL LONG CONSTANT IO$M_NOECHO 
        EXTERNAL LONG CONSTANT IO$M_NOFILTR 
        EXTERNAL SUB LIB$SIGNAL( LONG BY VALUE ) 
        EXTERNAL SUB LIB$STOP( LONG BY VALUE ) 
        EXTERNAL LONG CONSTANT SS$_TIMEOUT 
        EXTERNAL LONG FUNCTION SMG$CREATE_VIRTUAL_KEYBOARD( LONG, STRING ) 
        EXTERNAL LONG FUNCTION SMG$DELETE_VIRTUAL_KEYBOARD( LONG ) 
        EXTERNAL LONG FUNCTION SMG$READ_STRING( LONG, STRING, STRING, & 
            LONG, LONG, LONG, STRING, LONG, LONG ) 
        %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET" 
 
        !+ 
        ! Prompt the user for the timer value.  A value of 0 will cause 
        ! the type-ahead buffer to be read. 
        !- 
 
        INPUT "Enter timer value (0 to read type-ahead buffer):  ";TIMER 
 
        !+ 
        ! Tell SMG to use the timer value 
        !- 
 
        MODIFIER = IO$M_TIMED 
 
        !+ 
        ! Establish a SMG connection to SYS$INPUT.  Signal any unexpected 
        ! errors. 
        !- 
 
        RET_STATUS = SMG$CREATE_VIRTUAL_KEYBOARD( KB_ID, "SYS$INPUT:" ) 
        IF (RET_STATUS AND 1%) = 0% THEN 
            CALL LIB$SIGNAL( RET_STATUS ) 
        END IF 
 
 
        !+ 
        ! Tell SMG to use any keystroke except a letter or number 
        ! as a terminator to the input and perform the read. 
        ! Signal any error except SS$_TIMEOUT 
        !- 
 
        TERM_SET = STRING$( 4%, -1% ) + STRING$(12%, 0%) 
        RET_STATUS = SMG$READ_STRING( KB_ID, DATA_STR, , ,  & 
                MODIFIER, TIMER, TERM_SET, & 
                STR_LEN, TERM_CODE ) 
        IF (RET_STATUS <> SS$_TIMEOUT) AND ((RET_STATUS AND 1%) = 0%) THEN 
            CALL LIB$SIGNAL( RET_STATUS ) 
        END IF 
 
        !+ 
        ! All the data should come back as a terminator code, since any 
        ! character can be a terminator. 
        !- 
 
        PRINT "data string = ";LEFT(DATA_STR, STR_LEN) 
        PRINT "term_code = ";TERM_CODE 
        SELECT TERM_CODE 
 
            CASE 0 TO 31 
                PRINT "You typed a control character" 
 
            CASE 32 TO 127 
                PRINT "You typed: ";CHR$(TERM_CODE) 
 
            CASE SMG$K_TRM_PF1 TO SMG$K_TRM_PERIOD 
                PRINT "You typed one of the keypad keys" 
 
            CASE SMG$K_TRM_UP TO SMG$K_TRM_RIGHT 
                PRINT "You typed one of the cursor positioning keys" 
 
            CASE SMG$K_TRM_F6 TO SMG$K_TRM_F20 
                PRINT "You typed one of the function keys" 
 
            CASE SMG$K_TRM_E1 TO SMG$K_TRM_E6 
                PRINT "You typed one of the editing keys" 
 
            CASE SMG$K_TRM_TIMEOUT 
                PRINT "You did not type a key fast enough" 
 
            CASE ELSE 
                PRINT "I'm not sure what key you typed" 
 
        END SELECT 
 
        !+ 
        ! Close the connection to SYS$INPUT, and signal any errors. 
        !- 
 
        RET_STATUS = SMG$DELETE_VIRTUAL_KEYBOARD( KB_ID ) 
        IF (RET_STATUS AND 1%) = 0% THEN 
            CALL LIB$SIGNAL( RET_STATUS ) 
        END IF 
 
        END 
 
 
      

This BASIC example program demonstrates the use of SMG$READ_STRING. One sample of the output generated by this program is as follows:

$ RUN READ_STRING Enter timer value (0 to read type-ahead buffer): ? 5 d data string = d term_code = 13 You typed a control character

C+ 
C This Fortran example program demonstrates how to use 
C SMG$READ_STRING. 
C 
C This routine creates a virtual display and writes it to the pasteboard. 
C Data is placed in the virtual display using SMG$PUT_CHARS. 
C- 
 
C+ 
C Include the SMG definitions. In particular, we want SMG$M_BORDER. 
C- 
 
        IMPLICIT INTEGER (A-Z) 
        INCLUDE '($SMGDEF)' 
        CHARACTER*20 TEXT 
 
C+ 
C Create a virtual display with a border using SMG$CREATE_VIRTUAL_DISPLAY. 
C- 
 
        ROWS = 7 
        COLUMNS = 50 
 
        STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Use SMG$CREATE_PASTEBOARD to create the pasteboard. 
C- 
 
        STATUS = SMG$CREATE_PASTEBOARD (PASTE1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Create a virtual keyboard by calling SMG$CREATE_VIRTUAL_KEYBOARD. 
C- 
 
        STATUS = SMG$CREATE_VIRTUAL_KEYBOARD ( KEYBOARD1 ) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Use SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display 
C at row 3, column 9. 
C- 
 
        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 3, 9 ) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Read a string from the virtual pasteboard using SMG$READ_STRING. 
C- 
 
        STATUS = SMG$READ_STRING ( KEYBOARD1, 
     1          TEXT, 'prompt', 20, , , , , , DISPLAY1 ) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        END 
 
 
 
      

The output generated by this Fortran program before the call to SMG$READ_STRING is shown in Figure SMG-38. The program is waiting for input. The cursor immediately follows the word "prompt."

Figure SMG-38 Output Generated Before the Call to SMG$READ_STRING

The output generated after the call to SMG$READ_STRING is shown in Figure SMG-39.

Figure SMG-39 Output Generated After the Call to SMG$READ_STRING

The Read and Verify a String routine reads a sequence of characters and verifies the sequence.

Format

SMG$READ_VERIFY keyboard-id ,resultant-string ,initial-string ,picture-string ,fill-character ,clear-character [,prompt-string] [,modifiers] [,timeout] [,placeholder-arg] [,initial-offset] [,word-terminator-code] [,display-id] [,alternate-echo-string] [,alternate-display-id] [,rendition-set] [,rendition-complement] [,input-length]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

keyboard-id

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Keyboard identifier. The keyboard-id argument is the address of an unsigned longword containing the identifier of the virtual keyboard from which to read.

The virtual keyboard is created by calling the SMG$CREATE_VIRTUAL_KEYBOARD routine.

resultant-string

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

Output string into which SMG$READ_VERIFY writes the characters that are read. The resultant-string argument is the address of a descriptor pointing to this output string.

initial-string

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Input string that contains the initial characters of the field. The initial-string argument is the address of a descriptor pointing to the input string.

picture-string

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

String that contains a picture of what the field is to look like. The picture-string argument is the address of a descriptor pointing to the picture string.

For more information on the legal values for the picture string, see the terminal driver section of the OpenVMS I/O User's Reference Manual.

fill-character

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Fill character. The fill-character argument is the address of a descriptor pointing to the string that contains the character to be used as a fill character in the initial-string argument.

clear-character

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Clear character. The clear-character argument is the address of a descriptor pointing to the string that contains the character to be displayed for each occurrence of fill-character in initial-string.

prompt-string

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Prompt string. The prompt-string argument is the address of a descriptor pointing to the string that SMG$READ_VERIFY uses as the prompt for the read operation. This is an optional argument.

modifiers

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Modifiers. The modifiers argument is a longword bit mask that specifies optional behavior. The bits defined are the same as for the $QIO item-list entry TRM$_MODIFIERS. This is an optional argument.

Valid values for modifiers are as follows:

TRM$M_TM_AUTO_TAB	Field is full when last character is entered.
TRM$M_TM_CVTLOW	Converts lowercase characters to uppercase characters.
TRM$M_TM_NOECHO	Characters entered are not echoed on the screen.
TRM$M_TM_NOEDIT	Advanced editing is disabled for this read operation.
TRM$M_TM_NORECALL	Line recall is disabled.
TRM$M_TM_PURGE	Type-ahead buffer is purged before read is begun.
TRM$M_TM_R_JUST	Input is right justified.
TRM$M_TM_TRMNOECHO	Termination character, if any, is not displayed.

The TRM$ symbols are defined by the $TRMDEF macro/module in Digital-supplied system symbol libraries. See the terminal driver section of the OpenVMS I/O User's Reference Manual for more information on modifiers for read operations.

timeout

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Timeout count. The timeout argument is the address of a signed longword that contains the timeout value. The timeout argument is optional. If timeout is specified, all characters typed in before the timeout or before a terminator is entered are returned in the buffer. If timeout is omitted, characters are returned in the buffer until a terminator is seen.

placeholder-arg

OpenVMS usage:	unspecified
type:	unspecified
access:	read only
mechanism:	unspecified

Placeholder argument. The OpenVMS terminal driver ignores this argument when performing a read-verify.

initial-offset

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Input string offset. The initial-offset argument is the address of a signed longword that contains the number of characters (from the initial-string argument) to output after the prompt before waiting for input.

word-terminator-code

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Key terminator code. The word-terminator-code argument is an unsigned word into which SMG$READ_VERIFY writes a code indicating what character or key terminated the read. Key terminator codes are of the form SMG$K_TRM_keyname. The key names are listed in Table 3-1.

display-id

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Display identifier. The optional display-id argument is the address of an unsigned longword that contains the identifier of the virtual display in which the read is to be performed.

If display-id is specified, SMG$READ_VERIFY begins the read at the current virtual cursor position in that virtual display. If omitted, the read begins in the current physical cursor position. You cannot accept input from an occluded area of the virtual display.

In the case of multiple virtual displays, each virtual display has an associated virtual cursor position. At the same time, there is a single physical cursor position corresponding to the current location of the physical cursor. If the display-id argument is specified, the read begins at the current virtual cursor position in the specified virtual display. If omitted, the read begins in the current physical cursor position. Note that the length of the prompt-string, the initial-offset, and the string entered is limited to the number of visible columns in the display.

alternate-echo-string

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Alternate echo string. The alternate-echo-string argument is a string that is printed after the first character is typed during the read operation. This is an optional argument.

alternate-display-id

OpenVMS usage:	identifier
type:	longword (signed)
access:	read only
mechanism:	by reference

Alternate display identifier. The alternate-display-id is a signed longword containing the identifier of the virtual display in which the alternate-echo-string argument is to be printed. This is an optional argument. If specified, the output begins at the current virtual cursor position in that virtual display. If omitted, the value of the display-id argument is used as the default. If display-id is not specified, the output begins in the current physical cursor position.

rendition-set

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINK	Displays blinking characters.
SMG$M_BOLD	Displays characters in higher-than-normal intensity.
SMG$M_REVERSE	Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINE	Displays underlined characters.
SMG$M_INVISIBLE	Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8	Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display in which the read is done. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the transformations shown in the following table.

Set	Complement	Action
0	0	Attribute set to default
1	0	Attribute on
0	1	Attribute set to complement of default setting
1	1	Attribute off

input-length

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Number of characters entered by the user. The input-length argument is the address of an unsigned word containing this number.

Description

SMG$READ_VERIFY reads a sequence of characters from the virtual keyboard specified and verifies the sequence against the picture string. It then returns characters read to the caller. The caller may also specify that a code indicating the terminator be returned. Rendition applies to both the prompt (if there is one) and echoing of input characters.

Note that display batching for both the pasteboard and the virtual display must be off when you use SMG$READ_VERIFY.

For additional information on read-verify operations and on use of the read-verify arguments, see the terminal driver section of the OpenVMS I/O User's Reference Manual.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SS$_ABORT	I/O operation aborted during execution (by SMG$CANCEL_INPUT).
SS$_CANCEL	I/O operation canceled while queued (by SMG$CANCEL_INPUT).
SMG$_DISREQ	A call to SMG$READ_VERIFY was made specifying right-justification; no display-id was specified, and the SCROLL_REVERSE sequence was not found for this terminal in TERMTABLE.EXE. Add the display-id argument to the SMG$READ_VERIFY call or add the SCROLL_REVERSE sequence to TERMTABLE.EXE.
SMG$_EOF	End of file.
SMG$_INVCOL	Invalid column specified.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_INVKBD_ID	Invalid keyboard-id.
SMG$_KBDIN_USE	On a second or subsequent read operation, multiple QIOs were attempted on the same channel.
SMG$_LENMUSONE	Length of fill-character and clear-character must be 1.
SMG$_LENNOTEQL	Length of picture-string and initial-string are not equal.
SMG$_WRONUMARG	Wrong number of arguments.
LIB$_ xxx	Any error from LIB$SCOPY_R_DX.
RMS$_ xxx	Any error from $GET (except RMS$_EOF).
SS$_ xxx	Any error from $QIOW.

	privacy and legal statement
5935PRO_032.HTML