HP OpenVMS Systems Documentation

HP OpenVMS Programming Concepts Manual

If your program needs to make a number of changes to a virtual display,
you can use SMG$ routines to make all of the changes before updating
the display. The SMG$BEGIN_DISPLAY_UPDATE routine causes output
operations to a pasted display to be reflected only in the display's
buffers. The SMG$END_DISPLAY_UPDATE routine writes the display's buffer
to the pasteboard.

The SMG$BEGIN_DISPLAY_UPDATE and SMG$END_DISPLAY_UPDATE routines
increment and decrement a counter. When this counter's value is 0,
output to the virtual display is sent to the pasteboard immediately.
The counter mechanism allows a subroutine to request and turn off
batching without disturbing the batching state of the calling program.

A second set of routines, SMG$BEGIN_PASTEBOARD_UPDATE and
SMG$END_PASTEBOARD_UPDATE, allow you to buffer output to a pasteboard
in a similar manner.

When using the SMG$ routines, you must take care not to corrupt the
mapping between the screen appearance and the internal representation
of the screen. Therefore, observe the following guidelines:

Mixing SMG I/O and other forms of I/O In general, do not use
any other form of terminal I/O while the terminal is active as a
pasteboard. If you do use I/O other than SMG I/O (for example, if you
invoke a subprogram that may perform non-SMG terminal I/O), first
invoke the SMG$SAVE_PHYSICAL_SCREEN routine and when the non-SMG I/O
completes, invoke the SMG$RESTORE_PHYSICAL_SCREEN routine, as
demonstrated in the following example:

Sharing the pasteboard A routine using the terminal screen
without consideration for its current contents must use the existing
pasteboard ID associated with the terminal and delete any virtual
displays it creates before returning control to the high-level code.
This guideline also applies to the program unit that invokes a
subprogram that also performs screen I/O. The safest way to clean up
your virtual displays is to call the SMG$POP_VIRTUAL_DISPLAY routine
and name the first virtual display you created. The following example
invokes a subprogram that uses the terminal screen:

Sharing virtual displays To share a virtual display created by
high-level code, the low-level code must use the virtual display ID
created by the high-level code; an invoking program unit must pass the
virtual display ID to the subprogram. To share a virtual display
created by low-level code, the high-level code must use the virtual
display ID created by the low-level code; a subprogram must return the
virtual display ID to the invoking program.

The following example permits a subprogram to use a virtual display
created by the invoking program unit:

Screen management input routines and the SYS$QIO and SYS$QIOW system
services allow you to perform I/O operations otherwise unavailable to
high-level languages. For example, you can allow a user to interrupt
normal program execution by typing a character and by providing a
mechanism for reading that character. You can also control such things
as echoing, time allowed for input, and whether data is read from the
type-ahead buffer.

Some of the operations described in the following sections require the
use of the SYS$QIO or SYS$QIOW system services. For more information
about the QIO system services, see the HP OpenVMS System Services Reference Manual and Chapter 23.

Other operations, described in the following sections, can be performed
by calling the SMG$ input routines. The SMG$ input routines can be used
alone or with the SMG$ output routines. Section 22.4 describes how to
use the input routines with the output routines. This section assumes
that you are using the input routines alone. To use the SMG$ input
routines, do the following:

Call SMG$CREATE_VIRTUAL_KEYBOARD to associate a logical keyboard
with a device or file specification (SYS$INPUT by default).
SMG$CREATE_VIRTUAL_KEYBOARD returns a keyboard identification number;
use that number to identify the device or file to the SMG$ input
routines.

Call an SMG$ input routine (SMG$READ_STRING or
SMG$READ_COMPOSED_LINE) to read data typed at the device associated
with the virtual keyboard.

When using the SMG$ input routines without the SMG$ output routines, do
not specify the optional VDID argument of the input routine.

The QIO system services enable you to detect a Ctrl/C or Ctrl/Y
interrupt at a user terminal, even if you have not issued a read to the
terminal. To do so, you must take the following steps:

