Document revision date: 19 July 1999

Use the SMG$CREATE_PASTEBOARD routine to create a pasteboard and associate it with a physical device. SMG$CREATE_PASTEBOARD returns a unique pasteboard identification number; use that number to refer to the pasteboard in subsequent calls to SMG$ routines. After associating a pasteboard with a device, your program references only the pasteboard. The screen management facility performs all necessary operations between the pasteboard and the physical device. Example 9-4 creates a pasteboard.

Example 9-4 Creating a Pasteboard

STATUS = SMG$CREATE_PASTEBOARD (PBID, ROWS, COLUMNS) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))

9.4.3.1 Erasing a Pasteboard

When you create a pasteboard, the screen management facility clears the screen by default. To clear the screen yourself, invoke the SMG$ERASE_PASTEBOARD routine. Any virtual displays associated with the pasteboard are removed from the screen, but their contents in memory are not affected. The following example erases the screen:

STATUS = SMG$ERASE_PASTEBOARD (PBID) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))

9.4.3.2 Deleting a Pasteboard

Invoking the SMG$DELETE_PASTEBOARD routine deletes a pasteboard, making the screen unavailable for further pasting. The optional second argument of the SMG$DELETE_PASTEBOARD routine allows you to indicate whether the routine clears the screen (the default) or leaves it as is. The following example deletes a pasteboard and clears the screen:

STATUS = SMG$DELETE_PASTEBOARD (PBID) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))

By default, the screen is erased when you create a pasteboard. Generally, you should erase the screen at the end of a session.

9.4.3.3 Setting Screen Dimensions and Background Color

The SMG$CHANGE_PBD_CHARACTERISTICS routine sets the dimensions of the screen and its background color. You can also use this routine to retrieve dimensions and background color. To get more detailed information about the physical device, use the SMG$GET_PASTEBOARD_ATTRIBUTES routine. Example 9-5 changes the screen width to 132 and the background to white, then restores the original width and background before exiting.

Example 9-5 Modifying Screen Dimensions and Background Color

. . . INTEGER*4 WIDTH, 2 COLOR INCLUDE '($SMGDEF)' ! Get current width and background color STATUS = SMG$CHANGE_PBD_CHARACTERISTICS (PBID,, 2 WIDTH,,,, 2 COLOR) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) ! Change width and background color STATUS = SMG$CHANGE_PBD_CHARACTERISTICS (PBID, 2 132,,,, 2 SMG$C_COLOR_WHITE) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) . . . ! Restore width and background color STATUS = SMG$CHANGE_PBD_CHARACTERISTICS (PBID, 2 WIDTH,,,, 2 COLOR) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))

9.4.4 Virtual Displays

You write to virtual displays, which are logically configured as rectangles, by using the SMG$ routines. The dimensions of a virtual display are designated vertically as rows and horizontally as columns. A position in a virtual display is designated by naming a row and a column. Row and column numbers begin at 1.

9.4.4.1 Creating a Virtual Display

Use the SMG$CREATE_VIRTUAL_DISPLAY routine to create a virtual display. SMG$CREATE_VIRTUAL_DISPLAY returns a unique virtual display identification number; use that number to refer to the virtual display.

Optionally, you can use the fifth argument of SMG$CREATE_VIRTUAL_DISPLAY to specify one or more of the following video attributes: blinking, bolding, reversing background, and underlining. All characters written to that display will have the specified attribute unless you indicate otherwise when writing text to the display. The following example makes everything written to the display HEADER_VDID appear bold by default:

INCLUDE '($SMGDEF)' . . . STATUS = SMG$CREATE_VIRTUAL_DISPLAY (1, ! Rows 2 80, ! Columns 2 HEADER_VDID,, 2 SMG$M_BOLD)

You can border a virtual display by specifying the fourth argument when you invoke SMG$CREATE_VIRTUAL_DISPLAY. You can label the border with the routine SMG$LABEL_BORDER. If you use a border, you must leave room for it: a border requires two rows and two columns more than the size of the display. The following example places a labeled border around the STATS_VDID display. As pasted, the border occupies rows 2 and 13 and columns 1 and 57.

STATUS = SMG$CREATE_VIRTUAL_DISPLAY (10, ! Rows 2 55, ! Columns 2 STATS_VDID, 2 SMG$M_BORDER) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) STATUS = SMG$LABEL_BORDER (STATS_VDID, 2 'statistics') IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) STATUS = SMG$PASTE_VIRTUAL_DISPLAY (STATS_VDID, 2 PBID, 2 3, ! Row 2 2) ! Column

