OpenVMS RTL Screen Management (SMG$) Manual
A pasteboard is a logical structure for performing output operations to
a terminal screen. You can think of a pasteboard as a two-dimensional
area on which you place and manipulate screen displays. A pasteboard is
always associated with a physical device or an OpenVMS RMS file, but a
pasteboard may be larger or smaller than the physical screen. Each
output device has only one pasteboard.
Create a pasteboard by calling the SMG$CREATE_PASTEBOARD routine.
Specify the physical device to be associated with the pasteboard as an
argument. SMG$CREATE_PASTEBOARD returns a unique pasteboard identifier
(pasteboard-id), which is used in subsequent routine
calls where a pasteboard identifier is needed. For example, use the
pasteboard-id to specify the physical terminal screen
on which to paste a virtual display. SMG$CREATE_PASTEBOARD also returns
the numbers of rows and columns available on the associated device as
output arguments. You can use this information to create a virtual
display the size of the physical screen. (Virtual displays are
discussed in the next section.)
Think of a pasteboard as a logical coordinate system in which the
relative orientation of one or more virtual displays is specified. (The
pasteboard itself has no physical boundaries, but the physical screen
does.) Figure 1-1 depicts the pasteboard coordinate system.
Figure 1-1 Pasteboard Coordinate System
The origin (cellular position 1,1) corresponds to the upper left-hand
corner of the physical screen. The numbering of rows and columns starts
from this origin. For example, on a VT200 series terminal, with 24 rows
and 80 columns, the first 24 rows and first 80 columns of the
pasteboard coordinate system map to the physical screen. Note that you
can place a virtual display anywhere in this coordinate system, not
only in the quadrant that corresponds to the physical screen. Thus a
virtual display, when pasted (that is, positioned on the pasteboard),
may be invisible or only partly visible on the physical screen.
Pasteboards are deleted, or disassociated, from a particular device by
the SMG$DELETE_PASTEBOARD routine. When a pasteboard is deleted, all
virtual displays pasted to it are unpasted.
Once a pasteboard has been created, you can learn about its attributes
(particularly its dimensions) by calling SMG$GET_PASTEBOARD_ATTRIBUTES.
You can change the characteristics of a pasteboard by calling
SMG$CHANGE_PBD_CHARACTERISTICS if the associated physical device allows
the change. For example, if the device is a VT100, you can change the
width of the pasteboard from 80 columns to 132 columns.
When the pasteboard is created, the Screen Management Facility clears
the screen by default; however, you can request that the screen be left
as it is. In addition, you can call SMG$ERASE_PASTEBOARD to erase the
screen. You can also call SMG$PRINT_PASTEBOARD to print the contents of
the pasteboard on a line printer.
1.2 Virtual Displays
A virtual display is a rectangular part of the terminal screen to which
a program writes data using routine calls. Virtual displays are the
main focus of the Screen Management Facility. When you create images to
be placed on the screen, think in terms of virtual displays rather than
in terms of the physical screen. This logical separation of the virtual
display from the physical screen allows a main program to reposition
virtual displays, so that a subroutine that writes to the virtual
display need not be involved with positioning the display on the
When you associate a virtual display with a pasteboard, it is
pasted. When you remove the display from the
pasteboard, it is unpasted. A virtual display is not
displayed unless it is pasted to a pasteboard. (See Section 2.1.1 for
more information on pasting virtual displays.)
The number of virtual displays that a program can create and maintain
is limited only by the virtual address space available. A single
virtual display can be pasted to more than one pasteboard at a time;
thus, a program maintains only the virtual display. Any change to a
virtual display is automatically reflected in each pasteboard to which
the display is pasted (and its associated terminal screen).
Create a virtual display by calling the SMG$CREATE_VIRTUAL_DISPLAY
The call must specify the number of rows and columns that make up the
virtual display. The program can also request certain display and video
attributes to be applied to the display.
SMG$CREATE_VIRTUAL_DISPLAY returns a unique virtual display identifier
(display-id). This display-id
identifies the virtual display in subsequent routine calls that modify
A program or subroutine can determine which attributes and dimensions
are associated with a virtual display by calling the
SMG$GET_DISPLAY_ATTR routine. If you have multiple virtual displays
pasted to a pasteboard, you can use SMG$LIST_PASTING_ORDER to determine
the order in which the virtual displays are pasted.
If you do not specify video attributes, SMG applies default video
characteristics to output. Renditions are video
characteristics that you can turn on or off; they include bolding,
blinking, reverse video, and underlined text. Display attributes are
the characteristics that specify whether or not the display:
- Is bordered (the border may be labeled).
- Echoes carriage control characters (like form feed, vertical tab,
and so on).
- Shows the user a diamond-shaped icon when text extends past the
rightmost position in the display.
You can change the video and display attributes you specify when you
create a virtual display. The SMG$CHANGE_RENDITION routine lets you
change video attributes while the SMG$CHANGE_VIRTUAL_DISPLAY routine
lets you change both video and display attributes. For example, you can
redimension a virtual display with the latter routine. When you
redimension a virtual display, the data in it is copied to the
redimensioned display; that is, as much of the current contents
(starting with row 1, column 1) as will fit in the newly dimensioned
display are preserved.
You can delete a virtual display by calling the
SMG$DELETE_VIRTUAL_DISPLAY routine. See Section 2.1.5 for more
information on the delete operation.
Since a virtual display can be very large, it is not always possible to
show the entire display on the screen at one time. You must repaste a
large virtual display to view a different portion of it. A viewport
associated with the virtual display makes this job easier.
Viewporting refers to the process of moving a rectangular viewing area
around on a virtual display to view different pieces of the virtual
display. The viewport is associated with the virtual display so that
any output operation that you perform on the virtual display is
reflected on the viewport. You can create, delete, paste, unpaste,
scroll, and move a viewport. See Section 2.2.10 for more information on
1.4 Virtual Keyboards
A virtual keyboard is a logical structure for input operations, just as
a pasteboard is a logical structure for output operations. The
advantage of using virtual keyboards is device independence. When using
the screen management input routines, you need not worry about the
terminal type. For example, your program need not know which line
terminators a particular terminal uses; the screen management routines
map the different terminator character sequences into a uniform set of
function codes. (See Section 3.6 for more information about terminator
A virtual keyboard is usually associated with a physical keyboard on a
terminal, but it may also be any file accessible through OpenVMS RMS.
There is a many-to-one correspondence between virtual keyboards and an
input device or file.
Establish a source for input (a virtual keyboard) by calling the
SMG$CREATE_VIRTUAL_KEYBOARD routine. Delete virtual keyboards by
calling the SMG$DELETE_VIRTUAL_KEYBOARD routine.
Once you have created a virtual keyboard, you can obtain data from it
with the SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING,
or SMG$READ_VERIFY routine. SMG$READ_COMPOSED_LINE reads a line
composed of ordinary keystrokes and predefined strings associated with
keypad and control keys; it provides an easy way to code an interface
for command-oriented utilities by providing single-key command
capabilities. Use the SMG$READ_KEYSTROKE routine to read one keystroke
entered at the keyboard. SMG$READ_STRING reads a string composed of
characters and a terminator; this routine is general purpose and
flexible, providing access to many features of the OpenVMS terminal
driver. Use the SMG$READ_VERIFY routine to read formatted input. You
can abort all types of read operations by calling the SMG$CANCEL_INPUT
Screen Management Output Operations
This chapter discusses the output operations provided by the Screen
Management Facility. These output operations are described in terms of
composition operations (operations that, in effect, create an image on
a terminal screen) and output operations through virtual displays.
2.1 Composition Operations
Composition operations are the routines you use to manipulate virtual
displays on a pasteboard and thus to create an image on a terminal
screen. These operations include pasting, unpasting, repasting, moving
and popping virtual displays, checking virtual displays for occlusion,
and listing the pasting order.
2.1.1 Paste Operation
Virtual displays are visible on a physical device only while they are
pasted to a pasteboard. Paste a display to a pasteboard
by calling SMG$PASTE_VIRTUAL_DISPLAY and specifying the pasteboard
coordinates as the origin of the virtual display. (The origin is the
top left-hand corner.) The pasteboard itself has no boundaries, but of
course the physical screen does. Thus you can paste a display to a
pasteboard in such a way that some or all of the display does not
appear on the terminal screen.
Pasting virtual displays to a pasteboard is a logical operation that
maps the contents of a virtual display to a location on the screen by
specifying the row and column of the pasteboard that coincide with row
1 and column 1 of the virtual display. For example, pasting a 6-row
virtual display "A" to pasteboard rows 1 through 6 and
pasting a second 6-row virtual display "B" to pasteboard rows
7 through 12 places virtual display "B" immediately below
virtual display "A" on the screen. See Figure 2-1.
Figure 2-1 Paste Operation
2.1.2 Unpaste Operation
You can make a virtual display disappear from the physical screen using
the SMG$UNPASTE_VIRTUAL_DISPLAY routine. To continue the example in
Section 2.1.1, if virtual display "B" is unpasted, the results
appear as in Figure 2-2.
Figure 2-2 Unpaste Operation
Unpasting a virtual display does not destroy the virtual display or its
contents; it simply removes the display from the pasteboard.
Displays can overlap partially or completely, depending on their size,
where they are pasted, and the order in which they are pasted. This
overlap is called occlusion. Unpasting the top display
causes the underlying displays to be visible.
2.1.3 Repaste Operation
You can move a virtual display to a new location on the pasteboard by
SMG$REPASTE_VIRTUAL_DISPLAY, which prevents the screen from being left
blank during the unpaste and repaste operations. Figure 2-3 shows the
effect of repasting the second display farther to the right. Notice
that display 2 has been pulled out of its former pasting order and is
now uppermost --- hiding part of display 3, which was uppermost before
the repasting operation.
Figure 2-3 Repaste Operation
2.1.4 Move Operation
You can also move a virtual display around the pasteboard while
preserving its pasting order by calling the SMG$MOVE_VIRTUAL_DISPLAY
routine. Figure 2-4 shows the effect of moving the second display to
the right. Note the difference between the unpaste and move operations:
the pasting order does not change with a move. Thus, display 2 remains
partially occluded by display 3.
Figure 2-4 Move Operation
The routine SMG$MOVE_TEXT allows you to move text from one virtual
display to another virtual display. Given two points in opposite
corners of the rectangle, SMG$MOVE_TEXT determines the desired width
and height. This routine moves the attributes of the first virtual
display, thus moving the rectangle of text and erasing it from the
first virtual display.
2.1.5 Delete and Pop Operations
The unpaste, repaste, and move operations shown thus far do not destroy
the virtual displays affected. You can remove and delete a virtual
display by calling the SMG$DELETE_VIRTUAL_DISPLAY routine.
You can also remove a number of virtual displays from a pasteboard and
delete them in a single operation by calling SMG$POP_VIRTUAL_DISPLAY.
This routine unpastes and deletes the
specified virtual display and all other virtual displays that were
pasted after the one specified.
The pop operation is useful in a modular environment. For example, you
can call a subroutine and pass only the pasteboard-id
upon which it is to produce output. The subroutine then creates
additional virtual displays and pastes them to the indicated
pasteboard. When the subroutine returns control to its caller, it
returns the display-id of the first virtual display it
has pasted. The calling program can then undo the effects of the
subroutine by calling SMG$POP_VIRTUAL_DISPLAY, passing the identifier
of the virtual display returned by the subroutine. This technique
minimizes the amount of information to be passed between the calling
program and its subroutine. Figure 2-5 shows the effects of popping
Figure 2-5 Pop Operation
2.1.6 Occlusion Check Operation
You may want to know if a display is occluded, as pasted on a given
pasteboard. You can find this out by calling the
For example, in the configuration in Figure 2-6, displays 1 and 2
would be reported as being occluded, while displays 3 and 4 would be
reported as not occluded. You cannot use this test to determine which
display is pasted uppermost on the pasteboard; it determines only
whether or not the display, as pasted, is occluded.
Figure 2-6 Occlusion Check
If you have multiple virtual displays pasted to a pasteboard, you can
use SMG$LIST_PASTING_ORDER to determine the order in which virtual
displays are pasted. This routine returns the identifier of the first,
or bottommost, virtual display pasted. Call SMG$LIST_PASTING_ORDER in a
loop until the identifiers of all the succeeding pasted virtual
displays are returned.
The routine SMG$LIST_PASTEBOARD_ORDER gives you the inverse of the
information returned by SMG$LIST_PASTING_ORDER.
SMG$LIST_PASTEBOARD_ORDER returns the identifier of the first, or
bottommost, pasteboard to which the specified virtual display is pasted.
2.2 Output Through Virtual Displays
This section describes the screen management routines used to perform
output through virtual displays.
Writing to a virtual display is similar to writing directly to the
terminal. However, writing to a virtual display is done entirely by
calling screen management routines. The Screen Management Facility
allows you to erase the screen, set the cursor position, and scroll
output text. Text is arranged in the virtual display's buffer, so you
do not need to paste before it can receive output. When you write to
the physical screen, you are limited by the physical boundaries of the
screen. Similarly, screen management output operations are confined to
the boundaries of the virtual display: you cannot write text beyond the
last column of a virtual display.
You cannot see changes to a virtual display on the screen unless the
virtual display is pasted to the part of the pasteboard that is visible
on the screen. If the virtual display is not pasted, or if it is pasted
in a position that is not visible, such changes are reflected only in
the internal database that represents the virtual display.
2.2.1 Cursor Position
When a virtual display is first created, the virtual cursor is
positioned at row 1, column 1 of the virtual display. Various output
operations to the virtual display move the virtual cursor, just as
output operations do on a physical terminal.
Do not confuse the position of the virtual cursor in a virtual display
with the position of the physical cursor on the screen. Many virtual
displays can be pasted to a pasteboard and are therefore visible at the
same time on the physical screen. Although each virtual display has an
associated virtual cursor position, only one of the virtual cursor
positions for all these displays corresponds to the physical
cursor---usually the cursor position of the virtual display most
You can determine the current position of the virtual cursor within a
virtual display by calling the SMG$RETURN_CURSOR_POS routine.
This routine returns the current virtual cursor row and column.
For programming convenience, you can also obtain this information
through two separate routines, SMG$CURSOR_ROW and SMG$CURSOR_COLUMN,
which operate as functions. These two routines make it easy to code
constructions like this:
IF SMG$CURSOR_ROW ( Display-id ) > Max-row
To obtain this information with SMG$RETURN_CURSOR_POS, you would write
CALL SMG$RETURN_CURSOR_POS ( Display-id, Cursor-row, Cursor-column )
IF Cursor-row > Max-row
SMG$RETURN_CURSOR_POS requires you to define two local variables,
cursor-row and cursor-column, which you might not
need except to perform this test. However, this routine yields both the
row and column in a single routine call.
The following routines set the virtual cursor position in a virtual
- SMG$SET_CURSOR_ABS sets the virtual cursor to the specified
position in the virtual display.
- SMG$SET_CURSOR_REL sets the virtual cursor position to the
specified offset from the current display cursor position.
- SMG$HOME_CURSOR sets the virtual cursor to the virtual display's
home position (row 1, column 1).
2.2.2 Deletion Operations
The following routines delete parts of a virtual display:
SMG$DELETE_CHARS deletes one or more characters on a single line.
Character positions removed by this routine are replaced with the
characters to the right of the deleted characters on the same line.
Character positions opened at the end of the line are filled with
SMG$DELETE_LINE deletes one or more entire lines. Lines removed by this
routine are filled by the lines immediately below the deleted lines.
New lines introduced into the bottom of the virtual display are blank.
2.2.3 Erasure Operations
During an erase operation, the erased portion of the virtual display is
filled with blanks. No other parts of the virtual display are
The following routines erase parts of a virtual display:
- SMG$ERASE_CHARS erases a specified number of characters within a
- SMG$ERASE_COLUMN erases the specified portion of the virtual
display from the given position to the end of the column.
- SMG$ERASE_LINE erases characters in a line from the specified
starting position to the end of the line.
- SMG$ERASE_DISPLAY erases all or part of a virtual display.
2.2.4 Insertion Operations
The following routines insert text into a virtual display:
- SMG$INSERT_CHARS deposits the specified string of characters in the
indicated starting position. Existing characters in these positions are
shifted to the right to make room for each character as it is inserted.
Characters shifted beyond the rightmost column are discarded.
- SMG$INSERT_LINE inserts the specified line of text in the position
indicated and scrolls existing lines in the virtual display up or down
to make room for the inserted lines. Lines scrolled above the top line
or below the bottom line of the virtual display are discarded.
2.2.5 Writing Operations
The Screen Management Facility provides two types of routines for
writing text to a virtual display: character-oriented output and
line-oriented output. The following sections describe these routines.
188.8.131.52 Character-Oriented Output
Use the character-oriented output routines when you are using a virtual
display as a direct-access device. In this mode of operation, the
program explicitly sets the cursor in the virtual display and deposits
text there. Since the next output operation usually has no spatial
relationship to the previous one, you need to control the cursor
position and display scrolling.
The following are character-oriented output routines:
- SMG$PUT_CHARS writes normal characters to a virtual display.
- SMG$PUT_CHARS_WIDE writes double-width characters to a virtual
- SMG$PUT_CHARS_HIGHWIDE writes double-width, double-height
characters to a virtual display.
- SMG$PUT_CHARS_MULTI writes characters with multiple renditions to
the virtual display.
You cannot mix different types of characters on a single line in a