|
Document revision date: 30 March 2001
|
![[Compaq]](../../images/compaq.gif) |
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
|
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
|
OpenVMS RTL Screen Management (SMG$) Manual
SMG$SET_DEFAULT_STATE
The Set Default State routine sets and/or returns the current default
state for a key table.
Format
SMG$SET_DEFAULT_STATE key-table-id [,new-state] [,old-state]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
key-table-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the key table in which you are setting or inquiring about a
default state. The key-table-id argument is the
address of an unsigned longword that contains the key table identifier.
The key table identifier is returned by the SMG$CREATE_KEY_TABLE
routine.
new-state
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Specifies the new default state for the entire key table. The
new-state argument is the address of a descriptor
pointing to the new state string. The specified state name is converted
to uppercase and stripped of trailing blanks before use.
old-state
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Receives the existing default state name of the specified key
definition table. The old-state argument is the
address of a descriptor pointing to the string into which the old state
string is written.
Description
SMG$SET_DEFAULT_STATE sets and/or returns the default state name for an
entire key definition table. By changing the default state for an
entire key definition table, you can use the keypad keys for a new set
of functions. You can use the key definition table with the
SMG$READ_COMPOSED_LINE routine.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVKTB_ID
|
Invalid
key-table-id.
|
|
SMG$_INVSTANAM
|
Invalid state name.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor.
|
SMG$SET_DISPLAY_SCROLL_REGION
The Create Display Scrolling Region routine creates a virtual scrolling
region in a virtual display.
Format
SMG$SET_DISPLAY_SCROLL_REGION display-id [,start-row] [,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 |
Specifies the virtual display in which scrolling takes place. The
display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the first line of the virtual scrolling region. The
start-row argument is the address of a signed longword
that contains the starting line number. If omitted, the first line of
the display is used.
end-row
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the last line of the virtual scrolling region. The
end-row argument is the address of a signed longword
that contains the ending line number. If omitted, the last line of the
virtual display is used.
Description
SMG$SET_DISPLAY_SCROLL_REGION creates a virtual scrolling region in a
specified virtual display, using the specified starting and ending
lines. If the start-row and end-row
arguments are omitted, the entire display becomes a scrolling region.
This routine does not change the appearance of the pasteboard or the
virtual cursor position.
You can define part or all of a virtual display as scrolling using
SMG$SET_DISPLAY_SCROLL_REGION. The behavior of scrolling in the Screen
Management Facility is as follows: When you call SMG$PUT_LINE to write
to the bottom line of the scroll region, the display does not scroll up
immediately. If the display scrolled up immediately, it never would be
possible to use the bottom line of the scroll region. Instead, the need
for a scroll is "stored" until you issue the next
SMG$PUT_LINE call. (The need for a scroll is stored only until your
next call to a whole-line write routine, such as SMG$PUT_LINE,
SMG$PUT_LINE_WIDE, and so on.)
If you call another routine after SMG$PUT_LINE, such as
SMG$SET_CURSOR_ABS or SMG$PUT_CHARS, the stored need for a scroll will
be discarded and text written to the bottom line of the scrolling
region will overwrite the existing line.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVARG
|
The
end-row argument is less than or equal to
start-row.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_INVROW
|
Invalid row.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
SMG$SET_KEYPAD_MODE
The Set Keypad Mode routine sets the terminal's numeric keypad to
either numeric or applications mode.
Format
SMG$SET_KEYPAD_MODE keyboard-id ,flags
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 |
Specifies the virtual keyboard whose mode is to be changed. The
keyboard-id argument is the address of an unsigned
longword that contains the keyboard identifier.
The keyboard identifier is returned by SMG$CREATE_VIRTUAL_KEYBOARD.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Optional bit mask that specifies whether the keypad is to be in
applications or numeric mode. The flags argument is
the address of an unsigned longword that contains the flag. Valid
values for flags are as follows:
|
0
|
Keypad is set to numeric mode.
|
|
SMG$M_KEYPAD_APPLICATION
|
Keypad is set to applications mode.
|
Description
SMG$SET_KEYPAD_MODE sets the terminal's numeric keypad to either
numeric or applications mode. In applications mode, numeric keypad keys
are considered function keys and may be used as terminators. In numeric
mode, these keys are equivalent to the corresponding keys on the main
keyboard.
If the terminal does not support applications keypad mode, this routine
has no effect.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVKBD_ID
|
Invalid
keyboard-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
SMG$SET_OUT_OF_BAND_ASTS
The Set Out-of-Band ASTs routine either enables or disables the
trapping of out-of-band control characters.
Format
SMG$SET_OUT_OF_BAND_ASTS pasteboard-id,control-character-mask
,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 out-of-band characters are enabled
or disabled. The pasteboard-id argument is the address
of an unsigned longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
control-character-mask
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies which control characters are to be the new out-of-band
control characters. The control-character-mask
argument is the address of an unsigned longword that contains the mask.
Create this mask by setting the bit that corresponds to the ASCII value
of the desired character. For example, to specify that Ctrl/C (ASCII
value 3) is an out-of-band control character, set bit 3 (value 8) in
the control-character-mask. If no bits are set in this
mask, then no out-of-band ASTs occur. For more information, see the
OpenVMS I/O User's Reference Manual.
AST-routine
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
read only |
| mechanism: |
by value |
The address of an AST routine to be called when an out-of-band control
character is typed at the terminal. The AST-routine
argument is the routine's procedure value.
AST-argument
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The argument you supply to the AST. AST-argument is an
unsigned longword that contains the value to be passed to the AST
routine. However, the AST routine may also need to determine the
out-of-band character and the pasteboard-id at which
it was typed. Therefore, the Screen Management Facility creates a
three-longword structure to hold this information and passes the
address of this structure as the first argument to the AST routine. The
remaining four arguments are R0, R1, PC, and PSL (on VAX systems) or PS
(on Alpha systems). The Screen Management Facility stores the argument
you supply in this structure.
The first longword contains the pasteboard-id and has
the symbolic name SMG$L_PBD_ID. The second longword contains the
AST-argument and has the symbolic name SMG$L_USER_ARG.
The third longword contains the ASCII value of the out-of-band
character typed and can be accessed by way of two symbolic names:
SMG$B_CHAR (the low-order byte containing the ASCII value), and
SMG$L_CHAR (the longword containing the ASCII value in the low-order
byte and spaces in the high-order bytes).
Description
SMG$SET_OUT_OF_BAND_ASTS enables or disables the acceptance of
out-of-band control characters at the specified terminal. If one of
these characters is typed at the terminal, the AST routine is called.
This routine can be used to trap out-of-band characters, such as
Ctrl/C, Ctrl/Y, and Ctrl/O.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVPAS_ID
|
Invalid
pasteboard-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
Example
|
!+
! This BASIC example demonstrates the use of
! SMG$SET_OUT_OF_BAND_ASTS.
!-
OPTION TYPE = EXPLICIT
OPTION CONSTANT TYPE = INTEGER
%INCLUDE "$smgdef" %FROM %LIBRARY "sys$library:basic$starlet"
%INCLUDE "$ssdef" %FROM %LIBRARY "sys$library:basic$starlet"
EXTERNAL LONG FUNCTION smg$create_pasteboard, &
smg$create_virtual_keyboard, &
smg$set_out_of_band_asts
EXTERNAL LONG out_band_routine
DECLARE LONG s, pasteboard_id, keyboard_id, ctrl_mask
ctrl_mask = (2%**smg$k_trm_ctrlc) + (2%**smg$k_trm_ctrlw) + &
(2%**smg$k_trm_ctrlz)
s = smg$create_pasteboard (pasteboard_id)
IF s <> ss$_normal THEN CALL lib$signal(s) END IF
s = smg$create_virtual_keyboard (keyboard_id)
IF s <> ss$_normal THEN CALL lib$signal(s) END IF
s = smg$set_out_of_band_asts (pasteboard_id, &
ctrl_mask, &
LOC(out_band_routine) BY VALUE, &
keyboard_id BY VALUE)
IF s <> ss$_normal THEN CALL lib$signal(s) END IF
SLEEP(60)
END
SUB out_band_routine(smg$r_out_of_band_table smg_info, &
LONG r0, LONG r1, LONG pc, LONG psl)
OPTION TYPE = EXPLICIT
%INCLUDE "$smgdef" %FROM %LIBRARY "sys$library:basic$starlet"
%INCLUDE "$ssdef" %FROM %LIBRARY "sys$library:basic$starlet"
EXTERNAL LONG FUNCTION smg$repaint_screen, &
smg$set_keypad_mode
DECLARE LONG s, keypad_mode
IF smg_info::smg$b_char = smg$k_trm_ctrlc
THEN
PRINT "Ctrl/C typed"
END IF
IF smg_info::smg$b_char = smg$k_trm_ctrlz
THEN
PRINT "Ctrl/Z typed"
STOP
END IF
IF smg_info::smg$b_char = smg$k_trm_ctrlw
THEN
s = smg$repaint_screen (smg_info::smg$l_pbd_id)
IF s <> ss$_normal THEN CALL lib$signal(s) END IF
keypad_mode = smg$m_keypad_application
s = smg$set_keypad_mode (smg_info::smg$l_user_arg, keypad_mode)
IF s <> ss$_normal THEN CALL lib$signal(s) END IF
END IF
SUBEND
|
SMG$SET_PHYSICAL_CURSOR
The Set Cursor on Physical Screen routine moves the physical cursor to
the specified position on the pasteboard.
Format
SMG$SET_PHYSICAL_CURSOR pasteboard-id ,pasteboard-row ,pasteboard-column
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 whose physical cursor is to move. The
pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
pasteboard-row
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the row to which the physical cursor moves. The
pasteboard-row argument is the address of a signed
longword that contains the row number.
pasteboard-column
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the column to which the physical cursor moves. The
pasteboard-column argument is the address of a signed
longword that contains the column number.
Description
SMG$SET_PHYSICAL_CURSOR moves the physical cursor to the specified row
and column position on the specified pasteboard. This routine should
not be used when pasteboard batching is in effect.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVARG
|
Invalid column.
|
|
SMG$_INVPAS_ID
|
Invalid
pasteboard-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
SMG$SET_TERM_CHARACTERISTICS
The Change Terminal Characteristics routine changes or retrieves the
terminal characteristics for a given pasteboard.
Format
SMG$SET_TERM_CHARACTERISTICS pasteboard-id
[,on-characteristics1]
[,on-characteristics2] [,off-characteristics1] [,off-characteristics2]
[,old-characteristics1] [,old-characteristics2] [,on-characteristics3]
[,off-characteristics3] [,old-characteristics3]
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 whose characteristics are to be changed or
retrieved. The pasteboard-id argument is the address
of an unsigned longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
on-characteristics1
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Bit mask that specifies the terminal characteristics to be set from
$TTDEF. The on-characteristics1 argument is the
address of an unsigned longword that contains the bit mask.
on-characteristics2
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Bit mask that specifies the terminal characteristics to be set from
$TT2DEF. The on-characteristics2 argument is the
address of an unsigned longword that contains the bit mask.
off-characteristics1
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Bit mask that specifies the terminal characteristics to be reset from
$TTDEF. The off-characteristics1 argument is the
address of an unsigned longword that contains the bit mask.
off-characteristics2
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Bit mask that specifies the terminal characteristics to be reset from
$TT2DEF. The off-characteristics2 argument is the
address of an unsigned longword that contains the bit mask.
old-characteristics1
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Retrieves the current terminal characteristics in the first group. The
old-characteristics1 argument is the address of an
unsigned longword that contains the bit mask.
old-characteristics2
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Retrieves the current terminal characteristics in the second group. The
old-characteristics2 argument is the address of an
unsigned longword that contains the bit mask.
on-characteristics3
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Bit mask that specifies the terminal characteristics to be set from
$TT3DEF. The on-characteristics3 argument is the
address of an unsigned longword that contains the bit mask.