HP OpenVMS Systems Documentation

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

The Label a Virtual Display Border routine supplies a label for a virtual display's border.

Format

SMG$LABEL_BORDER display-id [,text] [,position-code] [,units] [,rendition-set] [,rendition-complement] [,character-set]

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

text

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

The new label for this display's border. The text argument is the address of a descriptor pointing to the label text. If omitted, the display is not labeled.

position-code

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

Specifies which of the display's borders contains the label. The position-code argument is the address of an unsigned longword that contains the position code.

Valid positions are as follows:

• SMG$K_TOP
• SMG$K_BOTTOM
• SMG$K_RIGHT
• SMG$K_LEFT

SMG$K_RIGHT and SMG$K_LEFT are valid when character-set argument is either SMG$C_ASCII or SMG$C_SPEC_GRAPHICS and when SMG$C_ASCII or SMG$C_SPEC_GRAPHICS is specified in SMG$CHANGE_VIRTUAL_DISPLAY.

If this argument is omitted, the label is displayed on the top border.

units

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

Specifies the character position at which the label begins within the border. The units argument is the address of a signed longword that contains the character position. If omitted, the label is centered in the specified border.

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

character-set

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

Specifies the character set of the label text in text. The character-set argument is the address of an unsigned longword that contains the character set code. If this argument is omitted, the default character set will be the character set set up by SMG$CREATE_VIRTUAL_DISPLAY or by SMG$CHANGE_VIRTUAL_DISPLAY.

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

Description

SMG$LABEL_BORDER lets you specify text to label a virtual display. If the specified virtual display does not already have the border display attribute (SMG$M_BORDER), then this attribute is forced. If the label string is supplied, it replaces the current label text for this border. If you supply an empty (null) label string, the border is not labeled. If the label text (as positioned within the border) does not fit within the border, this routine returns SMG$_INVARG.

Position-code and units together specify the starting position of the label text within a border. If position-code is omitted, the default is the top border. If units is omitted, this routine chooses a starting position so as to center the text either horizontally or vertically, depending on the implicit or explicit position argument. If both position-code and units are omitted, the text is centered in the top border.

Note that vertical labels are available only for SMG$C_ASCII and SMG$C_SPEC_GRAPHICS.

Original SMG routines support only ASCII(default) and DEC Special Graphics, but Korean SMG will allow users to specify the Korean character set to character-set argument which enables Korean language to be used.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_INVARG	Invalid argument. The combination of position-code, units, and text arguments resulted in a position outside the border area.
SMG$_WRONUMARG	Wrong number of arguments.

Example

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

C+
C Include the SMG definitions. In particular, we want SMG$M_BORDER,
C SMG$K_TOP, SMG$K_BOTTOM, and SMG$K_RIGHT.
C-

        IMPLICIT INTEGER (A-Z)
        INCLUDE '($SMGDEF)'

C+
C Call SMG$CREATE_VIRTUAL_DISPLAY to create virtual display number 1.
C Give it a border.
C-

        ROWS = 4
        COLUMNS = 30

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

C+
C Call SMG$CREATE_VIRTUAL_DISPLAY to create virtual display number 2.
C Give it a border.
C-

        ROWS = 3
        COLUMNS = 30

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

C+
C Create virtual display number 3. Do NOT give it a border.
C-

        ROWS = 4
        COLUMNS = 35

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY3)
        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 Call SMG$PUT_CHARS to put data into the virtual displays.
C-

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1          ' A bordered virtual display.', 2, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY2,
     1          ' A bordered virtual display.', 1, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY3,
     1          ' Started as an unbordered display.', 2, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$LABEL_BORDER to label the virtual display borders.
