HP OpenVMS Systems Documentation

OpenVMS/Hangul RTL Korean Screen Management (SMG$) Manual

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

You can enter all keys on the VT100, VT200-series, and VT300-series keyboards with the following exceptions:

• The Compose Character key on VT200-series and VT300-series keyboards
• The ESCAPE key
• The SHIFT keys
• The keys F1 through F5 on VT200-series and VT300-series keyboards

There are some keys and key definitions you can define, but Digital strongly suggests you avoid defining them. SMG$ does not return an error when you use these keys and key definitions, but the definitions you assign to these key combinations are not executed unless you set your terminal in the following special ways at the DCL level:

• Ctrl/C, Ctrl/O, Ctrl/X, and F6 --- To read these keys, you must first enter the DCL command SET TERMINAL/PASTHRU.
• Ctrl/T, Ctrl/Y --- To read these keys, you must first enter either the DCL command SET TERMINAL/PASTHRU or SET NOCONTROL, or both.
• Ctrl/S, Ctrl/Q --- To read these keys, you must first enter the DCL command SET TERMINAL/NOTTSYNC.

Digital does not recommend that you use these special terminal settings. The settings may cause unpredictable results if you do not understand all the implications of changing the default settings to give control to the terminal driver.

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).
SS$_xxx	Any error from $QIOW.
SMG$_EOF	End of file.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_INVKBD_ID	Invalid keyboard-id.
SMG$_WRONUMARG	Wrong number of arguments.
LIB$_xxx	Any error from LIB$SCOPY_R_DX.
RMS$_xxx	Any error from $GET (except RMS$_EOF).

Examples

C+
C This DEC Fortran example program demonstrates the use of
C SMG$READ_KEYSTROKE.
C-

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 First, include the SMG definitions. In particular, we want SMG$M_BORDER.
C-

        IMPLICIT INTEGER (A-Z)
        INCLUDE '($SMGDEF)'
        CHARACTER*3 TEXT
        CHARACTER*27 TEXT_OUTPUT

C+
C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual
C display with a border.
C-

        ROWS = 7
        COLUMNS = 60

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Create the pasteboard using SMG$CREATE_PASTEBOARD.
C-

        STATUS = SMG$CREATE_PASTEBOARD ( PASTE1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$CREATE_VIRTUAL_KEYBOARD to create a virtual keyboard.
C-

        STATUS = SMG$CREATE_VIRTUAL_KEYBOARD ( KEYBOARD1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Using SMG$PASTE_VIRTUAL_DISPLAY, 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))

        STATUS = SMG$PUT_LINE ( DISPLAY1,
     1          'Enter the character K after the >> prompt.' )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_LINE ( DISPLAY1,
     1          'This character will not be echoed as you type it.' )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_LINE ( DISPLAY1,
     1  'The terminal character equivalent of K is displayed.' )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_LINE ( DISPLAY1, ' ' )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$READ_KEYSTROKE to read a keystroke from the virtual
C pasteboard.
C-

        STATUS = SMG$READ_KEYSTROKE ( KEYBOARD1, TERM_CHAR, '>>', ,
     1          DISPLAY1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_LINE ( DISPLAY1, ' ' )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use OTS$CVT_L_TI to convert the decimal value of TERM_CHAR to
C a decimal ASCII text string.
C-

        STATUS = OTS$CVT_L_TI ( TERM_CHAR, TEXT )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        TEXT_OUTPUT = ' TERMINAL CHARACTER IS: ' // TEXT

C+
C Call SMG$PUT_LINE and SMG$PUT_CHARS to print the decimal
C ASCII text string.
C-

        STATUS = SMG$PUT_LINE ( DISPLAY1, TEXT_OUTPUT )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1, TEXT, 7, 25 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END


      

The output generated by this FORTRAN program is shown in Figure SMG-37.

Figure SMG-37 Output Generated by FORTRAN Program Calling SMG$READ_KEYSTROKE

1       OPTION TYPE=EXPLICIT

        !+
        ! This VAX BASIC program demonstrates the use of
        ! SMG$READ_KEYSTROKE to read a keystroke from the terminal.
        !

        DECLARE LONG kb_id, ret_status, term_code, I, timer
        EXTERNAL SUB LIB$SIGNAL( LONG BY VALUE )
        EXTERNAL SUB LIB$STOP( LONG BY VALUE )
        EXTERNAL LONG CONSTANT SS$_TIMEOUT

        %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

        EXTERNAL LONG FUNCTION SMG$CREATE_VIRTUAL_KEYBOARD( LONG, STRING )
        EXTERNAL LONG FUNCTION SMG$DELETE_VIRTUAL_KEYBOARD( LONG )
        EXTERNAL LONG FUNCTION SMG$READ_KEYSTROKE( LONG, LONG, STRING, &
            LONG, LONG )


        !+
        ! 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 typeahead buffer):  ";timer

        !+
        ! 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

        !+
        !   Read a keystoke, tell the user what we found.
        !-

        ret_status = SMG$READ_KEYSTROKE( kb_id, term_code, , timer, )
        IF (ret_status <> SS$_TIMEOUT) AND ((ret_status AND 1%) = 0%) THEN
            CALL LIB$SIGNAL( ret_status )
        END IF

        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_FIND TO SMG$K_TRM_NEXT_SCREEN
                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 program reads a key and returns the word-terminator-code and the name of the keystroke entered. One sample of the commands entered and the output generated by this program is as follows:

