Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

The output for this VAX Pascal program is shown in the following figures. In Figure SMG-49, the program is waiting for the user to make a menu selection.

Figure SMG-49 Output Generated Before a Menu Selection Is Made

Because the menu is created using the SMG$M_RETURN_IMMED attribute, once the user makes a selection the menu is terminated, and control returns to the program. The menu item selected by the user is displayed in the upper virtual display. This output is shown in Figure SMG-50.

Figure SMG-50 Output Generated After the User Selects an Item

#2
    10      !+
            !This VAX BASIC program demonstrates the use of
            !SMG-supported menus. Using SMG$CREATE_MENU and
            !SMG$SELECT_FROM_MENU, this program creates an
            !application that uses a vertical menu and allows
            !the user to make multiple selections.
            !-

            OPTION TYPE = EXPLICIT

            EXTERNAL SUB LIB$STOP (LONG BY VALUE)
            EXTERNAL LONG FUNCTION SMG$CREATE_PASTEBOARD (LONG)
            EXTERNAL LONG FUNCTION SMG$CREATE_VIRTUAL_KEYBOARD (LONG)
            EXTERNAL LONG FUNCTION SMG$CREATE_VIRTUAL_DISPLAY (LONG, LONG, &
                                    LONG, LONG, LONG)
            EXTERNAL LONG FUNCTION SMG$PASTE_VIRTUAL_DISPLAY (LONG, LONG, &
                                    LONG, LONG)
            EXTERNAL LONG FUNCTION SMG$CREATE_MENU (LONG, STRING DIM(), LONG, &
                                    LONG, LONG, LONG, LONG)
            EXTERNAL LONG FUNCTION SMG$SELECT_FROM_MENU (LONG, LONG, WORD, &
                                    WORD, LONG, STRING, LONG, WORD, STRING)
            EXTERNAL LONG FUNCTION SMG$PUT_LINE (LONG, STRING)
            EXTERNAL LONG FUNCTION SMG$DELETE_MENU (LONG)

     %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

            DECLARE STRING chosen
            MAP (xyz) STRING choice(20) = 16
            DECLARE LONG ret_status, pasteboard_id, display1_id, display2_id, &
                         keyboard_id
            DECLARE WORD number

            choice(0) = "ONE"
            choice(1) = "TWO"
            choice(2) = "THREE"
            choice(3) = "FOUR"
            choice(4) = "FIVE"
            choice(5) = "SIX"
            choice(6) = "SEVEN"
            choice(7) = "EIGHT"
            choice(8) = "NINE"
            choice(9) = "TEN"
            choice(10) = "ELEVEN"
            choice(11) = "TWELVE"
            choice(12) = "THIRTEEN"
            choice(13) = "FOURTEEN"
            choice(14) = "FIFTEEN"
            choice(15) = "SIXTEEN"
            choice(16) = "SEVENTEEN"
            choice(17) = "EIGHTEEN"
            choice(18) = "NINETEEN"
            choice(19) = "TWENTY"
            choice(20) = "Exit"

            ret_status = SMG$CREATE_PASTEBOARD (pasteboard_id)
            IF (ret_status AND 1%) = 0% THEN
               CALL LIB$STOP (ret_status BY VALUE)
            END IF

            ret_status = SMG$CREATE_VIRTUAL_KEYBOARD (keyboard_id)
            IF (ret_status AND 1%) = 0% THEN
               CALL LIB$STOP (ret_status BY VALUE)
            END IF

            ret_status = SMG$CREATE_VIRTUAL_DISPLAY (10, 20, display1_id, &
                          SMG$M_BORDER, SMG$M_BOLD)
            IF (ret_status AND 1%) = 0% THEN
               CALL LIB$STOP (ret_status BY VALUE)
            END IF

            ret_status = SMG$CREATE_VIRTUAL_DISPLAY (6, 20, display2_id, &
                          SMG$M_BORDER,)
            IF (ret_status AND 1%) = 0% THEN
               CALL LIB$STOP (ret_status BY VALUE)
            END IF

            ret_status = SMG$PASTE_VIRTUAL_DISPLAY (display2_id, &
                          pasteboard_id, 17, 20)
            IF (ret_status AND 1%) = 0% THEN
               CALL LIB$STOP (ret_status BY VALUE)
            END IF

            ret_status = SMG$PASTE_VIRTUAL_DISPLAY (display1_id, &
                          pasteboard_id, 4, 20)
            IF (ret_status AND 1%) = 0% THEN
               CALL LIB$STOP (ret_status BY VALUE)
            END IF

            ret_status = SMG$CREATE_MENU (display1_id, choice(), &
                          SMG$K_VERTICAL,,,SMG$M_BOLD, SMG$M_BOLD)
            IF (ret_status AND 1%) = 0% THEN
               CALL LIB$STOP (ret_status BY VALUE)
            END IF

    20      ret_status = SMG$SELECT_FROM_MENU (keyboard_id, display1_id, &
                          number,, SMG$M_REMOVE_ITEM,,,,chosen)
            IF (ret_status AND 1%) = 0% THEN
               CALL LIB$STOP (ret_status BY VALUE)
            END IF

            ret_status = SMG$PUT_LINE (display2_id, chosen)
            IF (ret_status AND 1%) = 0% THEN
               CALL LIB$STOP (ret_status BY VALUE)
            END IF

            IF (number <> 20) THEN
               GOTO 20
            END IF

            ret_status = SMG$DELETE_MENU (display1_id)
            IF (ret_status AND 1%) = 0% THEN
               CALL LIB$STOP (ret_status BY VALUE)
            END IF

            END

