[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

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:

There are certain keys and key definitions that Digital 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:

Warning

Digital 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

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5935PRO_030.HTML