$ RUN READ_KEY Enter the timer value (0 to read type-ahead buffer): ? 9 term_code = 100 You typed: d

Note that in this example, the user entered the keystroke "d" following the first prompt. The keystroke entered was not echoed.

The Read String routine reads a string from a virtual keyboard.

Format

SMG$READ_STRING keyboard-id ,resultant-string [,prompt-string] [,maximum-length] [,modifiers] [,timeout] [,terminator-set] [,resultant-length] [,word-terminator-code] [,display-id] [,initial-string] [,rendition-set] [,rendition-complement] [,terminator-string] [,character-set]

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

Specifies the virtual keyboard from which input is to be read. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier.

Keyboard-id is returned by SMG$CREATE_VIRTUAL_KEYBOARD.

resultant-string

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

String into which the input line is written. The resultant-string argument is the address of a descriptor pointing to the string into which the text is written.

prompt-string

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

String used to prompt for the read operation. The prompt-string argument is the address of a descriptor pointing to the prompt string.

maximum-length

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

Specifies the maximum number of bytes to be read. The maximum-length argument is the address of a signed longword that contains the maximum number of bytes to be read. The maximum valid value for this argument is 512. If omitted, 512 is the default.

Note that as a result of truncation, the return string may be one byte shorter than maximum-length when the last byte is the left portion of Korean character.

modifiers

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

Optional bit mask that specifies optional behavior. The modifiers argument is the address of an unsigned longword that contains the flag.

Valid values for modifiers are as follows:

TRM$M_TM_CVTLOW	Converts lowercase characters to uppercase. Only valid for ASCII and supplemental character set.
TRM$M_TM_NOECHO	Characters entered are not echoed on the screen.
TRM$M_TM_PURGE	Type-ahead buffer purged before read is done.
TRM$M_TM_TRMNOECHO	Terminator is not echoed.
TRM$M_TM_NOEDIT	Advanced editing is disabled.
TRM$M_TM_NORECALL	Line recall is disabled.

The TRM$ symbols are defined by the $TRMDEF macro/module in Digital-supplied system symbol libraries.

timeout

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

Specifies the number of seconds allowed between the time the prompt is issued and the completion of the input operation. The timeout argument is the address of a signed longword that contains the timeout value.

If timeout is specified, all characters typed before the expiration time or until a terminate key is entered are returned in resultant-string. If omitted, the input operation remains active until a terminator is typed.

terminator-set

OpenVMS usage	unspecified
type	unspecified
access	read only
mechanism	by descriptor, fixed length

Either a mask that specifies which characters are to be treated as terminators (short form) or a descriptor pointing to such a mask (long form). The terminator-set argument is the address of a descriptor pointing to the mask.

If you want to use terminators with ASCII values in the range 0 to 31, use the short form, which consists of two longwords. The first longword is zero, and the second longword is a terminator character bit mask. You create this mask by setting the bit that corresponds to the ASCII value of the desired terminator. For example, to specify that Ctrl/A (ASCII value 1) is a terminator, you set bit 1 in the terminator-set mask.

If you want to use terminators with ASCII values outside the range 0 to 31, use the long form. First create a descriptor of this form:

The mask itself has the same format as that of the short form; however, the long form allows the use of a more comprehensive set of terminator characters. For example, a mask size of 16 bytes allows any 7-bit ASCII character to be set as a terminator, while a mask size of 32 bytes allows any 8-bit character to be set as a terminator. Any mask size between 1 and 32 bytes is acceptable.

If the terminator mask is all zeros, there are no specified terminators. In that case, the read terminates when the number of bytes specified in maximum-length has been transferred or when timeout is reached.

If the terminator-set argument is omitted, the set of terminators is the OpenVMS default terminator set.

resultant-length

word-terminator-code

display-id

If you are using the Screen Management Facility input and output routines, this argument specifies the virtual display in which the input is to occur. The virtual display specified must be pasted to the same pasteboard as specified by keyboard-id and must not be occluded. 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 display-id is omitted, the read begins in the current physical cursor position. Note that the length of the prompt-string plus the key entered is limited to the number of visible columns in the display.

initial-string

rendition-set

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

rendition-complement

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 following transformations:

terminator-string

character-set

Valid values for character-set are as follows:

Refer to Table 2-1 in Section 2.2.14 for the valid definitions of the SMG$DEFAULT_CHARACTER_SET logical name.

Description

SMG$READ_STRING returns a string of characters read from a virtual keyboard. 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 argument.
SMG$_INVCOL	Invalid column. The input occurs outside the virtual display.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_INVKBD_ID	Invalid keyboard-id.
SMG$_INVKTB_ID	Invalid key-table-id.
SMG$_INVMAXLEN	Maximum length specified was greater than 512.
SMG$_WRONUMARG	Wrong number of arguments.