 |
OpenVMS/Hanzi RTL Chinese Screen Management (SMG$)
Manual
The display-id argument must be specified when you use
the rendition-set argument.
rendition-complement
| OpenVMS usage |
mask_longword |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
Attribute complement specifier. The optional
rendition-complement argument is the address of a
longword bit mask in which each attribute set causes the corresponding
attribute to be complemented in the display. All of the attributes that
can be specified with the rendition-set argument can
be complemented with the rendition-complement
argument. The display-id argument must be specified
when you use the rendition-complement argument.
The optional arguments rendition-set and
rendition-complement let the user control the
attributes of the virtual display. The rendition-set
argument sets certain virtual display attributes, while
rendition-complement complements these attributes. If
the same bit is specified in both the rendition-set
and rendition-complement parameters,
rendition-set is evaluated first, followed by
rendition-complement. By using these two parameters
together, the user can control each virtual display attribute in a
single procedure call. On a single-attribute basis, the user can cause
the following transformations:
| Set |
Complement |
Action |
|
0
|
0
|
Attribute set to default
|
|
1
|
0
|
Attribute on
|
|
0
|
1
|
Attribute set to complement of default setting
|
|
1
|
1
|
Attribute off
|
word-terminator-code
| OpenVMS usage |
word_unsigned |
| type |
word (unsigned) |
| access |
write only |
| mechanism |
by reference |
Key terminator code. The word-terminator-code argument
is an unsigned word into which is written a code indicating what
character or key terminated the read. Key terminator codes are of the
form SMG$K_TRM_keyname. The key names are listed in Table 3-1 in
Chapter 3.
character-set
| OpenVMS usage |
longword_unsigned |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
Optional character-set is the address of an unsigned
longword containing the character set of characters to be input. If
this argument is omitted, the default character set of the specified
virtual display is used. If no virtual display is used, the default
character set indicated by the SMG$DEFAULT_CHARACTER_SET logical name is used.
Valid values for this argument are :
| 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.
Refer to Table 2-1 in Section 2.2.14 for the valid definitions of
the SMG$DEFAULT_CHARACTER_SET logical name.
Description
SMG$READ_COMPOSED_LINE reads a line composed of normal keystrokes and
key equivalence strings as defined in the specified key table.
Attributes of the key definition control whether the equivalence string
is echoed and whether the read terminates with the defined keystroke.
Normal keystrokes are always echoed.
A carriage return always terminates the read operation. If Ctrl/Z is
typed and there is no definition for Ctrl/Z in the key definition
table, "EXIT" is echoed and the read is terminated. If Ctrl/Z
was the first character typed on the line, SMG$_EOF is returned.
Otherwise, SMG$_EOF is returned on the next read operation. No other
terminators are recognized except those specified as attributes in a
key definition.
If the arrow keys and Ctrl/B are not defined, the previous lines read
with the SMG$READ_xxxx routines can be recalled using the arrow keys.
The number of lines saved for later recall depends upon the
recall-size argument in SMG$CREATE_VIRTUAL_KEYBOARD.
The default is 20 lines.
Note that SMG$READ_COMPOSED_LINE calls the SMG$FLUSH_BUFFER routine
before performing the input operation. This ensures that the screen
image is up to date at the time of the input operation. Display
batching for both the pasteboard and virtual display must be off when
you use SMG$READ_COMPOSED_LINE.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SS$_ABORT
|
I/O operation aborted during execution (by SMG$CANCEL_INPUT).
|
|
SS$_CANCEL
|
I/O operation canceled while queued (by SMG$CANCEL_INPUT).
|
|
SMG$_EOF
|
End of file.
|
|
SMG$_ILLBATFNC
|
Input not allowed from a batched display.
|
|
SMG$_INVARG
|
Invalid argument.
|
|
SMG$_INVCOL
|
Invalid column. The read operation attempts to use a column outside the
virtual display.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_INVKBD_ID
|
Invalid
keyboard-id.
|
|
SMG$_INVKTB_ID
|
Invalid
key-table-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
Any condition values returned by LIB$COPY_R_DX.
Any condition values returned by $GET (except RMS$_EOF).
Any condition values returned by $QIOW.
SMG$READ_FROM_DISPLAY
The Read Text from Display routine reads a line of text from a virtual
display.
Format
SMG$READ_FROM_DISPLAY display-id ,resultant-string [,terminator-string]
[,start-row] [,rendition-string] [,character-set-string]
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 text is read. 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.
resultant-string
| OpenVMS usage |
char_string |
| type |
character string |
| access |
write only |
| mechanism |
by descriptor |
String into which SMG$READ_FROM_DISPLAY writes the information read
from the virtual display. The resultant-string
argument is the address of a descriptor pointing to the string into
which the string is written.
terminator-string
| OpenVMS usage |
char_string |
| type |
character string |
| access |
read only |
| mechanism |
by descriptor |
String containing a terminator or terminators that end the backward
search, thus determining the starting position of the returned string.
The terminator-string argument is the address of a
descriptor pointing to the string of terminators. If
terminator-string is omitted, no back searching is
performed; the returned string starts with the character at the current
cursor position.
start-row
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
The start-row argument is the address of a signed
longword that contains the row of the virtual display to read from.
This is an optional argument.
rendition-string
| OpenVMS usage |
char_string |
| type |
character string |
| access |
write only |
| mechanism |
by descriptor |
Optional bit mask string that controls the video attributes. The
rendition-string argument is the address of a
descriptor pointing to the bit mask string. Each attribute set causes
the corresponding attribute to be set for the corresponding byte in the
text string in the display. The following attributes can be specified
for each byte using the rendition-string argument:
|
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.
|
charcter-set-string
| OpenVMS usage |
char_string |
| type |
character string |
| access |
write only |
| mechanism |
by descriptor |
Optional byte string that shows character set. The
charcter-set-string argument is the address of a
descriptor pointing to the charcter set string. Each byte shows the
corresponding character set for corresponding byte in the text string
in the display. The following values can be returned for each byte
specified with character-set-string argument:
| Value |
Character Set |
|
SMG$C_ASCII
|
ASCII
|
|
SMG$C_SPEC_GRAPHICS
|
DEC Special Graphics
|
|
SMG$C_HANZI
|
DEC Hanzi
|
|
SMG$C_UNKNOWN
|
Unknown character set
|
1One of DEC supplemental character set and Latin-1 character
set.
Description
SMG$READ_FROM_DISPLAY returns a string that contains some or all of the
text on the current line of the specified virtual display. If the
terminator-string argument is omitted, the contents of
the current line (from the current column position to the rightmost
column position) are returned. If the current column position is the
right portion of a Chinese character, unknown character is
returned for the position. If the start-row argument
is passed, the contents of line start-row from column
1 to the rightmost column are returned in
resultant-string. If the start-row
argument is passed, the terminator-string argument is
ignored.
If you specify terminator-string, each character in it
serves as a terminator for back searching, that is, the process of
determining the first character position to be returned. If none of the
specified terminators is encountered, the search is terminated at the
first character position on the line.
Device-independent characters (+, --, |) are returned for drawn lines.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
Example
|
C+
C This DEC Fortran example demonstrates the use of SMG$READ_FROM_DISPLAY.
C-
C+
C Include the SMG definitions. In particular, we want SMG$M_BORDER.
C-
IMPLICIT INTEGER (A-Z)
INCLUDE '($SMGDEF)'
CHARACTER*80 TEXT
C+
C Use SMG$CREATE_VIRTUAL_DISPLAY to create the virtual display
C and give it a border.
C-
ROWS = 5
COLUMNS = 60
STATUS = SMG$CREATE_VIRTUAL_DISPLAY
1 (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Create the pasteboard by calling SMG$CREATE_PASTEBOARD.
C-
STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Call SMG$PASTE_VIRTUAL_DISPLAY and SMG$PUT_LINE to paste
C the virtual display and put some text on line 2.
C-
STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 2, 10 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$PUT_LINE ( DISPLAY1, ' ' )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$PUT_LINE ( DISPLAY1,
1 'This is an example of using SMG$READ_FROM_DISPLAY.' )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Use SMG$READ_FROM_DISPLAY to read line 2 from the virtual
C display, starting at column 22.
C-
STATUS = SMG$SET_CURSOR_ABS ( DISPLAY1, 2, 22 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Search line 2 from column 22 to column 1 for the null string.
C Since no terminator will be supplied, no "back-searching" will take
C place. TEXT will be assigned the "value" of the line from
C column 22 to the rightmost column.
C-
STATUS = SMG$READ_FROM_DISPLAY ( DISPLAY1, TEXT )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Put the line of text found into the virtual display at row 4,
C column 10 by calling SMG$SET_CURSOR_ABS and SMG$PUT_LINE.
C-
STATUS = SMG$SET_CURSOR_ABS ( DISPLAY1, 4, 10 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$PUT_LINE ( DISPLAY1, TEXT )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Use SMG$SET_CURSOR_ABS to set the cursor back to line 2, column 22.
C-
STATUS = SMG$SET_CURSOR_ABS ( DISPLAY1, 2, 22 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Use SMG$READ_FROM_DISPLAY to search line 2 from column 22 to
C column 1 for an "f". Now, "back-searching" will take place.
C Starting at column 22, "back-track" to column 1 looking for "f".
C Text will then be assigned the "value" of the line from the
C present cursor position (where the "f" is, to the rightmost
C column.
C-
STATUS = SMG$READ_FROM_DISPLAY ( DISPLAY1, TEXT, 'f' )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Put the line of text found into the virtual display at row 4, column 10.
C-
STATUS = SMG$SET_CURSOR_ABS ( DISPLAY1, 5, 10 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$PUT_LINE ( DISPLAY1, TEXT )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
END
|
The output generated by this FORTRAN program is shown in Figure SMG-36.
Figure SMG-36 Output Generated by FORTRAN Program Calling
SMG$READ_FROM_DISPLAY
SMG$READ_KEYSTROKE
The Read a Single Character routine reads a keystroke and returns that
keystroke's terminator code.
Format
SMG$READ_KEYSTROKE keyboard-id ,word-terminator-code [,prompt-string]
[,timeout] [,display-id] [,rendition-set] [,rendition-complement]
RETURNS
| OpenVMS usage |
cond_value |
| type |
longword (unsigned) |
| access |
write only |
| mechanism |
by value |
Arguments
keyboard-id
| OpenVMS usage |
identifier |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
Keyboard identifier. The keyboard-id argument is an
unsigned longword containing the identifier of the virtual keyboard
from which to read.
You can create a virtual keyboard by calling the
SMG$CREATE_VIRTUAL_KEYBOARD routine.
word-terminator-code
| OpenVMS usage |
word_unsigned |
| type |
word (unsigned) |
| access |
write only |
| mechanism |
by reference |
Key terminator code. The word-terminator-code argument
is an unsigned word into which is written a code indicating what
character or key terminated the read. Key terminator codes are of the
form SMG$K_TRM_keyname. The key names are listed in Table 3-1 in
Chapter 3.
prompt-string
| OpenVMS usage |
char_string |
| type |
character string |
| access |
read only |
| mechanism |
by descriptor |
Prompt string. The prompt-string argument is an
optional string used as the prompt for the read operation.
timeout
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Timeout count. The timeout argument is optional. If
specified, any character typed before the timeout is returned in the
buffer.
display-id
| OpenVMS usage |
identifier |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
Display identifier. The optional display-id argument
is the address of an unsigned longword that contains the identifier of
the virtual display in which the read is to be performed. If the
optional prompt-string argument is specified while
there are multiple virtual displays pasted, the
display-id argument is required to determine in which
virtual display the prompt string will be written. If the
prompt-string argument is not specified, do not
specify the display-id argument.
In the case of multiple virtual displays, each virtual display has an
associated virtual cursor position. At the same time, there is a single
physical cursor position corresponding to the current location of the
physical cursor. If the display-id argument is
specified, the read begins at the current virtual cursor position in
the specified virtual display. If display-id is
omitted, the read begins in the current physical cursor position. Note
that the length of the prompt-string plus the key
entered is limited to the number of visible columns in the display.
rendition-set
| OpenVMS usage |
mask_longword |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
Attribute specifier. The optional rendition-set
argument is the address of a longword bit mask in which each attribute
set causes the corresponding attribute to be set in the display. The
following attributes can be specified using the
rendition-set argument:
|
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_USER1 through
SMG$M_USER8
|
Displays user-defined attributes.
|
The display-id argument must be specified when you use
the rendition-set argument.
rendition-complement
| OpenVMS usage |
mask_longword |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
Attribute complement specifier. The optional
rendition-complement argument is the address of a
longword bit mask in which each attribute set causes the corresponding
attribute to be complemented in the display. All of the attributes that
can be specified with the rendition-set argument can
be complemented with the rendition-complement
argument. The display-id argument must be specified
when you use the rendition-complement argument.
The optional arguments rendition-set and
rendition-complement let the user control the
attributes of the virtual display. The rendition-set
argument sets certain virtual display attributes, while
rendition-complement complements these attributes. If
the same bit is specified in both the rendition-set
and rendition-complement parameters,
rendition-set is evaluated first, followed by
rendition-complement. By using these two parameters
together, the user can control each virtual display attribute in a
single procedure call. On a single-attribute basis, the user can cause
the following transformations:
| Set |
Complement |
Action |
|
0
|
0
|
Attribute set to default
|
|
1
|
0
|
Attribute on
|
|
0
|
1
|
Attribute set to complement of default setting
|
|
1
|
1
|
Attribute off
|
Description
SMG$READ_KEYSTROKE reads a keystroke from the specified virtual
keyboard and returns the terminator code of that keystroke in the form
SMG$K_TRM_keyname. The keystroke entered to be read is not echoed on
the screen. This keystroke may be any standard alphabetic character,
any keypad or function key, or one of the directional arrows.
|