9.4.4.2 Pasting Virtual Displays

To make a virtual display visible, paste it to a pasteboard using the SMG$PASTE_VIRTUAL_DISPLAY routine. You position the virtual display by specifying which row and column of the pasteboard should contain the upper left corner of the display. Example 9-6 defines two virtual displays and pastes them to one pasteboard.

Example 9-6 Defining and Pasting a Virtual Display

. . . INCLUDE '($SMGDEF)' INTEGER*4 PBID, 2 HEADER_VDID, 2 STATS_VDID INTEGER*4 STATUS, 2 SMG$CREATE_PASTEBOARD, 2 SMG$CREATE_VIRTUAL_DISPLAY, 2 SMG$PASTE_VIRTUAL_DISPLAY ! Create pasteboard for SYS$OUTPUT STATUS = SMG$CREATE_PASTEBOARD (PBID) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) ! Header pastes to first rows of screen STATUS = SMG$CREATE_VIRTUAL_DISPLAY (3, ! Rows 2 78, ! Columns 2 HEADER_VDID, ! Name 2 SMG$M_BORDER) ! Border IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) STATUS = SMG$PASTE_VIRTUAL_DISPLAY (HEADER_VDID, 2 PBID, 2 2, ! Row 2 2) ! Column IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) ! Statistics area pastes to rows 5 through 15, ! columns 2 through 56 STATUS = SMG$CREATE_VIRTUAL_DISPLAY (10, ! Rows 2 55, ! Columns 2 STATS_VDID, ! Name 2 SMG$M_BORDER) ! Border IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) STATUS = SMG$PASTE_VIRTUAL_DISPLAY (STATS_VDID, 2 PBID, 2 5, ! Row 2 2) ! Column IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) . . .

Figure 9-1 shows the screen that results from Example 9-6.

Figure 9-1 Defining and Pasting Virtual Displays

You can paste a single display to any number of pasteboards. Any time you change the display, all pasteboards containing the display are automatically updated.

A pasteboard can hold any number of virtual displays. You can paste virtual displays over one another to any depth, occluding the displays underneath. The displays underneath are only occluded to the extent that they are covered; that is, the parts not occluded remain visible on the screen. (In Figure 9-2, displays 1 and 2 are partially occluded.) When you unpaste a virtual display that occludes another virtual display, the occluded part of the display underneath becomes visible again.

You can find out whether a display is occluded by using the SMG$CHECK_FOR_OCCLUSION routine. The following example pastes a two-row summary display over the last two rows of the statistics display, if the statistics display is not already occluded. If the statistics display is occluded, the example assumes that it is occluded by the summary display and unpastes the summary display, making the last two rows of the statistics display visible again.

STATUS = SMG$CHECK_FOR_OCCLUSION (STATS_VDID, 2 PBID, 2 OCCLUDE_STATE) ! OCCLUDE_STATE must be defined as INTEGER*4 IF (OCCLUDE_STATE) THEN STATUS = SMG$UNPASTE_VIRTUAL_DISPLAY (SUM_VDID, 2 PBID) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) ELSE STATUS = SMG$PASTE_VIRTUAL_DISPLAY (SUM_VDID, 2 PBID, 2 11, 2 2) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) END IF

9.4.4.3 Rearranging Virtual Displays

Pasted displays can be rearranged by moving or repasting.

• Moving---To move a display, use the SMG$MOVE_VIRTUAL_DISPLAY routine. The following example moves display 2. Figure 9-2 shows the screen before and after the statement executes.

  STATUS = SMG$MOVE_VIRTUAL_DISPLAY (VDID, 2 PBID, 2 5, 2 10) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))

  Figure 9-2 Moving a Virtual Display

  ---

  
• Repasting---To repaste a display, use the SMG$REPASTE_VIRTUAL_DISPLAY routine. The following example repastes display 2. Figure 9-3 shows the screen before and after the statement executes.

  STATUS = SMG$REPASTE_VIRTUAL_DISPLAY (VDID, 2 PBID, 2 4, 2 4) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))

  Figure 9-3 Repasting a Virtual Display

  ---

  

You can obtain the pasting order of the virtual displays using SMG$LIST_PASTING_ORDER. This routine returns the identifiers of all the virtual displays pasted to a specified pasteboard.

9.4.4.4 Removing Virtual Displays

You can remove a virtual display from a pasteboard in a number of different ways:

