HP OpenVMS Systems Documentation
OpenVMS RTL Screen Management (SMG$) Manual
18.104.22.168 Line-Oriented Output
In contrast to the character-oriented output routines, the line-oriented routines treat a terminal as a sequential device. In this mode of operation, the program typically writes one line of information after another. Conceptually, this action corresponds to copying a stream of information (for example, a file) to a virtual display. Each routine call leaves the cursor at column 1 of the next row after the operation is complete.
2.2.6 Changing the Rendition of a Virtual Display
When you create a virtual display with the SMG$CREATE_VIRTUAL_DISPLAY routine, you specify a default rendition for all text that appears in the virtual display. You can change the rendition for an existing virtual display by calling either the SMG$CHANGE_VIRTUAL_DISPLAY or SMG$CHANGE_RENDITION routines.
The SMG$CHANGE_VIRTUAL_DISPLAY routine lets you change display attributes as well as video attributes for the entire display; you can use the SMG$CHANGE_RENDITION routine to change the video rendition of text already in the virtual display. For example, a program may maintain on the screen a list of values that change cyclically. When a number first changes, it can be displayed in reverse video to highlight it as a change on that cycle. On the next cycle, the same number must be displayed, but the reverse video should be removed, since the value of the number did not change. SMG$CHANGE_RENDITION provides an easy way to perform such changes.
Another use for the SMG$CHANGE_RENDITION routine is in implementing menus. Menu choices can be painted on the screen and the current choice highlighted by some video attribute, such as blinking characters or reverse video. As the user moves a cursor to change the selection, you can change the rendition of a menu item so that the current selection is always highlighted. Such changes in rendition can be made independently of the text contained in the menu choices.
To specify the default rendition for a virtual display, you use bit masks to set bits in the display attributes argument. You can set the following bits:
In order to use one of the user-defined renditions SMG$M_USER1 through SMG$M_USER8, you must provide an appropriate definition in the file TERMTABLE.TXT, using STRING_2 capabilities. The TERMTABLE definitions and STRING_2 capabilities are discussed in Chapter 5.
Any or all of the characteristics listed previously can be specified in the rendition of a virtual display. To specify more than one video attribute, you use the logical OR of these characteristics. For example, to specify underlined characters in reverse video as the default for a virtual display, you assign the logical OR of the appropriate bit masks to the display-attributes argument:
You then pass this display-attributes argument in the call to the SMG$CREATE_VIRTUAL_DISPLAY routine.
Screen management output routines let you override the default rendition so that you need not change the default each time you want to write text in some other rendition. Two arguments provide the means to override the default rendition: rendition-set and rendition-complement. The scheme for setting video attributes in these arguments is the same as that for setting the video attributes when you are creating a virtual display.
The default video attributes, the rendition-set argument, and the rendition-complement argument together specify the output rendition according to the following scheme:
The results of this scheme are shown in the following table:
Note that the effect of this scheme depends on the default attribute setting, not the current rendition of the virtual display. Thus, if you have used screen management output routines that explicitly specify a rendition, the current rendition may not match the default rendition for that virtual display.
If you want to erase a line drawn with SMG$DRAW_LINE or SMG$DRAW_RECTANGLE, use SMG$REMOVE_LINE. This routine removes the line but preserves the line-drawing characters at any line intersections.
Like all screen management routines, these are device independent. If the resulting line is to be drawn on a VT100 terminal, the VT100 line-drawing character set is used. If the same line is drawn on a VT52 terminal (which does not have this hardware capability), the lines are automatically approximated by the use of the plus sign (+), the vertical bar (|), and the dash (--). Your program does not have to supply different character codes for different types of terminals.
In addition, these routines automatically provide an appropriate character at the intersection of two lines. For example, if a program writes a horizontal line directly to the screen and then writes a vertical line that intersects the horizontal line, you would normally see what appears in Figure 2-7.
Figure 2-7 Lines Drawn Without SMG$DRAW_LINE
If these same lines are drawn using SMG$DRAW_LINE, the screen shows what appears in Figure 2-8.
Figure 2-8 Lines Drawn With SMG$DRAW_LINE
2.2.8 Displaying External Text
The following routines provide a way to output external text to the virtual display or terminal:
Since a virtual display can be very large, it is not always possible to show the entire display on the screen at one time. The user must repaste a large virtual display in order 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 in order to view
different pieces of the virtual display. The viewport is associated
with the virtual display so that any output operation performed on the
virtual display is reflected on the viewport.
The SMG$CREATE_VIEWPORT routine creates a viewport associated with a
particular virtual display. The virtual display must be created before
the viewport can be created, and you can only create one viewport for
each virtual display. In order to make the viewport visible, you have
to paste the virtual display by calling the SMG$PASTE_VIRTUAL_DISPLAY
routine; only the portion of the virtual display that falls inside the
viewport is visible.
The SMG$DELETE_VIEWPORT routine deletes a viewport. When you invoke
this routine, the viewport is automatically unpasted from any
pasteboards to which it is pasted. It is important to note, however,
that the virtual display associated with the viewport has not been
deleted. You can make the virtual display visible by calling
The SMG$PASTE_VIRTUAL_DISPLAY routine pastes either a viewport or a virtual display to a pasteboard. Once you have associated a viewport with a virtual display, any call to SMG$PASTE_VIRTUAL_DISPLAY uses the viewport instead of the virtual display. That is, once a viewport for a virtual display is created, the only part of that virtual display that you can view is the rectangular region contained in the viewport. To unpaste a viewport without deleting it, you can invoke SMG$UNPASTE_VIRTUAL_DISPLAY.
If you create a viewport when the associated virtual display is already
pasted, the viewport is not visible. A call to
SMG$PASTE_VIRTUAL_DISPLAY unpastes the virtual display and pastes the
viewport in its place.
A viewport associated with a virtual display may be situated entirely or partially on the pasteboard, or totally off the pasteboard. However, a viewport cannot extend beyond its associated virtual display. If you try to extend a viewport beyond the boundaries of its virtual display, the Screen Management Facility automatically truncates the viewport to fit into the virtual display.
To scroll a viewport, scroll the virtual display associated with the viewport by calling SMG$SCROLL_VIEWPORT. In actuality, the coordinates of the viewport are changing as it moves over the virtual display to simulate scrolling; however, the location of the viewport on the screen does not change. With the SMG$SCROLL_VIEWPORT routine, you can specify the direction (up, down, left, or right) that you want to scroll.
You can move a viewport by calling SMG$CHANGE_VIEWPORT. This routine
lets you specify a new starting location and size for the viewport. By
changing the starting location and size of the viewport, you can, in
effect, move the window around the virtual display.
The SMG$GET_VIEWPORT_CHAR routine lets you retrieve the current characteristics of a viewport. The characteristics of a viewport consist of the starting and ending row and column positions for the viewport. You can use this routine in conjunction with the SMG$CHANGE_VIEWPORT routine, which lets you change the starting and ending positions of an existing viewport.
To change any characteristic of a viewport other than its starting or ending position, use the SMG$CHANGE_VIRTUAL_DISPLAY routine. Any change you make to a virtual display is reflected in its associated viewport.
For example, if a virtual display has a border, so does the associated
viewport. If the virtual display does not have a border, then neither
does the viewport. If you want to add or delete a border to a viewport,
add or delete the border to the virtual display using the
SMG$CHANGE_VIRTUAL_DISPLAY routine. This change is automatically
reflected on the viewport.
The Screen Management Facility provides the capability to create and
make selections from a menu. The menu can be a block menu, a vertical
menu, or a horizontal menu. A block menu is a two-dimensional array of
items and is the main type of menu provided. A vertical menu displays
the menu choices in a single column, while a horizontal menu displays
the choices in a single row. Any menu items that do not fit within the
bounds of the viewport are not displayed until they are scrolled into
The SMG$CREATE_MENU routine creates a menu in the scrolling region of a specified virtual display. (By default, the scrolling region is the entire virtual display. You can use SMG$SET_DISPLAY_SCROLL_REGION to change the scrolling region.) Specify a format for the menu (block, vertical, or horizontal) when you create it.
A block menu is the default format for a menu. The items in the menu are passed to the routine in the form of a static array of character strings. The menu choices are single spaced by default, but you can request double spacing. Four spaces separate each menu item horizontally. In addition, you can request that the menu choices be displayed in fixed format columns, where the width of the column is equal to the size of the fixed-length strings being passed.
It is important to note that each virtual display can only contain one
menu. Also, after calling SMG$CREATE_MENU, you must not output any
characters to the display that disturb the area containing the menu;
otherwise, the results are unpredictable. The menu is output in the
scrolling region of the virtual display.
The SMG$DELETE_MENU routine deletes a menu by discontinuing access to
the menu choices in the specified virtual display. Additionally, you
can request that SMG$DELETE_MENU remove all menu choices from the
display when the menu is deleted.
Once you have created a menu, you can select items from that menu using the SMG$SELECT_FROM_MENU routine. When you move around the menu items, the currently selected item is highlighted in reverse video by default. You can specify a default selection that is highlighted and becomes the current item when you call SMG$SELECT_FROM_MENU. If you do not specify a default selection item, the previously selected item remains highlighted.
SMG$SELECT_FROM_MENU provides three modes of operation; you can switch
between these modes using the flags parameter. Each
mode is described in the following sections.
The default mode of operation for the SMG$SELECT_FROM_MENU routine is
invoked by omitting the flags parameter. In this mode,
you can move around the menu items using the arrow key and, after
selecting an item, you can continue making additional selections. The
default mode also lets you "reselect" items that were already
Specifying the SMG$M_RETURN_IMMED value for the flags parameter of the SMG$SELECT_FROM_MENU routine allows you to move around the menu choices with the arrow keys; however, pressing any other key returns control to the user. Ctrl/Z selects the current item and returns SMG$_EOF. Any other key entered selects the current item.
Use SMG$M_RETURN_IMMED mode if you want key definitions other than
those provided by the default mode.
If you specify the SMG$M_REMOVE_ITEM value for the flags parameter of SMG$SELECT_FROM_MENU, you cannot "reselect" an item in the menu, although the item remains in the menu. It appears in the default rendition for the virtual display containing the menu.
If you specify a default selection item while in this mode, and that
item has already been selected, the first "selectable" item
in the menu is highlighted. If none of the items is selectable, an
error is returned.
The SMG$SAVE_VIRTUAL_DISPLAY routine saves the contents of a virtual
display in a file. The text, renditions, and all the attributes needed
to reconstruct the virtual display are saved, but menu, viewport, and
subprocess contexts are not saved. You cannot print the resulting file.
To restore the virtual display, you can use SMG$LOAD_VIRTUAL_DISPLAY,
which creates a new virtual display and loads it with the saved
contents of the display. The new virtual display is not pasted to any
The SMG$SET_TERM_CHARACTERISTICS routine changes or retrieves the
terminal characteristics for a given pasteboard. With this routine, you
can control multiple terminal characteristics in a single routine call.
The Screen Management Facility provides a way for you to send output to a hardcopy device or to a file, instead of to a terminal screen. Although you cannot constantly update the display as you do with a video screen, you can capture the image of the current pasteboard at any point and send that image to either a hardcopy device or file.
If the output device for a screen management routine is a file or a hardcopy terminal, the output for screen updating is inappropriate for the image. The SMG$SNAPSHOT routine sends the current screen image (that is, the visible portion of the pasteboard) to the file or hardcopy terminal. To determine if you should use SMG$SNAPSHOT, check the type-of-terminal parameter returned by SMG$CREATE_PASTEBOARD.
The SMG$SNAPSHOT_TO_PRINTER routine prints the current pasteboard contents to a printer attached to the terminal's printer port.
Pasteboard batching does not affect the SMG$SNAPSHOT or
SMG$SNAPSHOT_TO_PRINTER routine. If you enable pasteboard batching with
the SMG$BEGIN_PASTEBOARD_UPDATE routine, a buffer is created that saves
all output to a pasteboard until you disable batching with a call to
SMG$END_PASTEBOARD_UPDATE. When you call SMG$SNAPSHOT or
SMG$SNAPSHOT_TO_PRINTER, you get a snapshot of that current pasteboard
buffer --- not what is possibly a stale screen image.
The SMG$PRINT_PASTEBOARD routine prints a pasteboard on a line printer.
The routine creates a file and fills it with the contents of a
specified pasteboard. Once the file is filled, SMG$PRINT_PASTEBOARD
submits the file to the specified print queue.
The SMG$PUT_PASTEBOARD routine lets you access the contents of a
pasteboard. You specify an action routine that is called once for each
line of the pasteboard. Using this action routine, you can perform
whatever action is necessary for each row of the pasteboard returned.
This section describes the screen management routines that control special modes of operation: minimal update, buffering, and whether or not tabs are used in updating. These modes let you optimize the manner in which information is actually written to the screen. To invoke these modes, use the SMG$CONTROL_MODE routine.
Normally, you need not be concerned with these modes; the Screen
Management Facility optimizes output so that characters appear to be
displayed on the screen immediately. For some applications, however,
you may want to take advantage of these mode settings. The following
sections describe these modes of operation.
By default, the Screen Management Facility attempts to minimize the
number of characters written to the screen by rewriting only the parts
of the screen that have changed. However, the Screen Management
Facility also supports nonminimal updating, in which all lines affected
by a change are redrawn, beginning at the first changed character and
continuing to the end of the line.
By default, output operations cause an immediate change on the screen by sending many small, partially filled buffers to the terminal instead of updating the screen when the buffer is full. Minimizing the number of these I/O transactions by enabling buffering mode results in faster program execution.
In buffering mode, the Screen Management Facility writes the terminal buffer to the screen only when the buffer is full. Thus, several output operations may be performed before the results appear on the screen. Because this delay is not acceptable for many applications, a special routine, SMG$FLUSH_BUFFER, is provided for use with buffering. SMG$FLUSH_BUFFER forces the buffer to be written to the terminal whether or not it is full. This routine is useful for an application that can usually accept delayed output but occasionally requires an immediate screen update. Applications that usually need immediate changes on the screen should not enable buffering.