Queue an asynchronous system trap (AST)---Issue the SYS$QIO or
SYS$QIOW system service with a function code of IO$_SETMODE modified by
either IO$M_CTRLCAST (for Ctrl/C interrupts) or IO$M_CTRLYAST (for
Ctrl/Y interrupts). For the P1 argument, provide the
name of a subroutine to be executed when the interrupt occurs. For the
P2 argument, you can optionally identify one longword
argument to pass to the AST subroutine.

Write an AST subroutine---Write the subroutine identified in the
P1 argument of the QIO system service and link the
subroutine into your program. Your subroutine can take one longword
dummy argument to be associated with the P2 argument
in the QIO system service. You must define common areas to access any
other data in your program from the AST routine.

If you press Ctrl/C or Ctrl/Y after your program queues the appropriate
AST, the system interrupts your program and transfers control to your
AST subroutine (this action is called delivering the AST). After your
AST subroutine executes, the system returns control to your program at
the point of interruption (unless your AST subroutine causes the
program to exit, or unless another AST has been queued). Note the
following guidelines for using Ctrl/C and Ctrl/Y ASTs:

ASTs are asynchronous---Since your AST subroutine does not know
exactly where you are in your program when the interrupt occurs, you
should avoid manipulating data or performing other mainline activities.
In general, the AST subroutine should either notify the mainline code
(for example, by setting a flag) that the interrupt occurred, or clean
up and exit from the program (if that is what you want to do).

ASTs need new channels to the terminal---If you try to access the
terminal with language I/O statements using SYS$INPUT or SYS$OUTPUT,
you may receive a redundant I/O error. You must establish another
channel to the terminal by explicitly opening the terminal.

Ctrl/C and Ctrl/Y ASTs are one-time ASTs---After a Ctrl/C or Ctrl/Y
AST is delivered, it is dequeued. You must reissue the QIO system
service if you wish to trap another interrupt.

Many ASTs can be queued---You can queue multiple ASTs (for the same
or different AST subroutines, on the same or different channels) by
issuing the appropriate number of QIO system services. The system
delivers the ASTs on a last-in, first-out (LIFO) basis.

Unhandled Ctrl/Cs turn into Ctrl/Ys---If the user enters Ctrl/C and
you do not have an AST queued to handle the interrupt, the system turns
the Ctrl/C interrupt into a Ctrl/Y interrupt.

DCL handles Ctrl/Y interrupts---DCL handles Ctrl/Y interrupts by
returning the user to DCL command level, where the user has the option
of continuing or exiting from your program. DCL takes precedence over
your AST subroutine for Ctrl/Y interrupts. Your Ctrl/Y AST subroutine
is executed only under the following circumstances:

If Ctrl/Y interrupts are disabled at DCL level (SET NOCONTROL_Y)
before your program is executed

If your program disables DCL Ctrl/Y interrupts with LIB$DISABLE_CTRL

If the user elects to continue your program after DCL interrupts it

You can dequeue Ctrl/C and Ctrl/Y ASTs---You can dequeue all Ctrl/C
or Ctrl/Y ASTs on a channel by issuing the appropriate QIO system
service with a value of 0 for the P1 argument (passed
by immediate value). You can dequeue all Ctrl/C ASTs on a channel by
issuing the SYS$CANCEL system service for the appropriate channel. You
can dequeue all Ctrl/Y ASTs on a channel by issuing the SYS$DASSGN
system service for the appropriate channel.

You can use SMG$ routines---You can connect to the terminal using
the SMG$ routines from either AST level or mainline code. Do not
attempt to connect to the terminal from AST level if you do so in your
mainline code.

Example 22-13 permits the terminal user to interrupt a display to see
how many lines have been typed up to that point.

You can detect input from the terminal even if you have not called
SMG$READ_COMPOSED_LINE or SMG$READ_STRING by using
SMG$ENABLE_UNSOLICITED_INPUT. This routine uses the AST mechanism to
transfer control to a subprogram of your choice each time the user
types at the terminal; the AST subprogram is responsible for reading
any input. When the subprogram completes, control returns to the point
in your mainline code where it was interrupted.

