Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

## SMG$CONTROL_MODE

> The Control Mode routine controls the mode of the pasteboard. This includes buffering, minimal updating, whether the screen is cleared when the pasteboard is deleted, and whether tab characters are used for screen formatting.

### Format

> SMG$CONTROL_MODE pasteboard-id [,new-mode] [,old-mode] [,buffer-size]

### RETURNS

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

### Arguments

> #### pasteboard-id

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

> Specifies the pasteboard to be changed. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

> The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

> #### new-mode

> OpenVMS usage: | mask_longword
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> Specifies the new control settings to be used. The optional new-mode argument is the address of an unsigned longword that contains the mode settings. A bit set to 1 forces that mode to be employed; a bit set to 0 inhibits that mode of operation.

> Valid settings are as follows:

> SMG$M_BUF_ENABLED | Enables buffering.
> SMG$M_CLEAR_SCREEN | Causes the Screen Management Facility to clear the screen when the program exits if you have not previously deleted the pasteboard.
> SMG$M_IGNORE | Allows you to delete the pasteboard even if batching is in effect.
> SMG$M_MINUPD | Enables minimal update (the default).
> SMG$M_NOTABS | Causes the Screen Management Facility not to use tab characters to format the screen.
> SMG$M_PROTECT | Protect pasteboard operations from AST interrupts (the default).
> SMG$M_RELEASE_PBD | Allows you to change the pasteboard size (using the SMG$CHANGE_PBD_CHARACTERISTICS routine) and prevents the Screen Management Facility from modifying anything on the screen outside of the smaller pasteboard.

> All other bits must be 0 and are reserved for future use by Compaq.

> #### old-mode

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

> Receives the control settings that were in effect before calling this procedure. The optional old-mode argument is the address of an unsigned longword into which the former mode settings are written. A bit set to 1 indicates that the specified mode was employed; a bit set to 0 indicates that the mode was inhibited.

> #### buffer-size

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

> Specifies the size of the buffer in bytes. The optional buffer-size argument is the address of an unsigned word that contains the size of the buffer. The buffer-size argument is used when buffering mode is enabled (SMG$M_BUF_ENABLED). The default and minimum buffer size is 256 bytes. The maximum value is 65535. The buffer-size value depends on user authorization file (UAF) values and is maximized with the SYSGEN parameter MAXBUF.

### Description

> SMG$CONTROL_MODE lets you determine and change the mode of the Screen Management Facility operation for a specified pasteboard. By specifying different combinations of the new-mode and old-mode arguments, SMG$CONTROL_MODE can be used in the following ways:
> - To use SMG$CONTROL_MODE to determine the current mode settings, use the following format:

>   `SMG$CONTROL_MODE (pasteboard_id ,,old_mode)`

> - To use SMG$CONTROL_MODE to set the bits without regard to their current setting, use the following format:

>   `SMG$CONTROL_MODE (pasteboard_id ,new_mode)`

> - To use SMG$CONTROL_MODE to save the current settings, set new modes, and later restore the original settings, use the following format:

>   `SMG$CONTROL_MODE (pasteboard_id ,new_mode ,old_mode)`

>   This retrieves the current bit settings and then sets the mode according to the new-mode argument.
>   Later, to restore the mode to its former state, specify the following format:

>   `SMG$CONTROL_MODE (pasteboard_id ,old_mode)`

>   This sets the new mode according to the settings previously retrieved.

> If both arguments are omitted, no information is returned.

> The modes that can be determined and changed using SMG$CONTROL_MODE are as follows:

