Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

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

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:

If both arguments are omitted, no information is returned.

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


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

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5935PRO_011.HTML