• Erase a virtual display---Invoking SMG$UNPASTE_VIRTUAL_DISPLAY erases a virtual display from the screen but retains its contents in memory. The following example erases the statistics display:

  STATUS = SMG$UNPASTE_VIRTUAL_DISPLAY (STATS_VDID, 2 PBID) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))

• Delete a virtual display---Invoking SMG$DELETE_VIRTUAL_DISPLAY removes a virtual display from the screen and removes its contents from memory. The following example deletes the statistics display:

  STATUS = SMG$DELETE_VIRTUAL_DISPLAY (STATS_VDID) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))

• Delete several virtual displays---Invoking SMG$POP_VIRTUAL_DISPLAY removes a specified virtual display and any virtual displays pasted after that display from the screen and removes the contents of those displays from memory. The following example "pops" display 2. Figure 9-4 shows the screen before and after popping. (Note that display 3 is deleted because it was pasted after display 2, and not because it is occluding display 2.)

  STATUS = SMG$POP_VIRTUAL_DISPLAY (STATS_VDID, 2 PBID) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))

  Figure 9-4 Popping a Virtual Display

  ---

  

The screen management facility provides several routines for modifying the characteristics of an existing virtual display:

• SMG$CHANGE_VIRTUAL_DISPLAY---Changes the size, video attributes, or border of a display
• SMG$CHANGE_RENDITION---Changes the video attributes of a portion of a display
• SMG$MOVE_TEXT---Moves text from one virtual display to another

The following example uses SMG$CHANGE_VIRTUAL_DISPLAY to change the size of the WHOOPS display to five rows and seven columns and to turn off all of the display's default video attributes. If you decrease the size of a display that is on the screen, any characters in the excess area are removed from the screen.

STATUS = SMG$CHANGE_VIRTUAL_DISPLAY (WHOOPS_VDID, 2 5, ! Rows 2 7,, ! Columns 2 0) ! Video attributes off

The following example uses SMG$CHANGE_RENDITION to direct attention to the first 20 columns of the statistics display by setting the reverse video attribute to the complement of the display's default setting for that attribute:

STATUS = SMG$CHANGE_RENDITION (STATS_VDID, 2 1, ! Row 2 1, ! Column 2 10, ! Number of rows 2 20, ! Number of columns 2 , ! Video-set argument 2 SMG$M_REVERSE) ! Video-comp argument 2

SMG$CHANGE_RENDITION uses three sets of video attributes to determine the attributes to apply to the specified portion of the display: (1) the display's default video attributes, (2) the attributes specified by the rendition-set argument of SMG$CHANGE_RENDITION, and (3) the attributes specified by the rendition-complement argument of SMG$CHANGE_RENDITION. Table 9-2 shows the result of each possible combination.

Table 9-2 Setting Video Attributes

rendition-set	rendition-complement	Result
off	off	Uses display default
on	off	Sets attribute
off	on	Uses the complement of display default
on	on	Clears attribute

In the preceding example, the reverse video attribute is set in the rendition-complement argument but not in the rendition-set argument, thus specifying that SMG$CHANGE_RENDITION use the complement of the display's default setting to ensure that the selected portion of the display is easily seen.

Note that the resulting attributes are based on the display's default attributes, not its current attributes. If you use SMG$ routines that explicitly set video attributes, the current attributes of the display may not match its default attributes.

9.4.4.6 Using Spawned Subprocesses

You can create a spawned subprocess directly with an SMG$ routine to allow execution of a DCL command from an application. Only one spawned subprocess is allowed per virtual display. Use the following routines to work with subprocesses:

• SMG$CREATE_SUBPROCESS---Creates a DCL spawned subprocess and associates it with a virtual display.
• SMG$EXECUTE_COMMAND---Allows execution of a specified command in the created spawned subprocess by using mailboxes. Some restrictions apply to specifying the following commands:
  • SPAWN, GOTO, or LOGOUT cannot be used and will result in unpredictable results.
  • Single-character commands such as Ctrl/C have no effect. You can signal an end-of-file (that is, press Ctrl/Z) command by setting the flags argument.
  • A dollar sign ($) must be specified as the first character of any DCL command.
• SMG$DELETE_SUBPROCESS---Deletes the subprocess created by SMG$CREATE_SUBPROCESS.

Viewports allow you to view different pieces of a virtual display by moving a rectangular area around on the virtual display. Only one viewport is allowed for each virtual display. Once you have associated a viewport with a virtual display, the only part of the virtual display that is viewable is contained in the viewport.

