 |
OpenVMS/Hanzi RTL Chinese Screen Management (SMG$)
Manual
SMG$ENABLE_UNSOLICITED_INPUT
The Enable Unsolicited Input routine detects unsolicited input and
calls an AST routine in response.
Format
SMG$ENABLE_UNSOLICITED_INPUT 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 unsolicited input is being enabled.
The pasteboard-id argument is the address of an
unsigned longword that contains the pasteboard identifier.
Pasteboard-id is returned by
SMG$CREATE_VIRTUAL_PASTEBOARD.
AST-routine
| OpenVMS usage |
ast_procedure |
| type |
procedure value |
| access |
read only |
| mechanism |
by value |
AST routine to be called upon receipt of unsolicited input at the
terminal. The AST-routine argument contains the
routine's procedure value. SMG$ENABLE_UNSOLICITED_INPUT detects the
presence of unsolicited input and calls the AST routine with six
arguments: the pasteboard-id, the
AST-argument, R0, R1, PC, and PSL (on VAX systems) or
PS (on AXP systems). The AST routine arguments are shown in
Figure SMG-19.
Figure SMG-19 AST Routine Arguments
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 argument contains the value to be passed
to the AST routine.
Description
SMG$ENABLE_UNSOLICITED_INPUT detects the presence of unsolicited input
and calls an AST routine in response.
Note that this routine does not read any input characters; it merely
calls an AST routine to "notify" the application that it
should issue a read operation with SMG$READ_COMPOSED_LINE,
SMG$READ_KEYSTROKE or SMG$READ_STRING. It is up to you to read the
unsolicited input.
SMG$ENABLE_UNSOLICITED_INPUT establishes a mailbox that receives
messages when terminal-related events occur that require the attention
of the user image. This mailbox carries status messages, not terminal
data, from the driver to the user program. This status message is sent
to the mailbox when there is unsolicited data in the type-ahead buffer.
In this case, the user process enters into a dialogue with the terminal
after an unsolicited data message arrives. Once this dialogue is
complete, the Screen Management Facility reenables the unsolicited data
message function on the last I/O exchange. Only one message is sent
between read operations. (The sysgen parameters DEFMBXBUFQUO and
DEFMBXMXMSG are used when creating the mailbox.)
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
|
SMG$_INVPAS_ID
|
Invalid
pasteboard-id.
|
Any condition values returned by $QIOW.
Example
For an example using SMG$ENABLE_UNSOLICITED_INPUT, see the example for
the routine SMG$DISABLE_BROADCAST_TRAPPING.
SMG$END_DISPLAY_UPDATE
The End Display Update routine ends update batching for a virtual
display.
Format
SMG$END_DISPLAY_UPDATE display-id
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 to be affected. The
display-id argument is the address of an unsigned
longword that contains the display identifier.
Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY.
Description
SMG$END_DISPLAY_UPDATE and SMG$BEGIN_DISPLAY_UPDATE work together to
control the batching of output operations on a given virtual display.
Each call to SMG$BEGIN_DISPLAY_UPDATE increments a "batch
count," while each call to SMG$END_DISPLAY_UPDATE decrements this
count. When the batch count reaches 0, the virtual display is updated
with all operations done under batching, and written to the pasteboard
if the virtual display is pasted.
Calling SMG$END_DISPLAY_UPDATE when the batch count is zero is a valid
operation; therefore a success status is returned.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_BATWASOFF
|
Successful completion. Note that batching was already off.
|
|
SMG$_BATSTIPRO
|
Successful completion. Note that batching is still in progress.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
SMG$END_PASTEBOARD_UPDATE
The End Pasteboard Update routine ends update batching for a pasteboard.
Format
SMG$END_PASTEBOARD_UPDATE pasteboard-id
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 on which the batch count is to be decremented.
The pasteboard-id argument is the address of an
unsigned longword that contains the pasteboard identifier.
Pasteboard-id is returned by SMG$CREATE_PASTEBOARD. If
the batch count reaches 0, all buffered output for the specified
pasteboard is written out.
Description
SMG$END_PASTEBOARD_UPDATE and SMG$BEGIN_PASTEBOARD_UPDATE work together
to control the batching of output operations on a given pasteboard.
Each call to SMG$BEGIN_PASTEBOARD_UPDATE increments a "batch
count," while each call to SMG$END_PASTEBOARD_UPDATE decrements
this count. When the batch count reaches 0, the pasteboard is written
to the screen.
Calling SMG$END_PASTEBOARD_UPDATE when the batch count is 0 is a valid
operation; a success status is returned.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_BATWASOFF
|
Successful completion. Note that batching was already off.
|
|
SMG$_BATSTIPRO
|
Successful completion. Note that batching is still in progress.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
SMG$ERASE_CHARS
The Erase Characters routine erases columns in a virtual display by
replacing them with blanks.
Format
SMG$ERASE_CHARS display-id ,number-of-columns ,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 from which columns will be erased. The
display-id argument is the address of an unsigned
longword that contains the display identifier.
Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY.
number-of-columns
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Specifies the number of columns to be replaced with blanks. The
number-of-columns argument is the address of a signed
longword that contains the number of columns to be replaced with blanks.
start-row
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Specifies the row on which the erase operation begins. The
start-row argument is the address of a signed longword
that contains the number of the row at which the erasure is to begin.
start-column
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Specifies the column on which the erase operation begins. The
start-column argument is the address of a signed
longword that contains the number of the column at which the erasure is
to begin.
In case that the start-column begins on the right portion of a
Chinese character, the right portion of the character is
overridden by space, and the left portion of the character will become
an undefined character.
Description
SMG$ERASE_CHARS erases columns in a virtual display by replacing them
with blanks. The remaining text in the display is not moved. An erase
operation is limited to the specified line. If
number-of-columns is greater than the number of
columns remaining in the line, all columns from the specified starting
position to the end of the line are erased. This routine leaves the
virtual cursor at the position of the first columns erased.
In case Chinese language character set is used, and the start
column begins on the right portion of a Chinese character, the
right portion of the character is overridden by space and the left
portion of the character will become an undefined character. Also, if
the erasure terminates on the left portion of a Chinese
character, the right portion of the character will become an undefined
character.
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.
|
Example
|
C+
C This DEC Fortran example demonstrates the use of SMG$ERASE_CHARS.
C
C Include the SMG definitions. In particular, we want SMG$M_BORDER.
C-
IMPLICIT INTEGER (A-Z)
INCLUDE '($SMGDEF)'
C+
C Create a virtual display with a border by calling
C SMG$CREATE_VIRTUAL_DISPLAY.
C-
ROWS = 7
COLUMNS = 50
STATUS = SMG$CREATE_VIRTUAL_DISPLAY
1 (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Call SMG$CREATE_PASTEBOARD to create the pasteboard.
C-
STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Using SMG$PUT_CHARS, put data in the virtual display.
C-
STATUS = SMG$PUT_CHARS ( DISPLAY1,
1 ' This virtual display has 7 rows and 50 columns.', 2, 1)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$PUT_CHARS ( DISPLAY1,
1 ' This is a bordered virtual display.', 4, 1)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$PUT_CHARS ( DISPLAY1,
1 ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Call SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display.
C-
STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Erase 4 characters on row 4 starting from character (column) 14 by
C calling SMG$ERASE_CHARS. This will remove the characters "rder"
C from the word "bordered".
C-
STATUS = SMG$ERASE_CHARS ( DISPLAY1, 4, 4, 14)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
END
|
The initial output generated by this FORTRAN example program is shown
in Figure SMG-20.
Figure SMG-20 Output Before the Call to SMG$ERASE_CHARS
The output generated after the call to SMG$ERASE_CHARS is shown in
Figure SMG-21.
Figure SMG-21 Output After the Call to SMG$ERASE_CHARS
SMG$ERASE_COLUMN
The Erase Column From Display routine erases the specified portion of
the virtual display from the given position to the end of the column.
Format
SMG$ERASE_COLUMN display-id [,start-row] [,column-number] [,end-row]
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 to be affected. The
display-id argument is the address of an unsigned
longword containing this virtual display identifier.
start-row
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Optional line number at which the erase operation begins. The
start-row argument is the address of a signed longword
that contains the specified line number. If this argument is omitted,
the column-number argument is ignored and the erase
operation begins at the current location of the virtual cursor for that
virtual display.
column-number
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Optional column number at which the erase operation begins. The
column-number argument is the address of a signed
longword that contains the specified column number. If this argument is
omitted, the start-row argument is ignored and the
erase operation begins at the current location of the virtual cursor
for that virtual display.
In the case that the column-number is on the right
portion of a Chinese character, the left portion of the character
will become an undefined character. Also, if it's on the left portion
of a Chinese character, the right portion of the character will
become an undefined character.
end-row
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Optional row number at which the erase operation ends. The
end-row argument is the address of a signed longword
that contains the specified row number.
Description
SMG$ERASE_COLUMN lets you erase a column of the virtual display from
the specified position to the end of the column. If the position is not
specified, the erase operation begins at the current position of the
virtual cursor in the specified virtual display. After the erase
operation has completed, this routine leaves the virtual cursor at the
position of the first character erased.
In the case that the Chinese language character set is used, if
the erasure operation occurs on the right portion of a Chinese
character, the left portion of the character will become an undefined
character. Also, if it occurs on the left portion of a Chinese
character, the right portion of the character will become an undefined
character.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_INVCOL
|
Invalid column number. The specified column is outside the virtual
display.
|
|
SMG$_INVROW
|
Invalid row number. The specified row is outside the virtual display.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
SMG$ERASE_DISPLAY
The Erase Virtual Display routine erases all or part of a virtual
display by replacing text characters with blanks.
Format
SMG$ERASE_DISPLAY display-id [,start-row] [,start-column] [,end-row]
[,end-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 to be erased. The
display-id argument is the address of an unsigned
longword that contains the display identifier.
Display-id 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 at which the erase operation begins. The
start-row argument is the address of a signed longword
that contains the number of the row at which the erasure begins.
If the start-row argument is not specified,
start-column is also ignored and the entire virtual
display is erased. If you do not specify start-row and
start-column, then end-row and
end-column are ignored and the entire virtual display
is erased.
start-column
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Specifies the column at which the erase operation begins. The
start-column argument is the address of a signed
longword that contains the number of the column at which the erasure
begins.
If the start-column argument is not specified,
start-row is also ignored and the entire virtual
display is erased. If you do not specify start-row and
start-column, then end-row and
end-column are ignored and the entire virtual display
is erased.
In case that the start-column begins on the right
portion of a Chinese character, the left portion of the character
will become an undefined character.
end-row
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Specifies the row at which the erase operation ends, that is, the last
row to be erased. The end-row argument is the address
of a signed longword that contains the number of the last row to be
erased.
If the end-row argument is not specified,
end-column is also ignored and all remaining rows in
the display are erased.
end-column
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Specifies the column at which the erase operation ends, that is, the
last column to be erased. The end-column argument is
the address of a signed longword that contains the number of the last
column to be erased.
If the end-column argument is not specified,
end-row is also ignored and all remaining columns in
the display are erased.
In case that the end-column terminates on the left
portion of a Chinese character, the right portion of the
character will become an undefined character.
Description
SMG$ERASE_DISPLAY causes all or part of a virtual display to be erased
by replacing text characters with blanks. If omitted, the starting
positions default to 1,1. The ending positions default to the last row
or column in the display. Thus, to erase the entire virtual display,
you need only pass the display-id. This routine leaves
the virtual cursor at the start of the erased position. If the entire
display is erased, the virtual cursor is left at position 1,1.
|
