[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

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 VAX Ada, VAX BASIC, VAX DIBOL, Digital Fortran, VAX 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:

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

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5935PRO_012.HTML