> - Buffering
>   In this mode, the Screen Management Facility buffers all output for efficient use of system QIOs. When the buffer fills, SMG$ writes the buffer to the terminal. By calling SMG$FLUSH_BUFFER, the user can force to the screen any output that has been placed in the pasteboard buffer but not yet written to the terminal.
> - Minimal Screen Update
>   By default, the Screen Management Facility tries to minimize the number of characters actually sent to the terminal. It does this by keeping track of the current contents of the pasteboard and the new contents of the pasteboard. SMG$ then sends only those characters that have changed.
>   Nonminimal updating rewrites any line containing a change, starting with the first changed character on that line.
> - Clear Screen
>   By default, the Screen Management Facility does not clear the screen when the program exits if you have not already deleted the pasteboard. Use the clear screen mode to prevent this default behavior.
> - No Tabs
>   If this bit is set, the Screen Management Facility does not rely on the terminal's tab settings. If it is not set, the Screen Management Facility will use physical tabs for the minimal update procedure. However, note that such use implicitly assumes that the tab stops are set to the Compaq default locations (every eight characters). Specify "no tabs" if you want to be sure that the application will run regardless of the tab settings the user has set on the terminal. By default, this bit is clear. A terminal setting of SET TERM/NOTABS may also be used to override this default.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | Invalid argument. New-mode has a bit set that does not correspond to SMG$M_BUF_ENABLED, SMG$M_MINUPD, SMG$M_CLEAR_SCREEN, or SMG$M_NOTABS, or buffer size is less than 256.
> SMG$_INVPAS_ID | Invalid pasteboard-id.
> SMG$_WRONUMARG | Wrong number of arguments.

## SMG$COPY_VIRTUAL_DISPLAY

> The Copy a Virtual Display routine creates a copy of an existing virtual display and assigns to it a new virtual display identifier.

### Format

> SMG$COPY_VIRTUAL_DISPLAY current-display-id ,new-display-id

### RETURNS

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

### Arguments

> #### current-display-id

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

> Display identifier of the virtual display to be replicated. The current-display-id argument is the address of the unsigned longword that contains the display identifier.

> #### new-display-id

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

> Receives the display identifier of the newly created virtual display. The new-display-id argument is the address of the unsigned longword that receives the new display identifier.

### Description

> SMG$COPY_VIRTUAL_DISPLAY creates a copy of an existing virtual display and assigns to it a new virtual display number. This newly created virtual display will not be pasted anywhere; use SMG$PASTE_VIRTUAL_DISPLAY and the new-display-id identifier to paste the newly created virtual display. The existing display being replicated does not have to be pasted when SMG$COPY_VIRTUAL_DISPLAY is invoked.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> LIB$_INSVIRMEM | Insufficient virtual memory to allocate needed buffer.

### Example

    C+
    C This Fortran example program demonstrates the use of
    C SMG$COPY_VIRTUAL_DISPLAY.
    C
    C This routine creates a virtual display and writes it to the
    C pasteboard.  Data is placed in the virtual display using SMG$PUT_CHARS.
    C-

            IMPLICIT INTEGER (A-Z)
            CHARACTER*29 TEXT

    C+
    C Include the SMG definitions. In particular, we want SMG$M_BORDER.
    C-

            INCLUDE '($SMGDEF)'

    C+
    C Create two virtual displays using SMG$CREATE_VIRTUAL_DISPLAY.
    C Give them borders.
    C-

            ROWS = 6
            COLUMNS = 50

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

            ROWS = 5
            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 the pasteboard using SMG$CREATE_PASTEBOARD.
    C-

            STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Use SMG$PUT_CHARS to put data into the virtual displays.
    C-

            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1         ' This virtual display has 6 rows and 50 columns.', 2, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1         ' This is a bordered virtual display.', 3, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1         ' SMG$PUT_CHARS puts data in this virtual display.', 4,
         1          1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1         ' This text should be partially occluded.', 5, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1         ' So should part of this row.', 6, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY2, ' This is virtual', 3, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY2,
         1         ' display #2.', 4, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY2,
         1         ' This is just some more text.', 5, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Use SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display.
    C-

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

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

    C+
    C Copy the first virtual display, the one that is partially occluded.
    C-

     STATUS = SMG$COPY_VIRTUAL_DISPLAY ( DISPLAY1, NEW_DISPLAY)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Now paste this new virtual display so that it occludes the other displays.
    C-

            STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( NEW_DISPLAY, PASTE1, 4, 20)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            END

> The first virtual display created by this Fortran example is shown in Figure SMG-5.

