Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

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 of the 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. 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:

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

#### 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 is written 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.

### Description

> SMG$READ_COMPOSED_LINE reads a line composed of normal keystrokes and key equivalence strings as defined in the specified key definition table. Attributes of the key definition control whether the equivalence string is echoed and whether the read terminates with the defined keystroke. Normal keystrokes are always echoed.

> A carriage return always terminates the read operation. If Ctrl/Z is pressed and there is no definition for Ctrl/Z in the key definition table, "EXIT" is echoed and the read is terminated. If Ctrl/Z was the first character on the line, SMG$_EOF is returned. Otherwise, SMG$_EOF is returned on the next read operation. SMG$_EOF is also returned if OpenVMS RMS is used for the input operation and RMS returns RMS$_EOF. No other terminators are recognized except those specified as attributes in a key definition.

> If the arrow keys and Ctrl/B are not defined, the previous lines read with the SMG$READ_xxxx routines can be recalled using the arrow keys. The number of lines saved for later recall depends upon the recall-size argument in SMG$CREATE_VIRTUAL_KEYBOARD. The default is 20 lines.

> Note that SMG$READ_COMPOSED_LINE calls the SMG$FLUSH_BUFFER routine before performing the input operation. This ensures that the screen image is up to date at the time of the input operation. Display batching for both the pasteboard and virtual display must be off when you use SMG$READ_COMPOSED_LINE.

### 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$_INVCOL | Invalid column. The read operation attempts to use a column outside the virtual display.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVKBD_ID | Invalid keyboard-id.
> SMG$_INVKTB_ID | Invalid key-table-id.
> 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.

## SMG$READ_FROM_DISPLAY

> The Read Text from Display routine reads a line of text from a virtual display.

### Format

> SMG$READ_FROM_DISPLAY display-id ,resultant-string [,terminator-string] [,start-row] [,rendition-string]

### RETURNS

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

### Arguments

> #### display-id

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

> Specifies the virtual display from which text is read. The display-id argument is the address of an unsigned longword that contains the display identifier.

> The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

> #### resultant-string

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

> String into which SMG$READ_FROM_DISPLAY writes the information read from the virtual display. The resultant-string argument is the address of a descriptor pointing to the string into which the string is written.

> #### terminator-string

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

> String containing a terminator or terminators that end the backward search, thus determining the starting position of the returned string. The terminator-string argument is the address of a descriptor pointing to the string of terminators. If terminator-string is omitted, no back searching is performed; the returned string starts with the character at the current cursor position.

> #### start-row

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

> The start-row argument is the address of a signed longword that contains the row of the virtual display to read from. This is an optional argument.

> #### rendition-string

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

> Optional bit mask string that controls the video attributes. The rendition-string argument is the address of a descriptor pointing to the bit mask string. Each attribute set causes the corresponding attribute to be set for the corresponding byte in the text string in the display. The following attributes can be specified for each byte using the rendition-string 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.

### Description

> SMG$READ_FROM_DISPLAY returns a string that contains some or all of the text on the current line of the specified virtual display. If the terminator-string argument is omitted, the contents of the current line (from the current column position to the rightmost column position) are returned. If the start-row argument is passed, the contents of line start-row from column 1 to the rightmost column are returned in resultant-string. If the start-row argument is passed, the terminator-string argument is ignored.

> If you specify terminator-string, each character in it serves as a terminator for back searching; that is, the process of determining the first character position to be returned. If none of the specified terminators is encountered, the search is terminated at the first character position on the line.

> Device-independent characters (plus sign [+], minus sign [-], and vertical bar [|]) are returned for drawn lines.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_DSPIN_USE | An SMG$ call was made from an AST routine that interrupted an SMG$ call on the same display.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_KBDIN_USE | On a second or subsequent read operation, multiple QIOs were attempted on the same channel.
> LIB$_INVSTRDES | Invalid string descriptor.
> LIB$_INSVIRMEM | Insufficient virtual memory.

