Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

The initial output generated by this Fortran program is shown in Figure SMG-29.

Figure SMG-29 Output Generated Before the Call to SMG$INSERT_LINE

The output generated after the call to SMG$INSERT_LINE is shown in Figure SMG-30.

Figure SMG-30 Output Generated After the Call to SMG$INSERT_LINE

## SMG$INVALIDATE_DISPLAY

> The Mark a Display as Invalid routine marks a display as invalid and causes the entire display to be redrawn.

### Format

> SMG$INVALIDATE_DISPLAY display-id

### RETURNS

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

### Argument

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

> The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

### Description

> SMG$INVALIDATE_DISPLAY marks a display as invalid and redraws the entire display. You would normally use this routine after you determine that output has been written to the display without benefit of the Screen Management Facility.

> This routine redraws the virtual display by invalidating the pasteboard contents of the virtual display's "footprint." If the display is occluded, only the occluded portion of the occluding virtual display is redrawn; the entire display is not redrawn.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVDIS_ID | Invalid display-id.

## SMG$KEYCODE_TO_NAME

> The Translate a Key Code into a Key Name routine translates the key code of a key on the keyboard into its associated key name.

### Format

> SMG$KEYCODE_TO_NAME key-code ,key-name

### RETURNS

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

### Arguments

> #### key-code

> OpenVMS usage: | word_unsigned
> type: | word (unsigned)
> access: | read only
> mechanism: | by reference

> Specifies the key code to translate into a key name. The key-code argument is the address of an unsigned word that contains the key code.

> The key code is returned by SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY in the word-terminator-code argument.

> #### key-name

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

> String containing the name of the key into which key-code is to be translated. The key-name argument is the address of a descriptor pointing to the character string containing the key name. The key-name argument is simply the name of the key (for example, COMMA, PERIOD, KP4, and so forth).

### Description

> SMG$KEYCODE_TO_NAME translates the key code of a key on the keyboard into its associated key name. This key code is the same code returned by the SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY routines in the word-terminator-code argument. The form of key-code is SMG$K_TRM_keyname (for example, SMG$K_TRM_DELETE).

> For more information on terminator values, see Table 3-1.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVKEYNAM | Invalid key-name.

## SMG$LABEL_BORDER

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

> The display identifier 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 this string is supplied, it replaces the current label text for this border. 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

> 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 default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

### 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. A display border, which includes all four sides of the display, can have only one label. 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.

> The position-code and units arguments 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 The label may shift when it is applied to a viewport. This occurs when the label needs to be moved to appear in a sensible location. For example, the default location for a label in a virtual display is at the top of the display and centered. When a viewport is created, that label may shift to remain in the center of the display.

### Condition Values Returned

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

### Example

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

## SMG$LIST_KEY_DEFS

> The List Key Definitions routine returns, one at a time, the definitions (equivalence strings) associated with specified keys in a specified key definition 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 definition 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.

> The key definition table identifier is returned by SMG$CREATE_KEY_TABLE.

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

> The context argument 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 definition 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_LOCKSTATE | 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 definition 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$SCOPY_DXDX.

Previous | Next | Contents | Index

| privacy and legal statement |
5935PRO_023.HTML