C-

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

        STATUS = SMG$LABEL_BORDER ( DISPLAY2, 'LABEL Bottom',
     1          SMG$K_BOTTOM, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$LABEL_BORDER ( DISPLAY3, 'Forced bordering ',
     1          SMG$K_TOP )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual displays.
C-

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

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

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

        END

      

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

Figure SMG-31 Output Generated by Program Calling SMG$LABEL_BORDER

The List Key Definitions routine returns, one at a time, the definitions (equivalence strings) associated with specified keys in a specified key table.

Format

SMG$LIST_KEY_DEFS key-table-id ,context [,key-name] [,if-state] [,attributes] [,equivalence-string] [,state-string]

RETURNS

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

Arguments

key-table-id

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

Specifies the key table from which you are extracting a key definition. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.

Key-table-id is returned by the SMG$CREATE_KEY_TABLE routine.

context

OpenVMS usage	context
type	longword (unsigned)
access	modify
mechanism	by reference

Provides a means to extract a series of key definitions from a key table. The context argument is the address of an unsigned longword that contains the context variable. For the first call to this routine, you should set the context argument to zero.

Context is incremented by the SMG$LIST_KEY_DEFS routine so that the next call returns the next key definition.

key-name

OpenVMS usage	char_string
type	character string
access	modify
mechanism	by descriptor

Identifies the key whose value you are listing. The key-name argument is the address of a descriptor pointing to the key name.

if-state

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

Receives the state name which qualifies the next definition in the key table. The if-state argument is the address of a descriptor pointing to the string into which the state name is written.

attributes

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

Attributes of this key definition. The attributes argument is the address of an unsigned longword into which the key attributes are written.

Possible attributes are as follows:

SMG$M_KEY_NOECHO	If set, this bit specifies that equiv_string is not to be echoed when this key is pressed; if clear, equiv_string is echoed. If SMG$M_KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is ignored.
SMG$M_KEY_TERMINATE	If set, this bit specifies that when this key is pressed (as qualified by if-state), the input line is complete and more characters should not be accepted. If clear, more characters may be accepted.
SMG$M_KEY_LOCK	If set, and if state-string is specified, the state name specified by state-string remains at the current state until explicitly changed by a subsequent keystroke whose definition includes a state-string. If clear, the state name specified by state-string remains in effect only for the next defined keystroke.
SMG$M_KEY_PROTECTED	If set, this bit specifies that this key definition cannot be modified or deleted. If clear, the key definition can be modified or deleted.

equivalence-string

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

The character string into which the equivalence string is written for the next key definition. The equivalence-string argument is the address of a descriptor pointing to the string into which equivalence-string is written.

state-string

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

A string into which is written the new state name, if any, set by the next key definition. The state-string argument is the address of a descriptor pointing to the string into which the state name is written. If this key definition sets a state, the attributes flag SMG$M_KEY_SETSTATE is also set.

Description

SMG$LIST_KEY_DEFS, when called repeatedly, lets you examine all the definitions in a key table. These definitions may be used with the routine SMG$READ_COMPOSED_LINE.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVKEYNAM	Invalid key-name.
SMG$_INVKTB_ID	Invalid key-table-id.
SMG$_NOMOREKEYS	No more keys in this table.

Any condition value returned by LIB$COPY_DXDX.

The Return Pasting Information routine returns the Pasteboard identifier of the pasteboard to which the specified virtual display is pasted. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual display are also returned.

Format

SMG$LIST_PASTEBOARD_ORDER display-id ,context ,pasteboard-id [,pasteboard-row] [,pasteboard-column]

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

Display identifier of the virtual display that is pasted. The display-id argument is the address of an unsigned longword containing the identifier of this display.

context

OpenVMS usage	context
type	longword (unsigned)
access	modify
mechanism	by reference

Context to search. The context argument is the address of an unsigned longword containing this context. On the initial call, you should set context to zero. SMG$LIST_PASTEBOARD_ORDER updates the value of context. The updated value should then be passed on the subsequent calls to obtain the next pasted display identifier.

pasteboard-id

OpenVMS usage	identifier
type	longword (unsigned)
access	write only
mechanism	by reference

Receives the identifier of the pasteboard on which the virtual display is pasted. The pasteboard-id argument is the address of an unsigned longword containing the identifier of this pasteboard.

pasteboard-row

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

Row of the pasteboard that contains row 1 of the specified virtual display. The optional pasteboard-row argument is the address of a signed longword containing the number of the pasteboard row that contains the first row of the virtual display.

pasteboard-column

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

Column of the pasteboard that contains column 1 of the specified virtual display. The optional pasteboard-column argument is the address of a signed longword containing the number of the pasteboard column that contains the first column of the virtual display.

Description

SMG$LIST_PASTEBOARD_ORDER returns the pasteboard identifier of the pasteboard to which the specified virtual display is pasted. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual displays are also returned.

SMG$LIST_PASTEBOARD_ORDER returns the identifier of the first (or bottommost) pasteboard to which the specified virtual display is pasted. Call this routine in a loop, once for each succeeding pasteboard, until SMG$_NOPASTED is returned.

This routine is useful if, for example, you pasted a display to many pasteboards and you longer know the pasteboard identifier of a pasteboard critical to your application.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_NOPASTED	No more displays are pasted.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_WRONUMARG	Wrong number of arguments.