> The vertical menu generated by this VAX BASIC program is shown in the following figures. The default choice is set to the first item in the menu: "ONE". In Figure SMG-51, the program is waiting for the user to make a selection from the menu.

> Figure SMG-51 Output Generated Before the User Selects a Menu Item

Because the menu was created with the SMG$M_REMOVE_ITEM attribute, the user cannot reselect a particular menu item. However, unlike Example 1, the user can make multiple selections. In Figure SMG-52, the user has selected "SIX" and "THIRTEEN", and the program has again highlighted the default menu item and is waiting for the user to make another selection.

Figure SMG-52 Output Generated After Two Selections

In Figure SMG-53, the user has selected "EXIT" and the menu has been deleted, although it still appears on the screen. At this point, no more selections can be made.

Figure SMG-53 Output Generated After EXIT Is Selected

#3
    C+
    C This Fortran example program shows the use of
    C SMG$CREATE_MENU, SMG$SELECT_FROM_MENU, and SMG$DELETE_MENU
    C to create an application that lets a user make multiple
    C selections from a horizontal menu.
    C-

            IMPLICIT INTEGER (A-Z)
            INCLUDE '($SMGDEF)'

            CHARACTER*20 c
            CHARACTER*20 a(20) /'One','Two','Three','This is Four','Five',
         1                  'Six','Seven','Eight','Nine','I like ten',
         2                  'Eleven','Twelve','Thirteen','Fourteen',
         3                  'Fifteen','Sixteen','Seventeen','Eighteen',
         4                  'Nineteen','Exit this menu.' /

            s = SMG$CREATE_PASTEBOARD(p_id)
            if (.not. s) call LIB$SIGNAL(%VAL(s))
            s = SMG$CREATE_VIRTUAL_KEYBOARD(k_id)
            if (.not. s) call LIB$SIGNAL(%VAL(s))
            s = SMG$CREATE_VIRTUAL_DISPLAY(6,50, d_id2, SMG$M_BORDER)
            if (.not. s) call LIB$SIGNAL(%VAL(s))
            s = SMG$CREATE_VIRTUAL_DISPLAY(6,50, d_id, SMG$M_BORDER)
            if (.not. s) call LIB$SIGNAL(%VAL(s))

            s = SMG$PASTE_VIRTUAL_DISPLAY(d_id2, p_id, 2,2)
            if (.not. s) call LIB$SIGNAL(%VAL(s))
            s = SMG$PASTE_VIRTUAL_DISPLAY(d_id, p_id, 10,2)
            if (.not. s) call LIB$SIGNAL(%VAL(s))

            s = SMG$CREATE_MENU(d_id,a,SMG$K_HORIZONTAL,,2,SMG$M_REVERSE)
            if (.not. s) call LIB$SIGNAL(%VAL(s))

      20    s = SMG$SELECT_FROM_MENU(k_id, d_id, n,6,,,,,C,SMG$M_BOLD,0)
            if (.not. s) call LIB$SIGNAL(%VAL(s))
            s = SMG$PUT_LINE(d_id2,c)
            if (.not. s) call LIB$SIGNAL(%VAL(s))

            if (n .ne. 20) goto 20

            s = SMG$DELETE_MENU(d_id)
            if (.not. s) call LIB$SIGNAL(%VAL(s))
     END

> The horizontal menu generated by this Fortran example program is shown in the following figures. In Figure SMG-54, the program displays all menu items in reverse video except for the default choice. At this point, the program is waiting for the user to make a selection.

> Figure SMG-54 Output Generated Before a Menu Item Is Selected

Because no attributes were specified when this menu was created, the items in the menu can be reselected. Figure SMG-55 shows the screen image after the user has made three selections, two of which are the same.

Figure SMG-55 Output Generated After Three Menu Selections

In Figure SMG-56, the user has selected "Exit this menu" and the program has completed execution.

Figure SMG-56 Output Generated After Program Completion

## SMG$SET_BROADCAST_TRAPPING

> The Enable Broadcast Trapping routine enables the trapping of broadcast messages.

### Format

> SMG$SET_BROADCAST_TRAPPING pasteboard-id [,AST-routine] [,AST-argument]

### 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 for which broadcast messages are to be trapped. 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.

> #### AST-routine

> OpenVMS usage: | ast_procedure
> type: | procedure value
> access: | read only
> mechanism: | by value

> The address of an AST routine to be called when a message is received at the pasteboard. The AST-routine argument is the address of the routine's procedure value.

