Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

Any menu items that do not fit within the bounds of the virtual display are not displayed, but are saved for later scrolling by SMG$SELECT_FROM_MENU. The choices are single spaced by default, but if requested this can be changed to double spaced. Four spaces separate each menu item horizontally. If requested, the items can also be displayed in fixed format columns where the width of the column is equal to the size of the largest string passed.

After a call to SMG$CREATE_MENU, the user must not output any characters to the display that disturb the rows containing the newly created menu. If characters are output that do interfere with the menu, unpredictable results will be generated. Use the SMG$SELECT_FROM_MENU routine to select an item from this menu.

SMG$CREATE_MENU supports one-dimensional Noncontiguous Array (NCA) and Varying String Array (VSA) string arrays. NCA and VSA string arrays include all string arrays generated by Compaq Ada, Compaq BASIC, VAX DIBOL, Compaq Fortran, Compaq Pascal, and VAX PL/I. (Note that if you are calling SMG$CREATE_MENU from VAX BASIC, you must still use a MAP statement to declare the array.)

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVDIS_ID | The display identifier is invalid or contains a viewport.
> SMG$_xxxx | Any condition value returned by SMG$PUT_CHARS, SMG$BEGIN_DISPLAY_UPDATE, and SMG$END_DISPLAY_UPDATE.
> LIB$_xxxx | Any condition value returned by LIB$CREATE_VM_ZONE, LIB$GET_VM, LIB$FREE_VM.

## SMG$CREATE_PASTEBOARD

> The Create a Pasteboard routine creates a pasteboard and returns its assigned pasteboard identifier.

### Format

> SMG$CREATE_PASTEBOARD pasteboard-id [,output-device] [,number-of-pasteboard-rows] [,number-of-pasteboard-columns] [,flags] [,type-of-terminal] [,device-name]

### RETURNS

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

### Arguments

> #### pasteboard-id

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

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

> #### output-device

> OpenVMS usage: | device_name
> type: | character string
> access: | read only
> mechanism: | by descriptor

> Specifies the file specification or logical name to which the output associated with this pasteboard will be written. The output-device argument is the address of a descriptor that points to the name of the output device. If omitted, output is sent to SYS$OUTPUT.

> #### number-of-pasteboard-rows

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

> Receives the number of rows on the device specified in the output-device argument. The number-of-pasteboard-rows argument is the address of a signed longword into which is written the number of rows on the specified device, which will be the number of rows in the pasteboard.

> #### number-of-pasteboard-columns

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

> Receives the number of columns on the device specified in the output-device argument. The number-of-pasteboard-columns argument is the address of a signed longword into which the number of columns on the specified device is written.

> #### flags

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

> Specifies the attributes to be used in the pasteboard. The flags argument is the address of an unsigned longword that contains the flag. The default action is to clear the screen when the pasteboard is created.

> Valid values are as follows:

> SMG$M_KEEP_CONTENTS | The screen is not initially cleared. The Screen Management Facility works best when it can manage the entire screen. Therefore, using SMG$M_KEEP_CONTENTS is discouraged.
> SMG$M_WORKSTATION | Calls DECterm to create a DECterm window if the Screen Management Facility is running on a workstation that is running DECwindows. If it is not running on a workstation that is running DECwindows, this flag is ignored.

> #### type-of-terminal

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

> Receives the SMG$ internal device type to which the output associated with this pasteboard will be written. The type-of-terminal argument is the address of an unsigned longword into which is written the terminal type.

> The returned values are as follows:

> > SMG$K_UNKNOWN
> > SMG$K_VTFOREIGN
> > SMG$K_HARDCOPY
> > SMG$K_VTTERMTABLE

> If a value other than SMG$K_VTTERMTABLE is returned, you must use SMG$SNAPSHOT to output the contents of the pasteboard.

> #### device-name

> OpenVMS usage: | char_string
> type: | character string
> access: | write only
> mechanism: | by descriptor

> Receives the device name of the device on which the output associated with this pasteboard is written. The device-name argument is the address of a descriptor into which is written the device name.

> If you specify the SMG$M_WORKSTATION value to the flags argument, this argument returns the DECwindows terminal device name created by the Screen Management Facility for this pasteboard. (You can then specify the device name in a call to SMG$CREATE_VIRTUAL_KEYBOARD to allow reading of input from the DECterm window.) Otherwise, the string specified by OUT_DEVICE is returned.

### Description

> SMG$CREATE_PASTEBOARD creates a new pasteboard, associates it with the device specified by output-device, and returns its assigned pasteboard-id. Note that if you request a pasteboard on a device that already has a pasteboard assigned, this routine returns the pasteboard-id of the existing pasteboard and returns the SMG$_PASALREXI status code.