> Figure SMG-5 First Virtual Display Generated by SMG$COPY_VIRTUAL_DISPLAY

The second virtual display created by this Fortran example is shown in Figure SMG-6.

Figure SMG-6 Second Virtual Display Generated by SMG$COPY_VIRTUAL_DISPLAY

The output generated after the call to SMG$COPY_VIRTUAL_DISPLAY is shown in Figure SMG-7.

Figure SMG-7 Output Generated After the Call to SMG$COPY_VIRTUAL_DISPLAY

## SMG$CREATE_KEY_TABLE

> The Create Key Table routine creates a table for key definitions.

### Format

> SMG$CREATE_KEY_TABLE key-table-id

### RETURNS

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

### Argument

> #### key-table-id

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

> Receives the identifier of the newly created key table. The key-table-id argument is the address of an unsigned longword into which the key table identifier is written.

### Description

> SMG$CREATE_KEY_TABLE creates a key definition table. You can add key definitions to this table with the SMG$ADD_KEY_DEF, SMG$LOAD_KEY_DEFS, and SMG$DEFINE_KEY routines. You can list the key definitions in this table with the SMG$LIST_KEY_DEFS routine. The key definitions in this table are used by the SMG$READ_COMPOSED_LINE routine.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_WRONUMARG | Wrong number of arguments.
> LIB$_INSVIRMEM | Insufficient virtual memory.

## SMG$CREATE_MENU

> The Fill the Virtual Display with a Menu routine displays menu choices in the virtual display indicated, starting at the specified row.

### Format

> SMG$CREATE_MENU display-id ,choices [,menu-type] [,flags] [,row] [,rendition-set] [,rendition-complement]

### 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 in which the menu is created. The display-id argument is the address of an unsigned longword containing this identifier.

> #### choices

> OpenVMS usage: | static array of char_string
> type: | character string
> access: | read only
> mechanism: | by descriptor

> Static array in which each element corresponds to an item to be displayed in the menu. The choices argument is the address of a descriptor pointing to this static array of character strings. Note that blank menu items are ignored.

> #### menu-type

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

> Optional bit mask specifying the type of menu to be displayed. The menu-type argument is the address of a longword bit mask that specifies this menu type. Valid values are as follows:

> SMG$K_BLOCK | The menu items are displayed in matrix format (default).
> SMG$K_VERTICAL | Each menu item is displayed on its own line.
> SMG$K_HORIZONTAL | The menu items are displayed all on one line.

> #### flags

> OpenVMS usage: | mask_longword
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> Optional bit mask specifying the attributes to be used for the menu. The flags argument is the address of an unsigned longword that contains the flag. Valid values are as follows:

> SMG$M_DOUBLE_SPACE | Double-spaced rows of menu items. The default is single spaced.
> SMG$M_FIXED_FORMAT | Each menu item is in a fixed-length field. The field is the size of the largest menu item. The default is compress.
> SMG$M_FULL_FIELD | The full field is highlighted when you move within the menu using item keys. The default is that menu items only are highlighted. If you specify this flag value, it also implies SMG$M_FIXED_FORMAT.
> SMG$M_WIDE_MENU | Wide characters are used in the menu items. The default is normal sized characters.
> SMG$M_WRAP_MENU | The up arrow and down arrow keys cause the menu to wrap when the cursor is on the first or last rows of the menu.

> #### row

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

> Optional row number in the specified virtual display at which the first menu item is displayed. The row argument is the address of a signed longword that contains this row number. If row is omitted, the first row of the virtual display's scrolling region is used.

> #### 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 used when writing out the menu choices. 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$CREATE_MENU displays a list of menu choices in the virtual display's virtual scrolling region, starting in a specified row. Menu items start in the second column of the virtual display. Multiple menu items on the same row are separated by four spaces.

> The choices are displayed with the specified rendition attributes in any one of the following formats:

> Vertical | Each menu item is on its own line.
> Horizontal | The menu items are all on one line.
> Block | The menu items appear in matrix format.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 5935PRO_011.HTML