The SMG$ENABLE_UNSOLICITED_INPUT routine is not an SMG$ input routine.
Before invoking SMG$ENABLE_UNSOLICITED_INPUT, you must invoke
SMG$CREATE_PASTEBOARD to associate a pasteboard with the terminal and
SMG$CREATE_VIRTUAL_KEYBOARD to associate a virtual keyboard with the
same terminal.

SMG$ENABLE_UNSOLICITED_INPUT accepts the following arguments:

The pasteboard identification number (use the value returned by
SMG$CREATE_PASTEBOARD)

The name of an AST subprogram

An argument to be passed to the AST subprogram

When SMG$ENABLE_UNSOLICITED_INPUT invokes the AST subprogram, it passes
two arguments to the subprogram: the pasteboard identification number
and the argument that you specified. Typically, you write the AST
subprogram to read the unsolicited input with SMG$READ_STRING. Since
SMG$READ_STRING requires that you specify the virtual keyboard at which
the input was typed, specify the virtual keyboard identification number
as the second argument to pass to the AST subprogram.

Example 22-14 permits the terminal user to interrupt the display of a
series of arrays, and either to go on to the next array (by typing
input beginning with an uppercase N) or to exit from the program (by
typing input beginning with anything else).

Normally, if the user types at the terminal before your application is
able to read from that device, the input is saved in a special data
structure maintained by the system called the type-ahead buffer. When
your application is ready to read from the terminal, the input is
transferred from the type-ahead buffer to your input buffer. The
type-ahead buffer is preset at a size of 78 bytes. If the HOSTSYNC
characteristic is on (the usual condition), input to the type-ahead
buffer is stopped (the keyboard locks) when the buffer is within 8
bytes of being full. If the HOSTSYNC characteristic is off, the bell
rings when the type-ahead buffer is within 8 bytes of being full; if
you overflow the buffer, the excess data is lost. The TTY_ALTALARM
system parameter determines the point at which either input is stopped
or the bell rings.

You can clear the type-ahead buffer by reading from the terminal with
SMG$READ_STRING and by specifying TRM$M_TM_PURGE in the
modifiers argument. Clearing the type-ahead buffer has
the effect of reading only what the user types on the terminal after
the read operation is invoked. Any characters in the type-ahead buffer
are lost. The following example illustrates how to purge the type-ahead
buffer:

You can also clear the type-ahead buffer with a QIO read operation
modified by IO$M_PURGE (defined in $IODEF). You can turn off the
type-ahead buffer for further read operations with a QIO set mode
operation that specifies TT$M_NOTYPEAHD as a basic terminal
characteristic.

You can examine the type-ahead buffer by issuing a QIO sense mode
operation modified by IO$M_TYPEAHDCNT. The number of characters in the
type-ahead buffer and the value of the first character are returned to
the P1 argument.

The size of the type-ahead buffer is determined by the TTY_TYPAHDSZ
system parameter. You can specify an alternative type-ahead buffer by
turning on the ALTYPEAHD terminal characteristic; the size of the
alternative type-ahead buffer is determined by the TTY_ALTYPAHD system
parameter.

Normally, the system writes back to the terminal any printable
characters that the user types at that terminal. The system also writes
highlighted words in response to certain control characters; for
example, the system writes EXIT if the user enters Ctrl/Z. If the user
types ahead of your read, the characters are not echoed until you read
them from the type-ahead buffer.

You can turn off echoing when you invoke a read operation by reading
from the terminal with SMG$READ_STRING and by specifying
TRM$M_TM_NOECHO in the modifiers argument. You can
turn off echoing for control characters only by modifying the read
operation with TRM$M_TM_TRMNOECHO. The following example turns off all
echoing for the read operation:

You can also turn off echoing with a QIO read operation modified by
IO$M_NOECHO (defined in $IODEF). You can turn off echoing for further
read operations with a QIO set mode operation that specifies
TT$M_NOECHO as a basic terminal characteristic.