Document revision date: 30 March 2001
|
|
|
|
OpenVMS RTL Screen Management (SMG$) Manual
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
|