### Example

    C+
    C This Fortran example demonstrates the use of SMG$READ_FROM_DISPLAY.
    C-

    C+
    C Include the SMG definitions. In particular, we want SMG$M_BORDER.
    C-

            IMPLICIT INTEGER (A-Z)
            INCLUDE '($SMGDEF)'
            CHARACTER*80 TEXT

    C+
    C Use SMG$CREATE_VIRTUAL_DISPLAY to create the virtual display
    C and give it a border.
    C-

            ROWS = 5
            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 by calling SMG$CREATE_PASTEBOARD.
    C-

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

    C+
    C Call SMG$PASTE_VIRTUAL_DISPLAY and SMG$PUT_LINE to paste
    C the virtual display and put some text on line 2.
    C-

            STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 2, 10 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

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

            STATUS = SMG$PUT_LINE ( DISPLAY1,
         1          'This is an example of using SMG$READ_FROM_DISPLAY.' )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Use SMG$READ_FROM_DISPLAY to read line 2 from the virtual
    C display, starting at column 22.
    C-

            STATUS = SMG$SET_CURSOR_ABS ( DISPLAY1, 2, 22 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Search line 2 from column 22 to column 1 for the null string.
    C Since no terminator will be supplied, no "back-searching" will take
    C place. TEXT will be assigned the "value" of the line from
    C column 22 to the rightmost column.
    C-

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

    C+
    C Put the line of text found into the virtual display at row 4,
    C column 10 by calling SMG$SET_CURSOR_ABS and SMG$PUT_LINE.
    C-

            STATUS = SMG$SET_CURSOR_ABS ( DISPLAY1, 4, 10 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

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

    C+
    C Use SMG$SET_CURSOR_ABS to set the cursor back to line 2, column 22.
    C-

            STATUS = SMG$SET_CURSOR_ABS ( DISPLAY1, 2, 22 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Use SMG$READ_FROM_DISPLAY to search line 2 from column 22 to
    C column 1 for an "f".  Now, "back-searching" will take place.
    C Starting at column 22, "back-track" to column 1 looking for "f".
    C Text will then be assigned the "value" of the line from the
    C present cursor position (where the "f" is, to the rightmost
    C column).
    C-

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

    C+
    C Put the line of text found into the virtual display at row 4, column 10.
    C-

            STATUS = SMG$SET_CURSOR_ABS ( DISPLAY1, 5, 10 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

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

            END

> The output generated by this Fortran program is shown in Figure SMG-36.

> Figure SMG-36 Output Generated by Fortran Program Calling SMG$READ_FROM_DISPLAY

## SMG$READ_KEYSTROKE

> The Read a Single Character routine reads a keystroke and returns that keystroke's terminator code.

### Format

> SMG$READ_KEYSTROKE keyboard-id ,word-terminator-code [,prompt-string] [,timeout] [,display-id] [,rendition-set] [,rendition-complement]

### 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 an unsigned longword containing the identifier of the virtual keyboard from which to read.

> You can create a virtual keyboard by calling the SMG$CREATE_VIRTUAL_KEYBOARD routine.

> #### 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 is written 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.

> #### prompt-string

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

> Prompt string. The prompt-string argument is an optional string used as the prompt for the read operation.

> #### timeout

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

> Timeout count. The timeout argument is optional. If specified, any character typed before the timeout is returned in the buffer.

> #### 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 the optional prompt-string argument is specified while there are multiple virtual displays pasted, the display-id argument is required to determine in which virtual display the prompt string will be written. If the prompt-string argument is not specified, do not specify the display-id argument.

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

> #### 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_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 of the 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. 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:

> 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

### Description

> SMG$READ_KEYSTROKE reads a keystroke from the specified virtual keyboard and returns the terminator code of that keystroke in the form SMG$K_TRM_keyname. The keystroke entered to be read is not echoed on the screen. This keystroke can be any standard alphabetic character, any keypad or function key, or one of the directional arrows.

> 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, VT300 series, VT400 series, and VT500 series keyboards with the following exceptions:

> - The Compose Character key on VT200 series, VT300 series, VT400 series, and VT500 series keyboards. (The VT100 has no Compose Character key.)
> - The Escape key.
> - The Shift keys.
> - The keys F1 through F5 on VT200 series, VT300 series, VT400 series, and VT500 series keyboards. (The VT100 does not have keys F1 through F5.)

> There are certain keys and key definitions that Compaq strongly suggests you avoid defining. 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.

> Warning Compaq recommends that you not use these special terminal settings. The settings can 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$_KBDIN_USE | On a second or subsequent read operation, multiple QIOs were attempted on the same channel.
> 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

#1
    C+
    C This 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

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 5935PRO_030.HTML