[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

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


Previous Contents

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 in Chapter 3.

character-set


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

Optional character-set is the address of an unsigned longword containing the character set of characters to be input. If this argument is omitted, the default character set of the specified virtual display is used. If no virtual display is used, the default character set indicated by the SMG$DEFAULT_CHARACTER_SET logical name is used.

Valid values for this argument are :

Value Character Set
SMG$C_ASCII ASCII
SMG$C_SPEC_GRAPHICS DEC Special Graphics
SMG$C_HANGUL DEC Hangul

1One of DEC supplemental character set and Latin-1 character set.

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_COMPOSED_LINE reads a line composed of normal keystrokes and key equivalence strings as defined in the specified key 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 typed 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 typed on the line, SMG$_EOF is returned. Otherwise, SMG$_EOF is returned on the next read operation. 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$_INVARG Invalid argument.
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$_WRONUMARG Wrong number of arguments.

Any condition values returned by LIB$COPY_R_DX.

Any condition values returned by $GET (except RMS$_EOF).

Any condition values returned by $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] [,character-set-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.

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

charcter-set-string


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

Optional byte string that shows character set. The charcter-set-string argument is the address of a descriptor pointing to the charcter set string. Each byte shows the corresponding character set for corresponding byte in the text string in the display. The following values can be returned for each byte specified with character-set-string argument:
Value Character Set
SMG$C_ASCII ASCII
SMG$C_SPEC_GRAPHICS DEC Special Graphics
SMG$C_HANGUL DEC Hangul
SMG$C_UNKNOWN Unknown character set

1One of DEC supplemental character set and Latin-1 character set.


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 current column position is the right portion of a Korean character, unknown character is returned for the position. 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 (+, --, |) are returned for drawn lines.


Condition Values Returned

SS$_NORMAL Normal successful completion.
SMG$_INVDIS_ID Invalid display-id.
LIB$_INVSTRDES Invalid string descriptor.
LIB$_INSVIRMEM Insufficient virtual memory.

Example


C+
C This DEC 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 in Chapter 3.

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 may be any standard alphabetic character, any keypad or function key, or one of the directional arrows.


Previous Next Contents