Document revision date: 30 March 2001

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

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.

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.

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

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.

	privacy and legal statement
5935PRO_023.HTML