Document revision date: 19 July 1999

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.

The following are line-oriented output routines:

• SMG$PUT_LINE writes lines of text to a virtual display.
• SMG$PUT_LINE_WIDE writes lines of double-width text to a virtual display.
• SMG$PUT_LINE_HIGHWIDE writes lines of double-width, double-height text to a virtual display.
• SMG$PUT_LINE_MULTI writes lines with multiple renditions to the 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; the SMG$CHANGE_RENDITION routine can be used 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, the rendition of a menu item can be altered 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. The following bits can be set:

SMG$M_BLINK	Specifies blinking characters.
SMG$M_BOLD	Specifies characters in higher-than-normal intensity.
SMG$M_REVERSE	Specifies characters in reverse video; that is, the opposite of the current rendition of the virtual display.
SMG$M_UNDERLINE	Specifies underlined characters.
SMG$M_INVISIBLE	Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8	Specifies a user-defined rendition.

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:

Display_attributes = ( SMG$M_REVERSE OR SMG$M_UNDERLINE )

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:

1. The logical or bitwise OR operation is performed on the mask containing the default video attributes and the rendition-set argument.
2. The logical or bitwise EXCLUSIVE OR operation is performed on the result of the previous OR operation and the rendition-complement argument.

The results of this scheme are shown in the following table:

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

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.

2.2.7 Drawing and Removing Drawn Lines and Characters

• SMG$DRAW_LINE constructs either horizontal or vertical lines, given the end points of those lines.
• SMG$DRAW_RECTANGLE draws a rectangle given the position of the upper left-hand corner and the lower right-hand corner.
• SMG$DRAW_CHAR draws one line-drawing character.

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

The following routines provide a way to output external text to the virtual display or terminal:

• SMG$PUT_HELP_TEXT outputs the help text for the specified topic in the virtual display provided.
• SMG$PUT_STATUS_LINE outputs a line of text to the terminal's hardware status line. Some terminals have a hardware status line at the bottom (25th line) of the screen. If this line has been set as host writable, you can use this routine to output a line of text in reverse video to the status line.

2.2.9 Reading from a Virtual Display

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.

2.2.10.1 Creating a 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.

2.2.10.2 Deleting a Viewport

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 SMG$PASTE_VIRTUAL_DISPLAY.

2.2.10.3 Pasting and Unpasting a Viewport

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.

2.2.10.4 Scrolling and Moving a Viewport

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.

2.2.10.5 Changing Viewport Characteristics

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.

2.2.11 Menus

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 view.

2.2.11.1 Creating a Menu

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.

2.2.11.2 Deleting a Menu

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.

2.2.11.3 Selecting from a Menu

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.

2.2.11.3.1 Default Mode

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 selected.

2.2.11.3.2 RETURN_IMMED Mode

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.

2.2.11.3.3 REMOVE_ITEM 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.

2.2.12 Saving a Virtual Display

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 pasteboard.

2.2.13 Changing Terminal Characteristics

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.

2.2.14 Hardcopy and File Output Operations

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.

2.2.14.2 Printing a Pasteboard

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.

2.2.14.3 Pasteboard Output by Means of a User-Supplied Routine

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.

2.3 Operational Controls

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.

2.3.1 Minimal Update

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.

2.3.2 Buffering

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.

	privacy and legal statement
5935PRO_002.HTML