> If a program calls both SMG$CREATE_PASTEBOARD and SMG$CREATE_VIRTUAL_KEYBOARD, make sure SMG$CREATE_PASTEBOARD is called first. The program will not function correctly if SMG$CREATE_VIRTUAL_KEYBOARD is called before SMG$CREATE_PASTEBOARD.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_PASALREXI | Successful completion. A pasteboard already exists for this device.
> SMG$_WRONUMARG | Wrong number of arguments.
> LIB$_INSVIRMEM | Insufficient virtual memory to allocate needed buffer.

Any condition values returned by LIB$GET_EF, LIB$GET_VM, $QIO, $GETDVI, $ASSIGN.

### Example

    C+                                            SMG1.FOR

    C This Fortran example program demonstrates the use of
    C SMG$CREATE_PASTEBOARD.
    C-

            IMPLICIT INTEGER*4 (A-Z)
            SMG$M_BOLD = 1
            SMG$M_REVERSE = 2
            SMG$M_BLINK = 4
            SMG$M_UNDERLINE = 8
    C+
    C Establish the terminal screen as a pasteboard
    C by calling SMG$CREATE_PASTEBOARD.
    C-

            STATUS = SMG$CREATE_PASTEBOARD (NEW_PID,,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Establish a virtual display region by calling
    C SMG$CREATE_VIRTUAL_DISPLAY.
    C-

            STATUS = SMG$CREATE_VIRTUAL_DISPLAY (5,80,DISPLAY_ID,,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Paste the virtual display to the screen, starting at
    C row 10, column 15 using SMG$PASTE_VIRTUAL_DISPLAY.
    C-

            STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY_ID,NEW_PID,10,15)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Write three lines to the screen using SMG$PUT_LINE.
    C-

            STATUS = SMG$PUT_LINE (DISPLAY_ID,'This line is underlined',2,
            1                               SMG$M_UNDERLINE,0,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

            STATUS = SMG$PUT_LINE (DISPLAY_ID,'This line is blinking',2,
            1                               SMG$M_BLINK,0,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

            STATUS = SMG$PUT_LINE (DISPLAY_ID,'This line is reverse video',2,
            1                               SMG$M_REVERSE,0,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

            END

> This Fortran program calls SMG$ routines to format screen output.

## SMG$CREATE_SUBPROCESS

> The Create and Initialize a Subprocess routine creates a DCL subprocess and associates it with a virtual display.

### Format

> SMG$CREATE_SUBPROCESS display-id [,AST-routine] [,AST-argument] [,flags]

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

> Identifier of the virtual display with which the newly created subprocess is associated. The display-id argument is the address of an unsigned longword containing this identifier.

> #### AST-routine

> OpenVMS usage: | ast_procedure
> type: | procedure value
> access: | call without stack unwinding
> mechanism: | by value

> Optional AST routine to be called when the currently executing command completes. The AST-routine argument is the routine's procedure value.

> The AST routine is called with five parameters. The first parameter is a pointer to a data structure that contains the display-id, AST-argument, and the command-status values. The remaining four parameters for the AST routine are R0, R1, PC, and PSL. The following figure illustrates the AST-routine parameters and the data structure pointed to by the first parameter.

If the AST-routine argument is specified, the routine SMG$EXECUTE_COMMAND buffers any commands passed to it and executes them in order, calling the specified AST routine when each command completes. If the AST-routine argument is not specified, SMG$EXECUTE_COMMAND waits until the specified command completes before returning control to the user.

#### AST-argument

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

Optional argument you supply to the AST routine. The AST-argument parameter is an unsigned longword that contains the value to be passed to the AST routine.

#### flags

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

Optional argument you supply to SMG$CREATE_SUBPROCESS. SMG$CREATE_SUBPROCESS calls LIB$SPAWN to create the subprocess. The flags argument lets you control some of the flags used in that call. Flags available to SMG$CREATE_SUBPROCESS correspond to flags in LIB$SPAWN as follows:

SMG$CREATE_SUBPROCESS Flag | LIB$SPAWN Flag | Function
--- | --- | ---
SMG$M_TRUSTED | TRUSTED | If this bit is set, it indicates a SPAWN command on behalf of the application. If this bit is not set, it indicates that the SPAWN command originates from the user. SPAWN commands originating from users are disallowed in captive accounts (DCL).
SMG$M_AUTHPRIV | AUTHPRIV | If this bit is set, the subprocess inherits the caller's authorized privileges. If this bit is clear, the spawned processes' authorized mask is set equal to the caller's current (active) privilege mask.
SMG$M_SUBSYSTEM | SUBSYSTEM | If this bit is set, a spawned process inherits protected subsystem IDs for the duration of LOGINOUT.EXE (used to map the command line interpreter). The IDs will be removed in the process of transferring control to the command language interpreter (CLI) (as a user mode $RUNDWN is performed). If this bit is clear, LOGINOUT does not execute under the subsystem IDs.

The default is that none of these bits is set. See online Help or the OpenVMS RTL Library (LIB$) Manual for a complete description of LIB$SPAWN, these flags, and the security consideration surrounding their use.

### Description

> SMG$CREATE_SUBPROCESS lets you create a DCL subprocess and associate this subprocess with a virtual display. (The subprocess is initialized using the DCL commands SET NOVERIFY and SET NOON.) From your main process you can then specify commands to be executed by the subprocess using the SMG$EXECUTE_COMMAND routine. Communication between processes is performed using mailboxes, thus allowing you to control the input commands and the output text. When buffering commands, use the optional AST routine to notify your main process whenever a command is completed. Broadcast trapping and unsolicited input do not have to be disabled to use this routine. For more information on mailboxes, see the mailbox driver section of the OpenVMS I/O User's Reference Manual.

> Before creating the subprocess, the Screen Management Facility checks to ensure that you have sufficient resources to create the necessary mailboxes and the subprocess. A remaining BYTLM value of at least 5000 and a remaining PRCLM value of at least 1 are required.

> The Screen Management Facility declares an exit handler that deletes the subprocess if the user exits without first calling the routine SMG$DELETE_SUBPROCESS. Under some circumstances, however, these facility-supplied exit handlers are not executed. In this case, you must delete the subprocess with the DCL command SHOW PROCESS/SUB followed by the DCL command STOP.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INSQUOCRE | Insufficient quota remaining to create subprocess.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_SUBALREXI | Subprocess already exists for this display-id (alternate success status).
> SS$_xxxx | Any status from $GETDVI, $GETJPI, $DCLEXH, or $CREMBX.
> LIB$_xxxx | Any status from LIB$SPAWN, LIB$GET_EF, LIB$GET_VM.

### Example

    10
    !
    ! This VAX BASIC program demonstrates the use of
    ! SMG$CREATE_SUBPROCESS.
    !

    OPTION TYPE = EXPLICIT
    OPTION CONSTANT TYPE = INTEGER

    %INCLUDE "LIB$ROUTINES" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
    %INCLUDE "SMG$ROUTINES" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"   !*** new line
    %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
    %INCLUDE "$SSDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

    COMMON LONG NUM_COMMANDS

    DECLARE SMG$R_SUBPROCESS_INFO_TABLE SMG_INFO        !***
    DECLARE LONG S, PASTEBOARD_ID, DISPLAY_ID, STATUS_DISPLAY_ID

    EXTERNAL INTEGER COMPLETION_ROUTINE          !***

    S = SMG$CREATE_PASTEBOARD (PASTEBOARD_ID)
    IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

    S = SMG$CREATE_VIRTUAL_DISPLAY (12,75,DISPLAY_ID,SMG$M_BORDER)
    IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

    S = SMG$CREATE_VIRTUAL_DISPLAY (5,75,STATUS_DISPLAY_ID,SMG$M_BORDER)
    IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

    S = SMG$PASTE_VIRTUAL_DISPLAY (DISPLAY_ID,PASTEBOARD_ID,2,2)
    IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

    S = SMG$PASTE_VIRTUAL_DISPLAY (STATUS_DISPLAY_ID,PASTEBOARD_ID,17,2)
    IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

    S = SMG$CREATE_SUBPROCESS (DISPLAY_ID,    &
       LOC(COMPLETION_ROUTINE),  &
       STATUS_DISPLAY_ID)
    IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

    NUM_COMMANDS = 1
    S= SMG$EXECUTE_COMMAND(DISPLAY_ID, "$SHOW DEFAULT")
    IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

    NUM_COMMANDS = NUM_COMMANDS + 1
    S= SMG$EXECUTE_COMMAND(DISPLAY_ID, "$SHOW TIME")
    IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

    NUM_COMMANDS = NUM_COMMANDS + 1
    S= SMG$EXECUTE_COMMAND(DISPLAY_ID, "$SHOW QUOTA")
    IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF
    SLEEP (5) UNTIL NUM_COMMANDS <= 0
    END

    20 SUB COMPLETION_ROUTINE(SMG$R_SUBPROCESS_INFO_TABLE SMG_INFO,  &  !***
       LONG R0, LONG R1, LONG PC, LONG PSL)
    OPTION TYPE = EXPLICIT
    OPTION CONSTANT TYPE = INTEGER
    %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
    %INCLUDE "$SSDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

    COMMON LONG NUM_COMMANDS

    DECLARE LONG S

    EXTERNAL LONG FUNCTION LIB$SIGNAL(LONG),  &
      SMG$PUT_LINE (LONG, STRING)

    NUM_COMMANDS = NUM_COMMANDS - 1

    IF (SMG_INFO::SMG$L_STATUS AND 1) <> 0
    THEN
     S = SMG$PUT_LINE(SMG_INFO::SMG$L_USR_ARG, "command completed")
     IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF
    ELSE
     S = SMG$PUT_LINE(SMG_INFO::SMG$L_USR_ARG, "command failed")
     IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF
    END IF

    SUBEND

## SMG$CREATE_VIEWPORT

> The Create a Virtual Viewport routine creates a viewport and associates it with a virtual display. The location and size of the viewport are specified by the caller.

### Format

> SMG$CREATE_VIEWPORT display-id ,viewport-row-start ,viewport-column-start ,viewport-number-rows ,viewport-number-columns

### 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 associated with the newly created viewport. The display-id argument is the address of an unsigned longword containing this identifier.

> #### viewport-row-start

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

> Row number in the virtual display that will become row 1 in the viewport. The viewport-row-start argument is the address of a signed longword containing the row number.

> #### viewport-column-start

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

> Column number in the virtual display that will become column 1 in the viewport. The viewport-column-start argument is the address of a signed longword containing the column number.

> #### viewport-number-rows

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

> Number of rows in the viewport. The viewport-number-rows argument is the address of a signed longword containing the number of rows in the newly created viewport.

> #### viewport-number-columns

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

> Number of columns in the viewport. The viewport-number-columns argument is the address of a signed longword containing the number of columns in the newly created viewport.

### Description

> SMG$CREATE_VIEWPORT creates a viewport and associates it with a particular virtual display. The virtual display must be created before the viewport can be created, and you can only create one viewport for each virtual display. In order to make the viewport visible, you have to paste the virtual display by calling the SMG$PASTE_VIRTUAL_DISPLAY routine; only the portion of the virtual display that falls inside the viewport is visible. You can delete a viewport with the SMG$DELETE_VIEWPORT routine.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | Number of rows or columns is less than zero.
> SMG$_INVCOL | Invalid column specified.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVROW | Invalid row specified.
> SMG$_WINEXISTS | Viewport already exists on the virtual display (alternate success status).
> SMG$_WRONUMARG | Wrong number of arguments.

### Example

    C+
    C This Fortran example creates two virtual displays, one
    C being a copy of the other. The initial virtual display is
    C filled and pasted to the pasteboard. The second virtual
    C display is assigned a viewport and then pasted to the
    C pasteboard. Therefore, only the section of the second
    C virtual display that falls inside the viewport is visible.
    C-
     IMPLICIT INTEGER (A-Z)
     INCLUDE '($SMGDEF)'

    C Create the Virtual Display. Give it a border.

     ROWS = 9
       COLUMNS = 32

     STATUS = SMG$CREATE_VIRTUAL_DISPLAY
         1         (ROWS, COLUMNS, DISPLAY1,SMG$M_BORDER )
     IF (.NOT. STATUS) call lib$signal(%val(STATUS))

    C Create the Pasteboard

     STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
     IF (.NOT. STATUS) call lib$signal(%val(STATUS))

    C Put data in the Virtual Display

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 1, you see.', 1, 1)
     IF (.not. STATUS) call lib$signal(%val(STATUS))

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 2, you see.', 2, 1)
     IF (.not. STATUS) call lib$signal(%val(STATUS))

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 3, you see.', 3, 1)
     IF (.not. STATUS) call lib$signal(%val(STATUS))

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 4, you see.', 4,1)
     IF (.not. STATUS) call lib$signal(%val(STATUS))

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 5, you see.', 5, 1)
     IF (.not. STATUS) call lib$signal(%val(STATUS))

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 6, you see.', 6, 1)
     IF (.not. STATUS) call lib$signal(%val(STATUS))

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 7, you see.', 7, 1)
     IF (.not. STATUS) call lib$signal(%val(STATUS))

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 8, you see.', 8, 1)
     IF (.not. STATUS) call lib$signal(%val(STATUS))

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 9, you see.', 9, 1)
     IF (.not. STATUS) call lib$signal(%val(STATUS))

    C Paste the Virtual Display
     STATUS = SMG$PASTE_VIRTUAL_DISPLAY (DISPLAY1, PASTE1, 2, 2)
     IF (.NOT. STATUS) call lib$signal(%VAL(STATUS))

         STATUS = SMG$LABEL_BORDER (DISPLAY1, 'Full Display',,,SMG$M_BOLD)
     IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

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

     STATUS = SMG$LABEL_BORDER (DISPLAY2, 'Viewport',,,SMG$M_BOLD)
     IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

     STATUS = SMG$CREATE_VIEWPORT ( DISPLAY2, 3, 9, 3, 12)
     IF (.NOT. STATUS) call lib$signal(%VAL(STATUS))

     STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 15, 20)
     IF (.NOT. STATUS) call lib$signal(%VAL(STATUS))

     END

> Previous | Next | Contents | Index

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