The SMG$ routines for working with viewports include the following:

• SMG$CREATE_VIEWPORT---Creates a viewport and associates it with a virtual display. You must create the virtual display first. To view the viewport, you must paste the virtual display first with SMG$PASTE_VIRTUAL_DISPLAY.
• SMG$SCROLL_VIEWPORT---Scrolls the viewport within the virtual display. If you try to move the viewport outside of the virtual display, the viewport is truncated to stay within the virtual display. This routine allows you to specify the direction and extent of the scroll.
• SMG$CHANGE_VIEWPORT---Moves the viewport to a new starting location and changes the size of the viewport.
• SMG$DELETE_VIEWPORT---Deletes the viewport and dissociates it from the virtual display. The viewport is automatically unpasted. The virtual display associated with the viewport remains intact. You can unpaste a viewport without deleting it by using SMG$UNPASTE_VIRTUAL_DISPLAY.

The SMG$ output routines allow you to write text to displays and to delete or modify the existing text of a display. Remember that changes to a virtual display are visible only if the virtual display is pasted to a pasteboard.

9.4.6.1 Positioning the Cursor

Each virtual display has its own logical cursor position. You can control the position of the cursor in a virtual display with the following routines:

• SMG$HOME_CURSOR---Moves the cursor to a corner of the virtual display. The default corner is the upper left corner, that is, row 1, column 1 of the display.
• SMG$SET_CURSOR_ABS---Moves the cursor to a specified row and column.
• SMG$SET_CURSOR_REL---Moves the cursor to offsets from the current cursor position. A negative value means up (rows) or left (columns). A value of 0 means no movement.

In addition, many routines permit you to specify a starting location other than the current cursor position for the operation.

The SMG$RETURN_CURSOR_POS routine returns the row and column of the current cursor position within a virtual display. You do not have to write special code to track the cursor position.

Typically, the physical cursor is at the logical cursor position of the most recently written-to display. If necessary, you can use the SMG$SET_PHYSICAL_CURSOR routine to set the physical cursor location.

9.4.6.2 Writing Data Character by Character

If you are writing character by character (see Section 9.4.6.3 for line-oriented output), you can use three routines:

• SMG$DRAW_CHAR---Puts one line-drawing character on the screen at a specified position. It does not change the cursor position.
• SMG$PUT_CHARS---Puts one or more characters on the screen at a specified position, with the option of one video attribute.
• SMG$PUT_CHARS_MULTI---Puts several characters on the screen at a specified position, with multiple video attributes.

These routines are simple and precise. They place exactly the specified characters on the screen, starting at a specified position in a virtual display. Anything currently in the positions written-to is overwritten; no other positions on the screen are affected. Convert numeric data to character data with language I/O statements before invoking SMG$PUT_CHARS.

The following example converts an integer to a character string and places it at a designated position in a virtual display:

CHARACTER*4 HOUSE_NO_STRING INTEGER*4 HOUSE_NO, 2 LINE_NO, 2 STATS_VDID . . . WRITE (UNIT=HOUSE_NO_STRING, 2 FMT='(I4)') HOUSE_NO STATUS = SMG$PUT_CHARS (STATS_VDID, 2 HOUSE_NO_STRING, 2 LINE_NO, ! Row 2 1) ! Column

Note that the converted integer is right-justified from column 4 because the format specification is I4 and the full character string is written. To left-justify a converted number, you must locate the first nonblank character and write a substring starting with that character and ending with the last character.

Inserting and Overwriting Text

To insert characters rather than overwrite the current contents of the screen, use the routine SMG$INSERT_CHARS. Existing characters at the location written to are shifted to the right. Characters pushed out of the display are truncated; no wrapping occurs and the cursor remains at the end of the last character inserted.

Specifying Double-Size Characters

In addition to the preceding routines, you can use SMG$PUT_CHARS_WIDE to write characters to the screen in double width or SMG$PUT_CHARS_HIGHWIDE to write characters to the screen in double height and double width. When you use these routines, you must allot two spaces for each double-width character on the line and two lines for each line of double-height characters. You cannot mix single-and double-size characters on a line.

All the character routines provide rendition-set and rendition-complement arguments, which allow you to specify special video attributes for the characters being written. SMG$PUT_CHARS_MULTI allows you to specify more than one video attribute at a time. The explanation of the SMG$CHANGE_RENDITION routine in Section 9.4.4.5 discusses how to use rendition-set and rendition-complement arguments.

	privacy and legal statement
5841PRO_024.HTML