Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

#### terminator-string

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

Characters that terminate I/O. The optional terminator-string argument is the address of a descriptor pointing to the character string containing the terminating characters. The terminator-string argument returns the actual terminating characters, not the key that was pressed to terminate the I/O.

### 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
    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

#2
    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

## SMG$READ_VERIFY

> 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 system symbol libraries supplied by Compaq. 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.

Previous | Next | Contents | Index

| privacy and legal statement |
5935PRO_032.HTML