 |
OpenVMS/Hanzi RTL Chinese Screen Management (SMG$)
Manual
This FORTRAN program calls Run-Time Library Screen Management 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]
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 entry mask.
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.
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.
Description
SMG$CREATE_SUBPROCESS lets you create a DCL subprocess and associate
this subprocess with a virtual display. (The subprocess is initialized
using the SET NOVERIFY and SET NOON DCL commands.) 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.
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 SHOW PROCESS/SUB command
followed by the DCL STOP command.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_SUBALREXI
|
Subprocess already exists for this
display-id (alternate success status).
|
|
SMG$_INSQUOCRE
|
Insufficient quota remaining to create subprocess.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SS$_xxxx
|
Any status from $GETDVI, $GETJPI, $DCLEXH, or $CREMBX.
|
|
LIB$_xxxx
|
Any status from LIB$SPAWN, LIB$GET_EF, or 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" !***
%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.
In the case that the viewport-column-start begins on
the right portion of a Chinese character, the right portion of
the character becomes invisible.
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.
In case Chinese language character set is used, and the
viewport-column-start begins on the right portion of a
Chinese character, the right portion of the character will become
invisible. Also if the viewport ends on the left portion of a
Chinese character, the left portion of the character will become
invisible.
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 DEC 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
|
In this DEC Fortran example, the initial virtual display is copied to a
second virtual display that has a viewport associated with it. When the
second virtual display is pasted, only the portion of the virtual
display that falls inside the viewport is visible. This is shown in
Figure SMG-8.
Figure SMG-8 Output Generated by Creating a Viewport
SMG$CREATE_VIRTUAL_DISPLAY
The Create Virtual Display routine creates a virtual display and
returns its assigned display identifier.
Format
SMG$CREATE_VIRTUAL_DISPLAY number-of-rows ,number-of-columns
,display-id [,display-attributes] [,video-attributes] [,character-set]
RETURNS
| OpenVMS usage |
cond_value |
| type |
longword (unsigned) |
| access |
write only |
| mechanism |
by value |
Arguments
number-of-rows
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Specifies the number of rows in the newly created virtual display. The
number-of-rows argument is the address of a signed
longword that contains the desired number of rows.
number-of-columns
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Specifies the number of columns in the newly created virtual display.
The number-of-columns argument is the address of a
signed longword that contains the desired number of columns.
display-id
| OpenVMS usage |
identifier |
| type |
longword (unsigned) |
| access |
write only |
| mechanism |
by reference |
Receives the display-id of the newly created virtual
display. The display-id argument is the address of an
unsigned longword into which is written the display identifier.
display-attributes
| OpenVMS usage |
mask_longword |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
Specifies the default display attributes. The optional
display-attributes argument is the address of an
unsigned longword that contains the desired display attributes.
Valid values for display-attributes are as follows:
|
SMG$M_BORDER
|
Specifies a bordered display. If omitted, the display is not bordered.
|
|
SMG$M_BLOCK_BORDER
|
Specifies a block-bordered display. If omitted, the display is not
bordered.
|
|
SMG$M_DISPLAY_CONTROLS
|
Specifies that control characters such as carriage return and line feed
are displayed as graphic characters, if your terminal supports them.
|
|
SMG$M_TRUNC_ICON
|
Specifies that an icon (generally a diamond shape) is displayed where
truncation of a line exceeding the width of the virtual display has
occurred.
|
video-attributes
| OpenVMS usage |
mask_longword |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
Specifies the default rendition to be applied to all output in this
virtual display unless overridden by a call to a specific output
routine (for example, SMG$CHANGE_RENDITION). The
video-attributes argument is the address of an
unsigned longword that contains the video attributes mask.
Valid values for this argument are as follows:
|
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_INVISIBLE
|
Specifies invisible characters; that is, the characters exist in the
virtual display but do not appear on the pasteboard.
|
SMG$M_USER1 through
SMG$M_USER8
|
Displays user-defined attributes.
|
character-set
| OpenVMS usage |
longword_unsigned |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of
an unsigned longword that contains the character set specifier. If this
argument is omitted, the logical name of SMG$DEFAULT_CHARACTER_SET is used to
determine the default character set. If the logical name is not defined
or if the logical name is invalid, the default character set value is
UNKNOWN.
The valid values for this argument is as follows:
| Value |
Character Set |
|
SMG$C_ASCII
|
ASCII
|
|
SMG$C_SPEC_GRAPHICS
|
DEC Special Graphics
|
|
SMG$C_HANZI
|
DEC Hanzi
|
1One of DEC supplemental character set and Latin-1 character
set.
For the valid SMG$DEFAULT_CHARACTER_SET definitions, refer to Table 2-1 in
Section 2.2.14.
Description
SMG$CREATE_VIRTUAL_DISPLAY creates a new virtual display and returns
its display identifier. Initially, the virtual display contains blanks,
and the virtual cursor is positioned at row 1, column 1. The virtual
scrolling region is the entire virtual display. To make the display
visible, use the SMG$PASTE_VIRTUAL_DISPLAY routine.
Original SMG routines support only ASCII(default) and DEC Special
Graphics, but Chinese SMG will allow users to specify the
character-set which enables Chinese language to
be used.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
|
SMG$_INVARG
|
Invalid argument.
Video-attributes or
display-attributes contains an unknown value.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
Examples
| #1 |
C+
C This DEC Fortran example program demonstrates the use of
C SMG$ERASE_PASTEBOARD.
C-
IMPLICIT INTEGER*4 (A-Z)
CHARACTER*80 OUT_STR,TRIM_STR
CHARACTER*18 PROMPT /'Please enter data '/
SMG$M_BOLD = 1
SMG$M_REVERSE = 2
SMG$M_BLINK = 4
SMG$M_UNDERLINE = 8
C+
C Establish the terminal keyboard as the virtual keyboard
C by calling SMG$CREATE_VIRTUAL_KEYBOARD.
C-
STATUS = SMG$CREATE_VIRTUAL_KEYBOARD(KEYBOARD_ID,,,)
IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Establish the terminal screen as a pasteboard using
C 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
C calling 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. To paste the virtual display, use
C 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 Prompt the user for input, and accept that input using
C SMG$READ_STRING.
C-
STATUS = SMG$READ_STRING(KEYBOARD_ID,OUT_STR,PROMPT,,,,,,,)
IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Clear the screen using SMG$ERASE_PASTEBOARD.
C-
STATUS = SMG$ERASE_PASTEBOARD (NEW_PID)
IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Trim any trailing blanks from the user input
C by calling STR$TRIM.
C-
STATUS = STR$TRIM(TRIM_STR,OUT_STR,STR_LEN)
IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Display the data input by the user using SMG$PUT_CHARS
C and SMG$PUT_LINE.
C-
STATUS = SMG$PUT_CHARS(DISPLAY_ID,'You entered: ',,,,,,)
IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
STATUS = SMG$PUT_LINE(DISPLAY_ID,TRIM_STR(1:STR_LEN),,
1 SMG$M_REVERSE,0,,)
IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
END
|
|