> When the AST-routine argument is either omitted or is given a value of 0, the BROADCAST mode is set to synchronize. In this mode, you must periodically call SMG$GET_BROADCAST_MESSAGE to see if any broadcast messages have arrived.

> The AST routine is called with five parameters: AST-argument, R0, R1, PC, and PSL (on VAX systems) or PS (on Alpha systems).

#### AST-argument

OpenVMS usage: | user_arg
type: | longword (unsigned)
access: | read only
mechanism: | by value

A value to be passed to the AST routine. The AST-argument is an unsigned longword that contains the value to be passed to the AST routine.

### Description

> SMG$SET_BROADCAST_TRAPPING enables the trapping of broadcast messages sent to the specified pasteboard (terminal). When you disable broadcast trapping, any broadcast messages that have been queued to the terminal are lost. If you enable broadcast trapping with SMG$SET_BROADCAST_TRAPPING but do not disable it with SMG$DISABLE_BROADCAST_TRAPPING before the image exits, any messages that have been broadcast to the terminal are lost when the image exits.

> The system parameters DEFMBXBUFQUO and DEFMBXMXMSG are used when creating the mailbox that receives broadcast messages.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVPAS_ID | Invalid pasteboard-id.
> SMG$_NOT_A_TRM | Informational message; the pasteboard is not a terminal.
> SMG$_WRONUMARG | Wrong number of arguments.

Any condition values returned by $DASSGN, $CANCEL, or LIB$ASN_WTH_MBX.

### Example

> For an example using SMG$SET_BROADCAST_TRAPPING, see the example for SMG$DISABLE_BROADCAST_TRAPPING.

## SMG$SET_CURSOR_ABS

> The Set Absolute Cursor Position routine moves the virtual cursor to the specified position in a virtual display.

### Format

> SMG$SET_CURSOR_ABS display-id [,start-row] [,start-column]

### 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 in which to set the virtual cursor position. 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.

> #### start-row

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

> Specifies the row position to which the virtual cursor moves. The start-row argument is the address of a signed longword that contains the row number. If omitted, the cursor remains at the current row.

> #### start-column

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

> Specifies the column position to which the virtual cursor moves. The start-column argument is the address of a signed longword that contains the column number. If omitted, the virtual cursor remains at the current column.

### Description

> SMG$SET_CURSOR_ABS moves the virtual cursor to the specified position in the specified virtual display.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVCOL | Invalid column.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVROW | Invalid row.
> SMG$_WRONUMARG | Wrong number of arguments.

## SMG$SET_CURSOR_MODE

> The Set the Cursor Mode routine turns the physical cursor on or off and selects jump or smooth scrolling.

### Format

> SMG$SET_CURSOR_MODE pasteboard-id ,flags

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

> Pasteboard identifier. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

> #### flags

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

> Optional bit mask that specifies scrolling and cursor attributes. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values:

> SMG$M_CURSOR_OFF | Clears physical cursor.
> SMG$M_CURSOR_ON | Displays physical cursor.
> SMG$M_SCROLL_JUMP | Jump scrolls.
> SMG$M_SCROLL_SMOOTH | Smooth scrolls.

### Description

> SMG$SET_CURSOR_MODE turns the cursor on or off and selects jump or smooth scrolling. If your terminal does not have these capabilities defined, this routine has no effect.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | Invalid argument.
> SMG$_INVPAS_ID | Invalid pasteboard-id.
> SMG$_WRONUMARG | Wrong number of arguments.

## SMG$SET_CURSOR_REL

> The Move Cursor Relative to Current Position routine moves the virtual cursor the specified number of rows and columns from the current virtual cursor position in a virtual display.

### Format

> SMG$SET_CURSOR_REL display-id [,delta-row] [,delta-column]

### 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 in which to move the virtual cursor. 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.

> #### delta-row

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

> Specifies the number of rows to move the virtual cursor. The delta-row argument is the address of a signed longword that contains the number of rows to move. If omitted, the virtual cursor remains at the current row position. If delta-row is positive, the virtual cursor moves downward the specified number of rows. If delta-row is negative, the virtual cursor moves upward the specified number of rows.

> #### delta-column

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

> Specifies the number of columns to move the cursor. The delta-column argument is the address of a signed longword that contains the number of columns to move. If omitted, the virtual cursor remains at the current column position. If delta-column is positive, the virtual cursor moves the specified number of columns to the right. If delta-column is negative, the virtual cursor moves the specified number of columns to the left.

### Description

> SMG$SET_CURSOR_REL moves the virtual cursor the specified number of rows and columns relative to the current virtual cursor position. If the specified delta-row or delta-column causes the cursor to move outside the bounds of the virtual display, SMG$_INVROW or SMG$_INVCOL is returned.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | Invalid argument.
> SMG$_INVCOL | An invalid value of delta-column caused the cursor to move outside the bounds of the virtual display.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVROW | An invalid value of delta-row caused the cursor to move outside the bounds of the virtual display.
> SMG$_WRONUMARG | Wrong number of arguments.

Previous | Next | Contents | Index

| privacy and legal statement |
5935PRO_036.HTML