HP OpenVMS Systems Documentation

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.

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

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.

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