VSI OpenVMS RTL Screen Management (SMG$) Manual

Document Number: DO–RTLSMG–01A
Publication Date: June 2024
Operating System and Version:
VSI OpenVMS Alpha Version 8.4-2L1 or higher

Preface

This manual provides users of the OpenVMS operating system with detailed usage and reference information on screen management routines supplied in the SMG$ facility of the OpenVMS Run-Time Library (RTL).

1. About VSI

VMS Software, Inc. (VSI) is an independent software company licensed by Hewlett Packard Enterprise to develop and support the OpenVMS operating system.

2. Intended Audience

This manual is intended for system and application programmers who write programs that call SMG$ Run-Time Library routines.

3. Document Structure

This manual is organized as follows:

  • Chapter 1 lists the SMG$ routines and provides a brief overview of the major SMG$ components.

  • Chapter 2 discusses output operations provided by the Screen Management Facility.

  • Chapter 3 describes screen management routines used to enter input from a virtual keyboard.

  • Chapter 4 discusses the Screen Management Facility's advanced features.

  • Chapter 5 discusses a method of supporting foreign terminals.

  • Chapter 6 discusses some recommended methods for using the Screen Management Facility for developing new programs.

  • Chapter 7 contains examples demonstrating how to call some SMG$ routines from major OpenVMS languages.

  • Chapter 8 provides detailed reference information on each routine in the SMG$ facility of the Run-Time Library. This information uses the documentation format described in VSI OpenVMS Programming Concepts Manual. Routine descriptions appear in alphabetical order by routine name.

4. Related Documents

The Run-Time Library routines are documented in a series of reference manuals. A description of how you access the Run-Time Library routines and of OpenVMS features and functionality available through calls to the SMG$ Run-Time Library appears in the VSI OpenVMS Programming Concepts Manual. Descriptions of other RTL facilities and their corresponding routines and usages are discussed in the following books:

  • VSI OpenVMS RTL Library (LIB$) Manual

  • VSI OpenVMS RTL General Purpose (OTS$) Manual

  • VSI OpenVMS RTL String Manipulation (STR$) Manual

The Guide to POSIX Threads Library contains guidelines and reference information for POSIX Threads, the Multithreading Run-Time Library.

The VSI OpenVMS Command Definition, Librarian, and Message Utilities Manual provides information useful for writing applications that use line composition with keypad keys.

The VSI OpenVMS I/O User's Reference Manual contains information about using mailboxes.

Application programmers using any programming language can refer to the Guide to Creating OpenVMS Modular Procedures for writing modular and reentrant code.

High-level language programmers will find additional information on calling Run-Time Library routines in their language reference manual. You can also find additional information in the language user's guide provided with your OpenVMS language software.

For additional information about OpenVMS products and services, access the VSI website at the following location:

5. VSI Encourages Your Comments

You may send comments or suggestions regarding this manual or any VSI document by sending electronic mail to the following Internet address: . Users who have VSI OpenVMS support contracts through VSI can contact for help with this product.

6. OpenVMS Documentation

The full VSI OpenVMS documentation set can be found on the VMS Software Documentation webpage at https://docs.vmssoftware.com.

7. Typographical Conventions

The following conventions are used in this manual:

ConventionMeaning
Ctrl/xA sequence such as Ctrl/x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 xA sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key (x) or a pointing device button.
...
A horizontal ellipsis in examples indicates one of the following possibilities:
  • Additional optional arguments in a statement have been omitted.

  • The preceding item or items can be repeated one or more times.

  • Additional parameters, values, or other information can be entered.

.
.
.
A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )In command format descriptions, parentheses indicate that you must enclose choices in parentheses if you specify more than one.
[ ]In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for directory specifications and for a substring specification in an assignment statement.
|In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ }In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
bold typeBold type represents the name of an argument, an attribute, or a reason. Bold type also represents the introduction of a new term.
italic typeItalic type indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER=name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TYPEUppercase type indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Example

This typeface indicates code examples, command examples, and interactive screen displays. In text, this type also identifies website addresses, UNIX commands and pathnames, PC-based commands and folders, and certain elements of the C programming language.

-
A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbersAll numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes—binary, octal, or hexadecimal—are explicitly indicated.

Chapter 1. Overview of the Screen Management Facility (SMG$)

This manual discusses the Run-Time Library routines that perform terminal-independent functions. The most important aspect of the Screen Management Facility is that user programs are entirely separate from the physical devices that actually perform input and output. Instead of writing directly to a physical screen, the user program writes to a virtual display. Similarly, instead of entering input directly from a physical keyboard, user programs enter input from a virtual keyboard. (Virtual displays and virtual keyboards are logical entities whose usage is described more fully in the following sections.) This separation of virtual operations from physical operations is what allows input/output to be terminal independent.

The SMG$ routines listed below help you design, compose, and keep track of complex images on a video screen. These routines are meant for the types of operations you would normally perform on a VT100-class terminal; they also provide software emulation of screen management functions on terminals that do not have these functions implemented in their hardware. While you can use these routines with video terminals, you can also use them with hardcopy devices and files. The following lists contain all the screen management routines grouped according to their functions.

Table 1.1 lists routines that support third-party terminals; Chapter 5 discusses these routines.

Table 1.2 lists the SMG$ input routines; Chapter 3 discusses these routines.

Table 1.3 lists the SMG$ output routines; Chapter 2 discusses these routines.

Table 1.1. Routines That Support Third-Party Terminals
SMG$DEL_TERM_TABLESMG$GET_NUMERIC_DATA
SMG$GET_TERM_DATASMG$INIT_TERM_TABLE
SMG$INIT_TERM_TABLE_BY_TYPE
Table 1.2. Input Routines
SMG$ADD_KEY_DEFSMG$CANCEL_INPUT
SMG$CREATE_KEY_TABLESMG$CREATE_VIRTUAL_KEYBOARD
SMG$DEFINE_KEYSMG$DELETE_KEY_DEF
SMG$DELETE_VIRTUAL_KEYBOARDSMG$GET_KEY_DEF
SMG$GET_KEYBOARD_ATTRIBUTESSMG$KEYCODE_TO_NAME
SMG$LIST_KEY_DEFSSMG$LOAD_KEY_DEFS
SMG$NAME_TO_KEYCODESMG$READ_COMPOSED_LINE
SMG$READ_KEYSTROKESMG$READ_LOCATOR
SMG$READ_STRINGSMG$READ_VERIFY
SMG$REPLACE_INPUT_LINESMG$RETURN_INPUT_LINE
SMG$SET_DEFAULT_STATESMG$SET_KEYPAD_MODE
Table 1.3. Output Routines
SMG$BEGIN_DISPLAY_UPDATESMG$BEGIN_PASTEBOARD_UPDATE
SMG$CHANGE_PBD_CHARACTERISTICSSMG$CHANGE_RENDITION
SMG$CHANGE_VIEWPORTSMG$CHANGE_VIRTUAL_DISPLAY
SMG$CHECK_FOR_OCCLUSIONSMG$CONTROL_MODE
SMG$COPY_VIRTUAL_DISPLAYSMG$CREATE_MENU
SMG$CREATE_PASTEBOARDSMG$CREATE_SUBPROCESS
SMG$CREATE_VIEWPORTSMG$CREATE_VIRTUAL_DISPLAY
SMG$CURSOR_COLUMNSMG$CURSOR_ROW
SMG$DELETE_CHARSSMG$DELETE_LINE
SMG$DELETE_MENUSMG$DELETE_PASTEBOARD
SMG$DELETE_SUBPROCESSSMG$DELETE_VIEWPORT
SMG$DELETE_VIRTUAL_DISPLAYSMG$DISABLE_BROADCAST_TRAPPING
SMG$DISABLE_UNSOLICITED_INPUTSMG$DRAW_CHAR
SMG$DRAW_LINESMG$DRAW_RECTANGLE
SMG$ENABLE_UNSOLICITED_INPUTSMG$END_DISPLAY_UPDATE
SMG$END_PASTEBOARD_UPDATESMG$ERASE_CHARS
SMG$ERASE_COLUMNSMG$ERASE_DISPLAY
SMG$ERASE_LINESMG$ERASE_PASTEBOARD
SMG$EXECUTE_COMMANDSMG$FIND_CURSOR_DISPLAY
SMG$FLUSH_BUFFERSMG$FLUSH_DISPLAY_UPDATE
SMG$GET_BROADCAST_MESSAGESMG$GET_CHAR_AT_PHYSICAL_CURSOR
SMG$GET_DISPLAY_ATTRSMG$GET_PASTEBOARD_ATTRIBUTES
SMG$GET_PASTING_INFOSMG$GET_VIEWPORT_CHAR
SMG$HOME_CURSORSMG$INSERT_CHARS
SMG$INSERT_LINESMG$INVALIDATE_DISPLAY
SMG$LABEL_BORDERSMG$LIST_PASTEBOARD_ORDER
SMG$LIST_PASTING_ORDERSMG$LOAD_VIRTUAL_DISPLAY
SMG$MOVE_TEXTSMG$MOVE_VIRTUAL_DISPLAY
SMG$PASTE_VIRTUAL_DISPLAYSMG$POP_VIRTUAL_DISPLAY
SMG$PRINT_PASTEBOARDSMG$PUT_CHARS
SMG$PUT_CHARS_HIGHWIDESMG$PUT_CHARS_MULTI
SMG$PUT_CHARS_WIDESMG$PUT_HELP_TEXT
SMG$PUT_LINESMG$PUT_LINE_HIGHWIDE
SMG$PUT_LINE_MULTISMG$PUT_LINE_WIDE
SMG$PUT_PASTEBOARDSMG$PUT_STATUS_LINE
SMG$READ_FROM_DISPLAYSMG$REMOVE_LINE
SMG$REPAINT_LINESMG$REPAINT_SCREEN
SMG$REPASTE_VIRTUAL_DISPLAYSMG$RESTORE_PHYSICAL_SCREEN
SMG$RETURN_CURSOR_POSSMG$RING_BELL
SMG$SAVE_PHYSICAL_SCREENSMG$SAVE_VIRTUAL_DISPLAY
SMG$SCROLL_DISPLAY_AREASMG$SCROLL_VIEWPORT
SMG$SELECT_FROM_MENUSMG$SET_BROADCAST_TRAPPING
SMG$SET_CURSOR_ABSSMG$SET_CURSOR_MODE
SMG$SET_CURSOR_RELSMG$SET_DISPLAY_SCROLL_REGION
SMG$SET_OUT_OF_BAND_ASTSSMG$SET_PHYSICAL_CURSOR
SMG$SET_TERM_CHARACTERISTICSSMG$SNAPSHOT
SMG$SNAPSHOT_TO_PRINTERSMG$UNPASTE_VIRTUAL_DISPLAY

The Screen Management Facility provides two important services:

  • Terminal independence

    The screen management routines provide terminal independence by allowing you to perform commonly needed screen functions regardless of terminal type. All operations, including input and output, are performed by calling a routine that converts the caller's terminal-independent request (for example, to scroll a part of the screen) into the sequence of codes needed to perform that action. If the terminal being used does not support the requested operation in hardware, in most cases the screen management routines accomplish the action by emulating it in software. Similarly, the screen management routines provide a terminal-independent means for performing input from a keyboard without concern for the type of keyboard.

    Note

    The Screen Management Facility assumes that it has complete control of the terminal. Applications should not mix calls to SMG$ with calls to other screen products such as GKS or FMS.

  • Ease of composition

    The screen management routines help you compose complex images on a screen. For example, you may want to solicit user input from one part of the screen, display results on a second part of the screen, and maintain a status display in a third part of the screen. Normally, each routine that reads from or writes to one of these regions must be aware that other regions exist and know where on the screen they are positioned, in order to properly bias its row and column references to locate the display on the desired part of the screen. Using the screen management routines, a routine can independently write to its dedicated region of the screen regardless of the position of the region. References to row and column pertain only to the region of the screen the routine is addressing.

The following sections discuss the fundamental elements of screen management. These elements are the pasteboard, the virtual display, the viewport, and the virtual keyboard.

1.1. Pasteboards

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
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 physical screen.

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 routine. 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-ididentifies the virtual display in subsequent routine calls that modify the display.

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.

1.3. Viewports

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

1.3.1. 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 codes.)

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

Chapter 2. 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
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
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 calling 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
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
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-idof 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 display 2.

Figure 2.5. Pop Operation
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 SMG$CHECK_FOR_OCCLUSION routine. 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
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 recently modified.

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
THEN
  BEGIN

   .
   .
   .

  END
To obtain this information with SMG$RETURN_CURSOR_POS, you would write the following:
CALL SMG$RETURN_CURSOR_POS ( Display-id, Cursor-row, Cursor-column )
IF Cursor-row > Max-row
  THEN
    BEGIN

   .
   .
   .

    END

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 display:

  • 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 blanks.

  • 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 rearranged.

The following routines erase parts of a virtual display:

  • SMG$ERASE_CHARS erases a specified number of characters within a given line.

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

2.2.5.1. 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 display.

  • 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 virtual display.

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

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.

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:

SMG$M_BLINKSpecifies blinking characters.
SMG$M_BOLDSpecifies characters in higher-than-normal intensity.
SMG$M_REVERSESpecifies characters in reverse video; that is, the opposite of the current rendition of the virtual display.
SMG$M_UNDERLINESpecifies underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Specifies 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:

SetComplementAction
00Attribute set to default
10Attribute on
01Attribute set to complement of default setting
11Attribute 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

The following routines provide a simple way to construct horizontal and vertical lines:

  • 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
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 Without SMG$DRAW_LINE
Lines Drawn Without 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:

  • 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

The SMG$READ_FROM_DISPLAY routine makes it easy to obtain text from a virtual display. This routine might be used in applications that present menu items on the screen by way of a virtual display. The application might allow the user to move the cursor among the menu items and then select one (by pressing the Return key, for example). At this point, the program can read characters from the display at the current cursor position and determine which menu item was selected. Note that this routine also provides a way to read characters written with the SMG$M_INVISIBLE attribute.

2.2.10. Viewports

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

Note

Terminals accessed using non-terminal devices such as network and mailbox devices are treated as files.

2.2.14.1. Snapshots

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.

2.3.3. Tabs

Tabs are used for minimal updating. When you are using tabs, you must ensure that the tab stops are set to the default locations. Do not use tabs if you want to be sure that the application will run regardless of the tab settings the user has set on the terminal.

Any tabs that you output to the screen are converted to eight spaces by SMG$ before being output to the screen. The only exception to this is when using SMG$CREATE_VIRTUAL_DISPLAY with the display-attributesargument set to SMG$M_DISPLAY_CONTROLS. In this case, the tab character is printed rather than interpreted as eight spaces.

2.4. Batching Output Operations

If you want to construct a complex virtual display that requires several scrolling, cursor positioning, and output operations but do not want the interim steps to be visible, you can batch the output operations. Batching a series of operations to a virtual display lets the application hide the interim steps.

You may also want to construct a complex pasteboard image but have it appear on the screen only after the entire picture is complete. Unpasting and repasting leaves the screen blank during the construction process, so in this case you can batch a series of composition operations and let the screen show only the final effect.

The Screen Management Facility provides a mechanism for batching a series of operations at both the virtual display level and the pasteboard level. These are described in the following sections.

2.4.1. Display Update Batching

The SMG$BEGIN_DISPLAY_UPDATE routine causes output operations to a pasted display to be reflected only in the display's buffers. When all operations to the display are finished, the application can call the SMG$END_DISPLAY_UPDATE routine, which causes the display's buffer to be written 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 zero, output to the virtual display is immediately sent to the pasteboard. When the counter's value is nonzero, output operations are batched; the display batching level is equal to the counter's value. Notice that the counter mechanism allows a subroutine to request and turn off batching without disturbing the batching level of the calling program.

You can call SMG$FLUSH_DISPLAY_UPDATE in place of a call to SMG$END_DISPLAY_UPDATE that is immediately followed by a call to SMG$BEGIN_DISPLAY_UPDATE, when the batch count is zero, with much better performance than the two calls.

2.4.2. Pasteboard Update Batching

You accomplish pasteboard batching by calling the SMG$BEGIN_PASTEBOARD_UPDATE routine, performing several composition operations, and finally calling the SMG$END_PASTEBOARD_UPDATE routine. The SMG$BEGIN_PASTEBOARD_UPDATE routine causes output operations to be reflected only in the pasteboard buffer, not on the physical screen. The SMG$END_PASTEBOARD_UPDATE routine causes the pasteboard buffer to be written to the physical screen.

The SMG$BEGIN_PASTEBOARD_UPDATE and SMG$END_PASTEBOARD_UPDATE routines increment and decrement a counter. When this counter's value is zero, output to the pasteboard is immediately sent to the physical screen. When the counter's value is nonzero, output operations are batched; the pasteboard batching level is equal to the value of the counter. Notice that the counter mechanism allows a subroutine to request and turn off batching without disturbing the batching level of the calling program.

Chapter 3. Screen Management Input Operations

This chapter describes the screen management routines used to perform input from a virtual keyboard. Remember that while a virtual keyboard is usually associated with a terminal, it may also be associated with any OpenVMS RMS file to which you have access. If the RMS file is on another node in a network, you may need a valid account for that node.

The Screen Management Facility provides a flexible set of routines for performing input from a terminal or a file. The input routines can be used with the output routines, or they can be used by themselves. You establish an input source, called a virtual keyboard, by calling the SMG$CREATE_VIRTUAL_KEYBOARD routine. You delete a virtual keyboard by calling the SMG$DELETE_VIRTUAL_KEYBOARD routine.

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 type of terminal being used. 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 codes.) Virtual keyboards are also important for processing function/keypad keys.

3.1. Obtaining Data from Virtual Keyboards

Data may be obtained from a virtual keyboard in the following ways:

  • SMG$READ_STRING reads a string composed of characters and a terminator. This flexible routine provides access to many features of the OpenVMS terminal driver.

  • SMG$READ_COMPOSED_LINE reads a line composed of ordinary keystrokes and predefined strings associated with keypad and function keys; it provides an easy way to code an interface for command-oriented utilities by providing single-key command capabilities.

  • SMG$READ_KEYSTROKE reads one keystroke entered at the keyboard. It reads function/keypad keys as well as alphanumeric keys.

  • SMG$READ_VERIFY reads a string and verifies that string against a user-supplied picture string.

All read operations can be aborted by calling the SMG$CANCEL_INPUT routine.

3.2. Obtaining Data from a Mouse or Tablet

You can read information from a workstation terminal's locator device, such as a mouse or a tablet, by calling SMG$READ_LOCATOR. (This routine does not read locator information from the VT300 series terminals.) This routine tells you at which row and column the locator is pointing and which button was pressed.

3.3. Setting and Retrieving Virtual Keyboard Characteristics

In the same way that you can retrieve information about and set pasteboard characteristics, the Screen Management Facility also provides routines that let you retrieve and set the characteristics of a virtual keyboard.

The SMG$GET_KEYBOARD_ATTRIBUTES routine retrieves requested information about a virtual keyboard. It deposits this information in a user-supplied area called the keyboard information table (KIT). The information returned includes the following:

  • The current device characteristics

  • The device class

  • The size of the recall buffer

  • The physical device type

  • The first character in the type-ahead buffer

  • The terminal width

  • The number of characters in the type-ahead buffer

You can use SMG$SET_KEYPAD_MODE to set the terminal's numeric keypad to either numeric or applications mode. In applications mode, numeric keypad keys are considered function keys and may be used as terminators. In numeric mode, these keys are equivalent to the corresponding keys on the main keyboard. Note that the terminal must support applications mode, or the call to SMG$SET_KEYPAD_MODE will fail.

3.4. Line Composition Using Keypad Keys

In addition to the functions provided by SMG$READ_STRING, line composition with keypad keys provides a powerful and flexible tool for applications that have line-oriented commands (for example, utilities that use the Command Definition Utility). (See the VSI OpenVMS Command Definition, Librarian, and Message Utilities Manual for more information.)

With line composition, you can define certain keys (discussed below) to be equivalent to a string of characters. When you enter a line and press one of these keys, the equivalence string for that key is inserted into the returned command string. For example, if the application defines the key PF2 to have the equivalence string "HELP", then when you press the PF2 key, that command is returned to the application. You can also specify that the equivalence string be echoed; in this case, the string "HELP" is echoed. The recognition of keypad keys and the insertion of the equivalence string are handled automatically by SMG$READ_COMPOSED_LINE; the application treats the returned line just as if you had typed the entire line.

Key definitions are placed in a key definition table, which is created by a call to SMG$CREATE_KEY_TABLE. Key definitions can be added to and deleted from the table by calls to SMG$ADD_KEY_DEF and SMG$DELETE_KEY_DEF. Key definitions can also be added by calls to SMG$DEFINE_KEY and SMG$LOAD_KEY_DEFS; these routines accept a DCL command DEFINE/KEY (or a file of these commands). See the description of these routines for more information; see the VSI OpenVMS DCL Dictionary for an explanation of the DEFINE/KEY command.

All keyboard keys can be defined by calling SMG$ADD_KEY_DEF and can be used with SMG$READ_COMPOSED_LINE. Other definable keys include the function and keypad keys listed in Table 3.1, the control key sequences (Ctrl/A through Ctrl/Z), and line editing keys if line editing is disabled.

A key definition has several attributes. The TERMINATE attribute specifies whether the input line is terminated when this key is pressed; the NOTERMINATE attribute specifies that more characters and keystrokes may be entered. TERMINATE is the default.

The ECHO attribute specifies whether the equivalence string is echoed when the key is pressed. ECHO is the default.

The PROTECT attribute specifies whether this key definition can be changed or deleted once it is defined. NOPROTECT is the default.

The remaining attributes are LOCK_STATE, IF_STATE, and STATE. They are described in the following section.

3.5. States

A given key may have many definitions, depending on the value of the current state; the state is used to determine the meaning of the key. For example, if PF1 is defined as setting the state to "GOLD" and if PF2 with IF_STATE="GOLD" is defined as "HELP *", pressing PF1 and then PF2 would result in "HELP *" being returned as the command line. Note that in this case the PF1 definition would have no equivalence string and would specify the NOTERMINATE attribute.

A state name is any string comprising up to 31 alphanumeric characters, and can include the dollar sign ($) and underscore (_). When a line is being composed from normal keystrokes and equivalence strings, SMG$READ_COMPOSED_LINE maintains a string called the current state name. Before the first key is pressed, the current state is "DEFAULT". If you press a key whose definition has specified a value for the STATE attribute, the current state is changed to the specified state. Unless you specify the LOCK_STATE attribute, the state name reverts to "DEFAULT" after the next defined key is pressed.

3.6. Terminators

A terminator ends a transfer of data from the virtual keyboard. A terminator may be a single character such as a carriage return or Ctrl/Z, a character sequence (escape sequence) generated by pressing a function key on a keyboard, or a condition such as timeout or buffer full.

The terminator is not part of the data read from the virtual keyboard; it is returned to the caller in a separate argument as an integer (unsigned word) value.

3.6.1. Single-Character Terminators

For single-character terminators, the value is the terminator's 8-bit character code. Single-character terminator codes are in the range 0 through 255.

For calls to SMG$READ_STRING and SMG$READ_VERIFY, the default single character terminators are all the characters in the range 0 through 31 except backspace (8), horizontal tab (9), line feed (10), vertical tab (11), and form feed (12). Note that these characters make up the default terminator set for the OpenVMS terminal driver. However, any 8-bit character code is potentially a terminator.

The set of terminator characters may be changed by calls to SMG$READ_STRING or SMG$READ_VERIFY. For calls to SMG$READ_COMPOSED_LINE, the only default single terminator characters are the carriage return (13) and Ctrl/Z (26). Changes to the terminator set for SMG$READ_COMPOSED_LINE are made by key definitions; see the description of line composition in Section 3.4 for more information.

Behavior of input operations may vary in response to a Ctrl/Z. Under certain conditions, a Ctrl/Z in the input stream terminates the current read operation as well as the next read operation. You may need to issue an additional read to satisfy the Ctrl/Z.

3.6.2. Character Sequence Terminators

Character sequence terminators are returned in a device-independent fashion. The codes are in the form SMG$K_TRM_keyname (for example, SMG$K_TRM_DELETE). A unique code is assigned to each possible function key on VT220 (and VT200-compatible) terminals. Key codes on other terminals are returned using the code of the equivalent VT220 key. Therefore, the application program need not know which type of terminal is being used; the screen management routines transparently map the different terminator character sequences into a uniform set of function codes.

Table 3.1 lists the terminator name or condition for each terminator that is not a single character. The table also lists the code and the key legend for each terminator on the different types of terminals supported by the screen management input routines.
Table 3.1. Terminator Values
Key NameValueVT200 and VT300 SeriesVT100VT52
Keypad Keys
DELETESMG$K_TRM_DELETEDELETEDEL
PF1SMG$K_TRM_PF1PF1PF1Blue
PF2SMG$K_TRM_PF2PF2PF2Red
PF3SMG$K_TRM_PF3PF3PF3Black
PF4SMG$K_TRM_PF4PF4PF4
KP0SMG$K_TRM_KP0?000
KP1SMG$K_TRM_KP1?111
KP2SMG$K_TRM_KP2?222
KP3SMG$K_TRM_KP3?333
KP4SMG$K_TRM_KP4?444
KP5SMG$K_TRM_KP5?555
KP6SMG$K_TRM_KP6?666
KP7SMG$K_TRM_KP7?777
KP8SMG$K_TRM_KP8?888
KP9SMG$K_TRM_KP9?999
ENTERSMG$K_TRM_ENTER?ENTERENTERENTER
MINUSSMG$K_TRM_MINUS?
COMMASMG$K_TRM_COMMA?,,
PERIODSMG$K_TRM_PERIOD?..
Cursor Positioning Keys
UPSMG$K_TRM_UPUp arrowUp arrowUp arrow
DOWNSMG$K_TRM_DOWNDown arrowDown arrowDown arrow
LEFTSMG$K_TRM_LEFTLeft arrowLeft arrowLeft arrow
RIGHTSMG$K_TRM_RIGHTRight arrowRight arrowRight arrow
Function Keys
F6SMG$K_TRM_F6F6
F7SMG$K_TRM_F7F7
F8SMG$K_TRM_F8F8
F9SMG$K_TRM_F9F9
F10SMG$K_TRM_F10F10
F11SMG$K_TRM_F11F11
F12SMG$K_TRM_F12F12
F13SMG$K_TRM_F13F13
F14SMG$K_TRM_F14F14
HELPSMG$K_TRM_HELP?HELP
DOSMG$K_TRM_DO?DO
F17SMG$K_TRM_F17F17
F18SMG$K_TRM_F18F18
F19SMG$K_TRM_F19F19
F20SMG$K_TRM_F20F20
Editing Keys
FINDSMG$K_TRM_FINDFind
INSERT_HERESMG$K_TRM_INSERT_HEREInsert Here
REMOVESMG$K_TRM_REMOVERemove
SELECTSMG$K_TRM_SELECTSelect
PREV_SCREENSMG$K_TRM_PREV_SCREENPrev Screen
NEXT_SCREENSMG$K_TRM_NEXT_SCREENNext Screen
Conditions
CANCELEDSMG$K_TRM_CANCELLED
TIMEOUTSMG$K_TRM_TIMEOUT
BUFFER_FULLSMG$K_TRM_BUFFER_FULL
UNKNOWNSMG$K_TRM_UNKNOWN?

3.6.3. Termination by a Condition

Input operations terminated by a condition are indicated by the terminator codes SMG$K_TRM_CANCELLED, SMG$K_TRM_TIMEOUT, SMG$K_TRM_BUFFER_FULL, and SMG$K_TRM_UNKNOWN. If the input is from an OpenVMS RMS file, each input operation reads one record from the file; the terminator code is always the code for a Return. (The only exception is SMG$READ_KEYSTROKE, in which the terminator is the next character in the record.)

3.6.4. Key Name and Terminator Code Translation

The SMG$NAME_TO_KEYCODE routine translates the name of a key on the keyboard to its corresponding terminator code, while SMG$KEYCODE_TO_NAME translates the terminator code to the corresponding name of the key on the keyboard.

3.6.5. Symbolic Definitions of Terminator Values

Symbolic definitions of the terminator values are provided in symbol libraries named $SMGDEF. For example, in a MACRO program you would issue a call to $SMGDEF to extract these definitions. The symbol names are of the form SMG$K_TRM_keyname, where keyname is the key name given in Table 3.1. For terminator codes 1 through 26, which correspond to the control sequences Ctrl/A through Ctrl/Z, the key names are CTRLA for Ctrl/A, CTRLB for Ctrl/B, and so on. The following synonyms are also defined:

SymbolSynonym
SMG$K_TRM_BSSMG$K_TRM_CTRLH
SMG$K_TRM_HTSMG$K_TRM_CTRLI
SMG$K_TRM_LFSMG$K_TRM_CTRLJ
SMG$K_TRM_CRSMG$K_TRM_CTRLM
SMG$K_TRM_E1SMG$K_TRM_FIND
SMG$K_TRM_E2SMG$K_TRM_INSERT_HERE
SMG$K_TRM_E3SMG$K_TRM_REMOVE
SMG$K_TRM_E4SMG$K_TRM_SELECT
SMG$K_TRM_E5SMG$K_TRM_PREV_SCREEN
SMG$K_TRM_E6SMG$K_TRM_NEXTSCREEN
SMG$K_TRM_F15HELP
SMG$K_TRM_F16DO

3.7. Line Recall and the Recall Buffer

The Screen Management Facility allows you to access and change the contents of the application recall buffer. By default, the recall buffer stores the previous 20 commands or data lines entered by the user to the application.

The SMG$RETURN_INPUT_LINE routine lets you request a particular line from the recall buffer. You can either specify the appropriate line number for the line to be recalled, or you can specify a match string. If you use a match string, SMG$RETURN_INPUT_LINE searches for and returns the line that matches the specified string. This routine aids in the implementation of a DCL-style RECALL command.

The SMG$REPLACE_INPUT_LINE routine lets you replace the specified line or lines in the recall buffer with the specified string. The remaining lines of the recall buffer are deleted. This routine aids in processing line continuations.

3.8. Interaction of Input and Output

SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY accept an optional display-id argument. If a display-id is supplied, it designates the virtual display in which the input operation should occur. By specifying display-id, you enable the Screen Management Facility to remain aware of the changes caused by character echoing. If you omit display-id, the Screen Management Facility assumes that screen management output is not being used.

Note that if the display-id argument is specified for any one of the above-mentioned input routines, then the length of the prompt string plus the input is limited to the number of columns in the display or, where specified, to the maximum number of characters to be read. (In the case of SMG$READ_KEYSTROKE, this restriction applies only to the length of the prompt string.)

Chapter 4. Advanced Screen Management Features

The Screen Management Facility provides several advanced features to:

  • Trap asynchronous events

  • Create and execute commands in a subprocess

  • Move the physical cursor

  • Clean up at exit

The following sections describe these features.

Note

The Screen Management Facility assumes that it has complete control of the terminal. Applications should not mix calls to SMG$ with calls to other screen products such as GKS or FMS.

SMG$ is not reentrant. Therefore, unpredictable results can occur when multiple processes call SMG$ routines to perform operations on the same terminal. If your application contains multiple processes, one process should call the SMG$ routines. Other processes should send messages to the calling process when screen modifications are necessary. The calling process can then call the appropriate SMG$ routines.

4.1. Asynchronous Events

The following types of asynchronous events can disrupt the screen image:

  • Broadcast messages

  • Unsolicited input

  • Out-of-band asynchronous system traps (ASTs)

The following sections explain how to control these actions.

Note

The Screen Management Facility is not AST reentrant. Therefore, the caller of the SMG$ routines described in this chapter is responsible for any synchronization needed.

4.1.1. Broadcast Messages

Normally, broadcast messages (for example, MAIL notifications or operator messages) can appear on the terminal screen at any time, destroying or distorting the screen image. The SMG$SET_BROADCAST_TRAPPING routine lets you trap messages broadcast to the specified terminal (pasteboard) and in addition, lets you specify an AST routine to be called whenever a broadcast message is trapped. The AST routine you supply can access the broadcast message by calling the SMG$GET_BROADCAST_MESSAGE routine.

Whether or not you specify an AST routine in the call to SMG$SET_BROADCAST_TRAPPING, you can check for the receipt of a broadcast message at any time by calling SMG$GET_BROADCAST_MESSAGE.

4.1.2. Unsolicited Input

The SMG$ENABLE_UNSOLICITED_INPUT routine detects the presence of unsolicited input. Note that this routine does not read any input characters; it merely calls an AST routine to notify the application that it should issue a read operation with SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, or SMG$READ_VERIFY. It is up to you to read the unsolicited input.

4.1.3. Out-of-Band ASTs

The SMG$SET_OUT_OF_BAND_ASTS routine provides a way to trap out-of-band characters such as Ctrl/Y, Ctrl/C, and Ctrl/O. This routine lets you specify which characters are to be treated as out-of-band characters and also lets you specify an AST routine to be called when one of these characters is typed.

4.2. Subprocesses

The Screen Management Facility lets you use a subprocess to execute DCL commands from an application. Only one subprocess is allowed per virtual display.

4.2.1. Creating a Subprocess

The SMG$CREATE_SUBPROCESS routine creates a subprocess. This routine creates a DCL subprocess and associates it with a virtual display you specify. The subprocess is initialized with the DCL commands SET NOVERIFY and SET NOON. The creating process requires an available BYTLM value of at least 5000 and an available PRCLM value of at least 1. The Screen Management Facility checks to make sure that you have sufficient resources before creating the subprocess.

4.2.2. Deleting a Subprocess

When you are done executing subprocess commands, you can delete the subprocess with the SMG$DELETE_SUBPROCESS routine. If you exit without first calling this routine, the Screen Management Facility includes an exit handler that deletes the subprocess for you. It is important to note, however, that under some circumstances these facility-supplied exit handlers are not executed. In that case, you must delete the subprocess with the following commands using your system-assigned process identifier (PID) code for xxxx:
$ SHOW PROCESS/SUB
$ STOP/IDENT=xxxx

4.2.3. Executing Commands in a Subprocess

The SMG$EXECUTE_COMMAND routine executes a specified command in the created subprocess. If commands are being buffered, SMG$EXECUTE_COMMAND returns control after the specified command is buffered. The AST routine that you specify is invoked with the command status when the command completes execution. If commands are not being buffered, SMG$EXECUTE_COMMAND waits until the command has completed execution before returning the status of the command.

When you specify the command string to be executed, you must specify a dollar sign ($) as the first character of any DCL command. The Screen Management Facility assumes that any command string that does not begin with a dollar sign is input data for the previous command. The commands and their outputs are displayed on the specified virtual display as they are executed. Note that the commands SPAWN, GOTO, and LOGOUT are illegal to use as command strings and generate unpredictable results.

It is also important to note that since I/O is performed by means of mailboxes and not through the terminal driver, single-character commands such as Ctrl/C, Ctrl/Y, Ctrl/Z, and so on have no effect. Use SMG$M_SEND_EOF as the flags parameter in order to pass a Ctrl/Z to the subprocess.

4.3. Moving the Cursor

The Screen Management Facility lets you move the cursor to a specified location on the physical screen. It does so through the SMG$SET_PHYSICAL_CURSOR routine. However, if you attempt to move the cursor to a pasteboard position outside the screen boundaries, an error is returned.

4.4. Exit Handler

The Screen Management Facility supplies an exit handler, which is invoked before image termination. This handler deletes all pasteboards and virtual keyboards associated with the current image and resets the terminal characteristics. The Screen Management Facility's exit handler may or may not be invoked before any user-supplied exit handlers. Therefore, you should not delete pasteboards or virtual displays from inside a user-supplied exit handler because they may already have been deleted by the Screen Management Facility exit handler and their identifiers deassigned.

Chapter 5. Support for Third-Party Terminals

This chapter describes SMG$ support for foreign terminals. A foreign terminal is any terminal for which the device type is not one of the terminals recognized by OpenVMS, or any terminal on which the ANSI_CRT characteristic is not set.

This support is used by the Screen Management Facility, but it can also be used by application programs that perform their own I/O to foreign terminals. Thus, if you use the Screen Management Facility, you need to concern yourself only with the definition of foreign terminal capabilities, and not with the details of calling the foreign terminal routines directly. Further, you need to define only a few terminal capabilities ("set absolute cursor position," "erase to end of display," and "erase to end of line") in order for the Screen Management Facility to effectively control the terminal screen. The routines used by the Screen Management Facility are presented here to allow you to do your own I/O to foreign terminals.

The support begins with a source file named TERMTABLE.TXT, which contains a list of terminal names and their associated capabilities. This file is processed by the SYS$SYSTEM:SMGBLDTRM.EXE program to create an image file called TERMTABLE.EXE. The following sections describe the creation and processing of the TERMTABLE database.

Note that the TERMTABLE support is used by the Screen Management Facility for all terminals. The definitions for non-foreign terminals are included in a file named SYS$SYSTEM:SMGTERMS.TXT, which is provided as part of the Screen Management Facility. The examples in this chapter show you how to use the foreign terminal package to define non-foreign terminals, because most users are familiar with them.

Note

You should not create your own definitions for non-foreign terminals, nor should you modify the definitions in SYS$SYSTEM:SMGTERMS.TXT.

5.1. TERMTABLE Interface Routines

TERMTABLE.EXE is a database containing information about any number of different types of terminals. You extract information from this database with these steps:

  1. Provide the terminal name to the database.

  2. Retrieve the information about that terminal type (this step might be repeated any number of times).

  3. End access to the database.

When using screen management routines to perform I/O to foreign terminals, you need only create the proper TERMTABLE entries for the foreign terminals you use. The steps listed above are necessary only when your program performs I/O directly to foreign terminals.

The first step can be performed in either of two ways. You can either pass a string that contains a terminal name (for example, "VT100") to the SMG$INIT_TERM_TABLE routine, or you can pass a value returned by the OpenVMS system service $GETDVI to the SMG$INIT_TERM_TABLE_BY_TYPE routine. The returned value may be a symbolic terminal type (for example, TT$_VT100 or TT$_VT52) or a value assigned by the SMG$ foreign terminal routines to designate a particular foreign terminal.

The second step requires that you call the SMG$GET_TERM_DATA routine. This routine extracts a command string (for example, an escape sequence) from TERMTABLE and stores it in a buffer you provide. It is then your responsibility to write the command string to the terminal. It may be necessary to call SMG$GET_TERM_DATA many times; each time you receive the command sequence you can perform a different operation. You should also call SMG$GET_TERM_DATA each time you want to use a capability string that requires a substitution or arithmetic operation for an argument. However, you may want to save the static capability strings in your program's local storage. These static capability strings can be retrieved once and used any number of times.

The third step is optional; it merely frees the virtual memory used to access the information in the database.

The DCL commands SET and SHOW TERMINAL recognize any name defined in TERMTABLE, as well as the current set of valid OpenVMS terminal names. If you use the SET TERMINAL/DEVICE=name command to specify a terminal that is unknown to the OpenVMS operating system, the TERMTABLE database is searched for the named terminal.

Two routines are provided to obtain the address of a specific terminal definition. SMG$INIT_TERM_TABLE accepts a terminal name as input; SMG$INIT_TERM_TABLE_BY_TYPE accepts a device type as input. Each maps to a specific terminal entry in the TERMTABLE.EXE section. These routines return this identifier to the caller for use in future calls.

SMG$GET_TERM_DATA accepts the identifier of the compiled TERMTABLE database and a request code. The request code is used as an index into the data to retrieve the appropriate escape sequence. Some sequences are static; they do not contain any variable information and are simply copied into the caller's buffer. Variable sequences, which include a ! or % directive, cause additional processing to take place. An example of a variable sequence is the VT300-series set cursor command: the required binary row and column numbers must be converted to ASCII for the set cursor sequence. SMG$GET_TERM_DATA uses the optional input arguments to do the conversion before copying the sequence to the caller's buffer.

If you do not provide any optional input arguments to SMG$GET_TERM_DATA, it uses a default of 1 for each argument that the capability requires. Nevertheless, you cannot supply some of the optional arguments and accept the default for others—you must supply all or none of them. SMG$GET_NUMERIC_DATA provides a simplified interface for users who wish to obtain numeric or Boolean data only.

When all terminal I/O has been completed, SMG$DEL_TERM_TABLE can be called to release the virtual memory used. This routine is useful only if you do not need TERMTABLE for the duration of your program; releasing virtual memory may make it available for reuse by your program.

A skeleton TERMTABLE.TXT is supplied in SYS$SYSTEM:. SMGTERMS.TXT, which defines non-foreign terminals, is also provided. The skeleton TERMTABLE.TXT uses the REQUIRE directive to include the separate source file SMGTERMS.TXT. Thus, only third-party terminals are actually defined in the TERMTABLE.TXT source file.

5.2. Capability Fields

If you have a foreign (third-party) terminal, the Screen Management Facility does not know what your terminal can and cannot do—in other words, what the terminal's capabilities are. Capability fields let you tell the Screen Management Facility what capabilities are supported for your foreign terminal. These fields let SMG$ use your terminal capabilities rather than emulate common terminal functions, which in turn improves SMG$'s performance.

Three types of capability fields are allowed in a TERMTABLE entry:

  • Boolean

  • Numeric

  • String

The following sections describe these capability fields in detail.

Functions that are common to most terminals have been chosen as possible fields; not all functions of all terminal types are represented. (Specifically, there is no support for block mode, graphics, or typesetting composition functions.) Screen-oriented applications should be planned around typical terminal functions, and should not depend on features that exist on only one or a few models.

For applications that must support an unusual terminal, some generic capability names are reserved for user definition. Names of the form PRIVATE_BOO_n, PRIVATE_NUM_n, and PRIVATE_STR_n, where n is a number from 1 to 10, may be included as user-defined terminal definitions and returned by the TERMTABLE interface routines. Since meanings are assigned by the user, private capabilities vary between applications. Sites running several applications must guard against multiple definitions for a single private capability. (For example, you should include separate terminal entries for a terminal that requires PRIVATE_STR_1 to mean two different things, depending on the application program being run.) In general, you should not have to use private capabilities.

The following characters are used as delimiters in capability fields:

DelimiterMeaning
!Begins a comment
=Separates a capability field name from its value
,Separates capability fields
"Delimits strings

5.2.1. Boolean Capability Fields

Boolean capabilities are either present or not present for a given terminal.

The format for a Boolean capability field is as follows:
BOOLEAN {Boolean-capability = binary-digit} [,...]

Following are the meanings of the elements:

  • Boolean-capability—One of the capability fields listed in Table 5.1

  • Binary-digit—Either 1 or 0

Table 5.1. Boolean Capabilities
Capability FieldUsed by SMGMeaning if Set
ADVANCED_VIDEONThe terminal has advanced video attributes and is capable of 132-column mode operation.
ANSI_COLORNTerminal conforms to ANSI color programming standards.
ANSI_CRTNTerminal conforms to ANSI CRT programming standards.
AUTO_MARGINNTerminal has automatic margins.
BACKSPACEYTerminal can backspace with Ctrl/H.
BLOCK_MODENTerminal can perform block mode transmission, local editing, and field protection.
CURSOR_REPORT_ANSINTerminal uses the ANSI sequence to report the current cursor location.
DEC_CRTNTerminal conforms to VT100 family standards.
DEC_CRT_2NTerminal conforms to VT200 family standards.
DEC_CRT_3NTerminal conforms to VT300 family standards.
DEC_CRT_4NTerminal conforms to VT400 family standards.
DEC_CRT_5NTerminal conforms to VT500 family standards.
EDITNTerminal can perform ANSI-defined advanced editing functions.
EIGHT_BITNTerminal uses 8-bit ASCII character code.
FULLDUPNTerminal operation mode is full-duplex (half-duplex if not set).
IGNORE_NEWLINENTerminal ignores a newline after a wrap.
INSERT_MODE_NULLSNInsert mode distinguishes nulls on display.
LOWERCASENTerminal has both uppercase and lowercase letters.
NO_ERASENStandout (bolded) characters are not erased by writing over them.
NO_SCROLLNTerminal is not capable of scrolling.
OVERSTRIKENTerminal is capable of overstriking.
PHYSICAL_FFNTerminal can accept form feeds (if not set, terminal driver must translate form feeds to multiple line feeds).
PHYSICAL_TABSNTerminal has hardware tabs (note that these tabs may need to be set with an initialization string).
PRINTER_PORTNTerminal has a printer port available.
PRIVATE_BOO_1 to 10NThese fields denote user-defined capabilities 1 through 10.
REGISNTerminal understands ReGIS graphics commands.
SCOPENTerminal is a video terminal.
SET_CURSOR_COL_ROWYTerminal uses column/row addressing.
SIXEL_GRAPHICSNTerminal can display graphics using the ReGIS-defined SIXEL graphics protocol.
SOFT_CHARACTERSNTerminal can load a user-defined character set.
UNDERLINENTerminal has underlining capability (but not overstrike).
For example, the following TERMTABLE entry describes two characteristics of a VT300 series terminal:
NAME = "VT300_series"

  BOOLEAN

    ansi_crt = 1,         dec_crt = 1

This entry specifies that the terminal conforms to ANSI CRT programming standards and to VT300 series standards.

5.2.2. Numeric Capability Fields

Numeric capabilities take a numeric argument; for example, the number of columns on the terminal screen.

The format for a numeric capability field is as follows:
NUMERIC {numeric-capability = value} [,...]

Following are the meanings of the elements:

  • Numeric-capability—One of the capability fields listed in Table 5.2

  • Value—The value for the specified numeric capability

Table 5.2. Numeric Capabilities
OpenVMS NameUsed by SMGDescription
COLUMNSYSpecifies the number of columns in a line.
CR_FILLNSpecifies the number of fill characters needed after a carriage return.
LF_FILLNSpecifies the number of fill characters needed after a line feed.
FRAMENControls the number of data bits expected by the terminal driver for every character that is input or output (value must be between 5 and 8, inclusive).
NUMBER_FN_KEYSNSpecifies the number of function keys available.
PRIVATE_NUM_1 to 10NIf set, these fields denote user-defined capabilities 1 through 10.
ROWSNSpecifies the number of rows on the screen.
WIDE_SCREEN_COLUMNSYSpecifies the number of columns available in wide mode.
For example, the following TERMTABLE entry describes two characteristics of a VT300-series terminal:
NAME = "VT300_series"

  NUMERIC

    rows = 24,         columns = 80

5.2.3. String Capability Fields

String capability fields provide several features. They let you do the following:

  • Supply alternate characters for line drawing

  • Provide icons so that your program can display carriage control characters (for example, form feeds) instead of executing them

  • Supply the character sequences that cause a given operation (for example, ERASE_TO_END_OF_LINE) to be performed on any type of terminal

  • Specify the character strings returned by special keys (for example, function keys) on a given terminal

  • Specify strings having a maximum length of 255 characters (the maximum length of a string depends on its complexity, but in no case can it be longer than 255)

Table 5.3 lists string capabilities.

Table 5.3. String Capabilities
OpenVMS NameUsed by SMGDescription
BEGIN_ALTERNATE_CHARNBegins alternate character set.
BEGIN_AUTOPRINT_MODENBegins autoprint mode.
BEGIN_AUTOREPEAT_MODENBegins autorepeat mode.
BEGIN_AUTOWRAP_MODENBegins autowrap mode.
BEGIN_BLINKYBegins blinking characters.
BEGIN_BOLDYBegins bolded characters.
BEGIN_DELETE_MODENBegins delete mode.
BEGIN_INSERT_MODENBegins insert mode.
BEGIN_LINE_DRAWING_CHARYBegins using line-drawing character set.
BEGIN_NORMAL_RENDITIONYBegins using normal video attributes.
BEGIN_REVERSEYBegins reverse video characters.
BEGIN_UNDERSCOREYBegins underscored characters.
BOTTOM_T_CHARYDisplays line-drawing character bottom t.
CLEAR_TABNClears tab at current column.
CR_GRAPHICYDefines character to indicate a carriage return when control characters are being represented rather than executed.
CROSS_CHARYDefines character to represent the intersection of perpendicular lines.
CURSOR_DOWNNMoves cursor n lines down (does not cause scrolling).
CURSOR_LEFTNMoves cursor n positions to the left.
CURSOR_NEXT_LINENAccepts an argument n and moves the cursor to the first position in the nth following line.
CURSOR_POSITION_REPORTNReports the active position using two arguments.
CURSOR_PRECEDING_LINENAccepts an argument n and moves the cursor to the first position in the nth preceding line.
CURSOR_RIGHTNAccepts an argument n and moves the cursor n positions to the right.
CURSOR_UPNAccepts an argument n and moves cursor up n lines (does not cause scrolling).
DARK_SCREENYMakes screen background color dark (normal video).
DELETE_CHARNAccepts an argument n and deletes n characters.
DELETE_LINENAccepts an argument n and deletes n lines.
DEVICE_ATTRIBUTESNTerminal's response to a "What are you?" sequence.
DOUBLE_HIGH_BOTTOMYChanges line to double height bottom half.
DOUBLE_HIGH_TOPYChanges line to double height top half.
DOUBLE_WIDEYChanges line to double width.
END_ALTERNATE_CHARNEnds alternate character set.
END_AUTOPRINT_MODENEnds autoprint mode.
END_AUTOREPEAT_MODENEnds autorepeat mode.
END_AUTOWRAP_MODENEnds autowrap mode.
END_BLINKNEnds blinking characters.
END_BOLDNEnds bolding mode.
END_DELETE_MODENEnds delete mode.
END_INSERT_MODENEnds insert mode.
END_LINE_DRAWING_CHARYEnds line-drawing characters.
END_REVERSENEnds reverse video characters.
END_UNDERSCORENEnds underscore.
ERASE_DISPLAY_TO_CURSORNErases display to virtual cursor position.
ERASE_LINE_TO_CURSORNErases line to virtual cursor position.
ERASE_TO_END_DISPLAYNErases to end of display.
ERASE_TO_END_LINEYErases to end of line.
ERASE_WHOLE_DISPLAYYErases whole display.
ERASE_WHOLE_LINENErases whole line.
ERROR_ICONYDefines character that indicates an error.
FF_GRAPHICYUses this character to indicate a form feed when control characters are displayed rather than executed.
HOMEYDefines home cursor.
HORIZONTAL_BARYDisplays line-drawing character horizontal bar.
HT_GRAPHICYUses this character to indicate a horizontal tab when control characters are displayed rather than executed.
INDEXNMoves the cursor down one line without changing the column position (contents of the screen scroll up if necessary).
INIT_STRINGYDefines terminal initialization string.
INSERT_CHARNAccepts an argument n and inserts n characters.
INSERT_LINENAccepts an argument n and inserts n lines.
INSERT_PADNAccepts an argument n and inserts n pad characters after character inserted.
KEY_0YReturned by keypad 0 in applications mode.
KEY_1YReturned by keypad 1 in applications mode.
KEY_2YReturned by keypad 2 in applications mode.
KEY_3YReturned by keypad 3 in applications mode.
KEY_4YReturned by keypad 4 in applications mode.
KEY_5YReturned by keypad 5 in applications mode.
KEY_6YReturned by keypad 6 in applications mode.
KEY_7YReturned by keypad 7 in applications mode.
KEY_8YReturned by keypad 8 in applications mode.
KEY_9YReturned by keypad 9 in applications mode.
KEY_BACKSPACENReturned by backspace key.
KEY_COMMAYReturned by keypad comma key.
KEY_DOWN_ARROWYReturned by down arrow key.
KEY_E1YReturned by E1 (editing key 1).
KEY_E2YReturned by E2 (editing key 2).
KEY_E3YReturned by E3 (editing key 3).
KEY_E4YReturned by E4 (editing key 4).
KEY_E5YReturned by E5 (editing key 5).
KEY_E6YReturned by E6 (editing key 6).
KEY_ENTER (k)YReturned by keypad enter key.
KEY_F1YReturned by F1 (function key 1).

.
.
.

 

.
.
.

KEY_F20YReturned by F20 (function key 20).
KEY_LABEL_F1NLegend on F1 (function key 1).

.
.
.

 

.
.
.

KEY_LABEL_F20NLegend on F20 (function key 20).
KEY_LEFT_ARROWYReturned by left arrow key.
KEY_MINUSYReturned by keypad minus key.
KEY_PERIODYReturned by keypad period key.
KEY_PF1YReturned by PF1 key.
KEY_PF2YReturned by PF2 key.
KEY_PF3YReturned by PF3 key.
KEY_PF4YReturned by PF4 key.
KEY_RIGHT_ARROWYReturned by right arrow key.
KEY_UP_ARROWYReturned by up arrow key.
LEFT_T_CHARYDisplays line-drawing character left t.
LF_GRAPHICYUses this character to indicate a line feed when control characters are displayed rather than executed.
LIGHT_SCREENYMakes screen background color light (reverse video).
LOWER_LEFT_CORNERYDisplays line-drawing character lower left corner.
LOWER_RIGHT_CORNERYDisplays line-drawing character lower right corner.
NAMEYDefines terminal name; must be the first field in the entry.
NEWLINE_CHARNDefines new-line character.
NEXT_LINENDisplays next line.
NO_PRINTERNDefines no attached printer status.
PAD_CHARNDefines pad character (if other than null).
PRINT_SCREENNPrints contents of screen.
PRINTER_READYNDefines printer ready status.
PRINTER_NOT_READYNDefines printer not ready status.
PRIVATE_STR_1NUser-defined capability 1.

.
.
.

 

.
.
.

PRIVATE_STR_10NUser-defined capability 10.
REQUEST_CURSOR_POSITIONNRequests the active cursor position.
REQUEST_PRINTER_STATUSNRequests status of attached printer.
RESTORE_CURSORNRestores cursor to previously saved position.
REVERSE_INDEXNMoves the cursor to the same column on the preceding line (contents of the screen scroll down if necessary).
RIGHT_T_CHARYDisplays line-drawing character right t.
SAVE_CURSORNSaves cursor position.
SCROLL_FORWARDNAccepts an argument n and scrolls forward n lines.
SCROLL_REVERSEYAccepts an argument n and scrolls backward n lines.
SEL_ERASE_TO_END_DISPLAYNSelectively erases from cursor to end of display (does not change attributes).
SEL_ERASE_TO_END_LINENSelectively erases from cursor to end of line (does not change attributes).
SEL_ERASE_WHOLE_DISPLAYNSelectively erases entire display (does not change attributes).
SEL_ERASE_WHOLE_LINENSelectively erases entire line (does not change attributes).
SET_APPLICATION_KEYPADYBegins applications keypad mode.
SET_CHAR_NOT_SEL_ERASENDesignates all subsequent characters as not selectively erasable.
SET_CHAR_SEL_ERASENDesignates all subsequent characters as selectively erasable.
SET_CURSOR_ABSYDirects cursor addressing (accepts row and column arguments).
SET_CURSOR_OFFYSets cursor to invisible.
SET_CURSOR_ONYSets cursor to visible.
SET_JUMP_SCROLLYSets scrolling to jump scroll.
SET_NUMERIC_KEYPADYEnds keypad applications mode (resumes numeric mode).
SET_ORIGIN_ABSOLUTENAllows cursor positioning outside current scrolling region.
SET_ORIGIN_RELATIVENProhibits cursor positioning outside current scrolling region.
SET_PRINTER_OUTPUTNSends output to printer port rather than screen.
SET_SCREEN_OUTPUTNSends output to terminal screen.
SET_SCROLL_REGIONYSets scrolling region (accepts as arguments top margin and bottom margin).
SET_SMOOTH_SCROLLYSets scrolling to smooth scroll.
SET_TABNSets tab at current column.
SINGLE_HIGHYChanges this line to single height, single width.
TAB_CHARNDefines tab character (other than Ctrl/I or tab with padding); note that this field should be used only for non-ASCII terminals.
TOP_T_CHARYDisplays line-drawing character top t.
TRUNCATION_ICONYDefines the character that indicates overflow characters were truncated.
UNDERLINE_CHARNUnderlines a character.
UPPER_LEFT_CORNERYDisplays line-drawing character upper left corner.
UPPER_RIGHT_CORNERYDisplays line-drawing character upper right corner.
VERTICAL_BARYDisplays line-drawing character vertical bar.
VT_GRAPHICYDefines the character that indicates a vertical tab when control characters are displayed rather than executed.
WIDTH_NARROWYSets terminal width to narrow (usually 80 columns).
WIDTH_WIDEYSets terminal width to wide (usually 132 columns).

Table 5.4 lists the STRING_2 capabilities. In order to construct 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.

Table 5.4. String_2 Capabilities
OpenVMS NameUsed by SMGDescription
BEGIN_STATUS_LINEYBegins output to hardware status line.
BEGIN_USER1YBegins first user-defined attribute.
BEGIN_USER2YBegins second user-defined attribute.
BEGIN_USER3YBegins third user-defined attribute.
BEGIN_USER4YBegins fourth user-defined attribute.
BEGIN_USER5YBegins fifth user-defined attribute.
BEGIN_USER6YBegins sixth user-defined attribute.
BEGIN_USER7YBegins seventh user-defined attribute.
BEGIN_USER8YBegins eighth user-defined attribute.
END_STATUS_LINEYEnds output to hardware status line.
END_USER1NEnds first user-defined attribute.
END_USER2NEnds second user-defined attribute.
END_USER3NEnds third user-defined attribute.
END_USER4NEnds fourth user-defined attribute.
END_USER5NEnds fifth user-defined attribute.
END_USER6NEnds sixth user-defined attribute.
END_USER7NEnds seventh user-defined attribute.
END_USER8NEnds eighth user-defined attribute.
BLACK_SCREENYMakes screen background color black.
BLUE_SCREENYMakes screen background color blue.
CYAN_SCREENYMakes screen background color cyan (green-blue).
GREEN_SCREENYMakes screen background color green.
MAGENTA_SCREENYMakes screen background color magenta.
RED_SCREENYMakes screen background color red.
WHITE_SCREENYMakes screen background color white.
YELLOW_SCREENYMakes screen background color yellow.
USER1_SCREENYUser-defined background color.
USER2_SCREENYUser-defined background color.
Because string capability fields often include nonprinting characters, the following substitutions are used to make it easy to insert these characters in a capability string. Use the special character to represent the nonprinting character.
Special CharacterNonprinting CharacterMeaning
$ESCAPEASCII decimal value 27
^CONTROLControl
&CSIASCII decimal value 155
@SS3ASCII decimal value 143
Thus to create a capability string that contains an escape character, you insert a dollar sign at that position. To create a capability string that contains a control character, prefix the character with a circumflex (^). For example:
NAME = "VT300_series"

  .
  .
  .

    STRING
        begin_alternate_char = "^N",
        end_alternate_char = "^O",
        erase_whole_display = "$[2J"

  .
  .
  .

END

If you want to use a character in a capability string with its normal ASCII value, place an underscore in front of it. (For example, "_$" results in a single dollar sign rather than an underscore followed by an escape character). The following characters must be preceded by an underscore in order to be treated as normal ASCII text:

Ampersand&
Apostrophe'
At sign@
Quotation marks"
Circumflex^
Dollar sign$
Exclamation point!
Left parenthesis(
Underscore_

The Screen Management Facility automatically invokes the graphics mode needed to display the line-drawing character set (for example, the bottom_t_char, top_t_char, and so on). However, if you call the foreign terminal routines directly, you are responsible for invoking the required graphics mode.

Padding (for example, with null characters) must sometimes be added to a terminal command to allow the terminal sufficient time to execute the command. The amount of padding needed depends on the terminal and the baud rate. The pad character capability field is included only for future expansion and has no function in this release; padding is the responsibility of the user.

When the foreign terminal support routines are called directly, many of the string capability fields use arguments whose values must be specified at run time. Further, some arguments also require that arithmetic operations be performed when values are substituted for arguments. The following sections describe argument substitution and arithmetic operations.

5.2.4. Argument Substitution

It is frequently necessary to substitute values in a terminal command string. For example, setting a scrolling region or moving the cursor ten columns to the right requires the run-time substitution of a value; these values cannot be stored in the TERMTABLE terminal definition. TERMTABLE provides for string substitution by accepting !UL, an $FAO style directive. The !UL directive signifies that a value is to be inserted at that point: the TERMTABLE interface routine is to accept an unsigned longword and convert it to ASCII digits before substituting it in the capability field string (and thus in the returned command string). For example:
NAME = "VT300_series"

  .
  .
  .

    STRING
    set_cursor_abs = "$[!UL;!ULH"

  .
  .
  .

END

The string defined for the SET_CURSOR_ABS function must have values substituted for the two !UL directives; these values specify the row and column number at which to set the cursor. You specify these run-time arguments as an optional longword vector argument to the SMG$GET_TERM_DATA routine. The first entry in the vector contains the number of arguments that follow. Thus, the first entry is 2, the second entry is the desired row number, and the third entry is the desired column number. The SMG$GET_TERM_DATA routine converts the first optional data item (the second item in the vector) to ASCII digits and substitutes an ASCII value for the first !UL directive; it converts the second optional data item and substitutes it for the second !UL directive, and so on.

5.2.5. Arithmetic Operations

In addition to argument substitution, terminal command sequences may also require arithmetic operations. To perform an argument substitution and arithmetic operation, the TERMTABLE entry requires a different scheme than for argument conversion and substitution.

To perform both argument substitution and arithmetic operations, you use an opening parenthesis, a percent sign (to indicate the point of substitution), an arithmetic operator, an operand, and a closing parenthesis. For example:
NAME = "VT52"

  .
  .
  .

    STRING
    set_cursor_abs = "$Y(%1+31)(%2+31)"

  .
  .
  .

END

This example shows the string that directly positions the cursor on a VT52, where a bias must be added to the row and column numbers. Values to be substituted in the expression are passed with the SMG$GET_TERM_DATA routine, in the same way as for argument substitution alone. The percent sign is always followed by an integer that indicates the order in which arguments should be substituted.

The following table summarizes the characters used in arithmetic operations:

CharacterMeaning
(Beginning of arithmetic expression
% nSubstitute nth user argument
+Arithmetic addition operator
-Arithmetic subtraction operator
*Arithmetic multiplication operator
/Arithmetic division operator
)End of arithmetic expression

Longword integers are sufficient to express screen coordinates. Expressions are evaluated from left to right; there is no operator precedence.

Spaces between items are not significant; they may be used wherever desired to improve readability. Capability strings are limited to 128 bytes in length.

5.3. Creating an OpenVMS Terminal Capabilities File

The source code for the database is an ASCII file named TERMTABLE.TXT. This file contains an entry for each type of terminal. Each entry lists a terminal's capabilities and other device-specific information, such as initialization sequences and screen size; a TERMTABLE entry can span more than one record in the file. A terminal definition can be added by editing the TERMTABLE.TXT file; TERMTABLE.TXT must then be reprocessed by running SYS$SYSTEM:SMGBLDTRM.EXE.

TERMTABLE.TXT can be created with any text editor. A TERMTABLE entry consists of a terminal name, followed by any number of capability fields and their values (see Section 5.2 for more information about capability fields). Although TERMTABLE.TXT must be formatted for compilation, capability names are descriptive and can be easily understood. Terminal names must be unique; for example, if more than one definition is needed for a foreign terminal, then a second name must be used.

When a TERMTABLE routine first searches for a terminal entry, it tries to find TERMTABLE.EXE in the area logically named TERM$TABLOC. If the specified terminal entry is not found there, the routine then searches for TERMTABLE.EXE in SYS$SYSTEM. If you want to use a terminal definition that differs from the system definition for that terminal, you can create a private copy of TERMTABLE.TXT and TERMTABLE.EXE. You can then define a single terminal with a definition that is different from the one in SYS$SYSTEM:TERMTABLE.EXE and still use the rest of the standard system definitions.

The format of a TERMTABLE entry is as follows:
NAME = "terminal-name" capability-field [,...] END
The TERMTABLE.TXT file allows you to include REQUIRE directives. The REQUIRE directive lets you include separate source files in the TERMTABLE.TXT file. Its format is as follows:
REQUIRE "filespec"

In the above format, "filespec" is a valid OpenVMS file specification.

5.4. Examples

The following example contains sample terminal definitions for the TERMTABLE.TXT file; these entries contain device-specific information for a VT300 terminal and a VT52 terminal.
!
!       Private versions of terminal definitions
!
NAME = 'myvt300'

        BOOLEAN
        ansi_crt = 1,           dec_crt = 1

        NUMERIC
        rows = 24,              columns = 80,
        wide_screen_columns = 132

        STRING
        begin_alternate_char = "^N",
        end_alternate_char = "^O",
        erase_whole_display = "$[2J",
        init_string = "$_(B",
        set_cursor_abs = "$[!UL;!ULH"
END

NAME = "MYVT52"

        BOOLEAN
        ansi_crt = 0,           dec_crt = 1

        NUMERIC
        rows = 24,              columns = 80,
        wide_screen_columns = 80

        STRING
        begin_alternate_char = "$F"
        end_alternate_char = "$G",
        erase_whole_display = "$Y(32)(32)$J",  !position to 1,1; then erase
        set_cursor_abs = "$Y(%1+31)(%2+31)"

END

For the set cursor sequence listed for a VT300 series (MYVT300), the string returned depends on the values provided in the argument vector supplied with the call to the SMG$GET_TERM_DATA routine. For example, to position the cursor to row 3 and column 12, you supply these longword values as the second and third entries in the vector (the first entry is the number of values that follow). The SMG$GET_TERM_DATA routine converts these longword values into their ASCII values and inserts the converted values into the string returned at the point of the respective !UL directives.

For the set cursor sequence listed for a VT52 (MYVT52), the string returned depends not on argument substitution, but on an arithmetic operation (because the VT52 requires biasing). The arithmetic operator is used to add 31 (decimal) to the row and column numbers supplied in entries 2 and 3 of the argument vector for the SMG$GET_TERM_DATA routine.

The INIT_STRING field in MYVT300 is included to point out that the parenthesis is normally treated as a special character indicating an arithmetic expression. A parenthesis must be preceded by an underscore in order to be interpreted as a normal text character. Thus the string "$_(B" yields ESC(B, a command that designates the ASCII character set into G0.

The ERASE_WHOLE_DISPLAY sequence for MYVT52 shows that it may be necessary to combine sequences in order to provide a certain function. The VT52 does not have a command that erases the entire screen. However, you can erase the entire screen by homing the cursor and then using the command that erases from the current position to the end of the screen.

The following BASIC example program uses the LIB$GETDVI routine to ascertain the type of terminal associated with SYS$OUTPUT. The program then uses the foreign terminal routines to place the cursor at the twelfth screen line and to erase to the end of the screen. The program detects whether these capabilities are available for the terminal and displays an error message if they are not.
10  ! Program to call the Termtable interface routines
    !
    ! This program sets the cursor to row 12 column 1,
    ! and erase to the bottom of the screen.  If the cursor
    ! positioning or erasing to the end of the screen
    ! capabilities are not defined, a message is output.

    %INCLUDE "$SMGTRMPTR" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
    OPTION TYPE = EXPLICIT, SIZE = INTEGER LONG

    EXTERNAL INTEGER FUNCTION SYS$ASSIGN, SYS$DASSGN, SYS$QIOW
    EXTERNAL INTEGER FUNCTION LIB$GETDVI, LIB$GET_EF, LIB$FREE_EF
    EXTERNAL INTEGER FUNCTION SMG$INIT_TERM_TABLE_BY_TYPE, SMG$GET_TERM_DATA

    EXTERNAL INTEGER CONSTANT IO$_WRITEVBLK, DVI$_DEVTYPE

    COMMON (buf) STRING Data_buffer = 20         ! buffer to hold terminal data

    DECLARE INTEGER Sys_status,                   &
                    Chan,                         &
                    Term_type,                    &
                    Term_table_addr,              &
                    Arg_vector (2),               &
                    Ret_len,                      &
                    Event_flag

    ! Assign a channel for LIB$GETDVI and SYS$QIOW.

    Sys_status = SYS$ASSIGN ('SYS$OUTPUT', Chan, , , )

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error from SYS$ASSIGN : ";Sys_status
      GOTO Done
    END IF

    ! Get the terminal type.

    Sys_status = LIB$GETDVI (DVI$_DEVTYPE   ! request item code              &
                             ,Chan          ! channel assigned to SYS$OUTPUT &
                             ,              ! omit device name               &
                             ,Term_type)    ! place to return type

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error from LIB$GETDVI : ";Sys_status
      GOTO Done
    END IF

    ! Get the definition for the type of terminal we are running on.

    Sys_status =  SMG$INIT_TERM_TABLE_BY_TYPE (Term_type, Term_table_addr)

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error getting terminal definition : ";Sys_status
      GOTO Done
    END IF

    ! Get the sequence to position the cursor to 12,1

    Arg_vector (0) = 2%             ! number of args to follow
    Arg_vector (1) = 12%            ! row number
    Arg_vector (2) = 1%             ! column number

    Sys_status = SMG$GET_TERM_DATA                                        &
                    ( Term_table_addr       ! addr of terminal definition &
                      ,SMG$K_SET_CURSOR_ABS ! request code                &
                      ,20%                  ! max buffer length           &
                      ,Ret_len              ! length of sequence returned &
                      ,Data_buffer BY REF   ! buffer to hold sequence     &
                      ,Arg_vector (0) )     ! optional vector with
                                            ! row and column numbers

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error getting cursor sequence : ";Sys_status
      GOTO Done
    END IF

    IF Ret_len = 0%
    THEN
      PRINT "Cursor sequence not available"
      GOTO Done
    END IF

    ! Get a unique event flag number

    Sys_status = LIB$GET_EF (Event_flag)

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Unable to allocate an event flag"
      GOTO Done
    END IF

    ! Output the cursor sequence to the terminal.

    Sys_status = SYS$QIOW ( Event_flag BY VALUE     ! event flag number  &
                            ,Chan BY VALUE          ! channel number     &
                            ,IO$_WRITEVBLK BY VALUE ! function code      &
                            , , ,                   ! no iosb,           &
                                                    ! ast routine,       &
                                                    ! or  argument       &
                            ,Data_buffer BY REF     ! buffer to output   &
                            ,Ret_len BY VALUE       ! bytes returned     &
                            , , , , )               ! null arguments

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error from SYS$QIOW : ";Sys_status
      GOTO Done
    END IF

    ! Get the sequence to erase from current cursor to end of screen.

    Sys_status = SMG$GET_TERM_DATA                                           &
                         ( Term_table_addr ! addr of terminal definition     &
                           ,SMG$K_ERASE_TO_END_DISPLAY ! request code        &
                           ,20%                        ! max buffer length   &
                           ,Ret_len                    ! bytes returned      &
                           ,Data_buffer BY REF)        ! buffer for sequence

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error getting erase sequence : ";Sys_status
      GOTO Done
    END IF

    IF Ret_len = 0%
    THEN
      PRINT "Erase sequence not available"
      GOTO Done
    END IF

    ! Output the erase sequence to the terminal.

    Sys_status = SYS$QIOW (Event_flag BY VALUE          ! event flag number    &
                                ,Chan BY VALUE          ! channel number       &
                                ,IO$_WRITEVBLK BY VALUE ! function code value  &
                                , , ,                   ! no iosb,             &
                                                        ! ast routine,         &
                                                        ! or  argument         &
                                ,Data_buffer BY REF     ! buffer to output     &
                                ,Ret_len BY VALUE       ! bytes in buffer      &
                                , , , , )               ! null arguments

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error from SYS$QIOW : ";Sys_status
      GOTO Done
    END IF

    ! Deassign the channel.

    Sys_status = SYS$DASSGN (Chan BY VALUE)

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Error from SYS$DASSGN : ";Sys_status
      GOTO Done
    END IF

    ! Deallocate event flag so other programs can use it.

    Sys_status = LIB$FREE_EF (Event_flag)

    IF (Sys_status AND 1%) = 0%
    THEN
      PRINT "Unable to deallocate event flag"
      GOTO Done
    END IF

32767  Done: END

5.5. Creating TERMTABLE.EXE

Accessing an ASCII file for each screen program is inefficient because the ASCII text must be processed as binary information before it can be returned as a string ready for the terminal. To avoid paying the price of this processing at the start of every image, TERMTABLE.TXT is "precompiled" into the required binary format. A screen application then gets its terminal sequences from the precompiled binary capabilities file.

Compile TERMTABLE.TXT by running the SYS$SYSTEM:SMGBLDTRM.EXE program. This utility accepts TERMTABLE.TXT as an input file and creates TERMTABLE.EXE as an output file on the device and directory pointed to by the logical TERM$TABLOC.

The compiled terminal capabilities are stored as a table in a file which is mapped as a permanent global section. Thus, user programs map to the global section rather than having their own copies of the capabilities data.

If a user compiles a private TERMTABLE.TXT from his or her own directory, the interface routines access it by mapping it as a temporary section. TERMTABLE interface routines look for a definition in the temporary section before looking in the system's permanent global section.

Note that system managers may want to coordinate terminal definitions so that nonstandard definitions are confined to a user's private area.

Most users do not have the privilege to create a permanent global section. A short program, SYS$SYSTEM:SMGMAPTRM.EXE, that maps the compiled TERMTABLE as a global section, is part of the standard OpenVMS startup procedure. In order to map an updated TERMTABLE.EXE as the global section, the existing global section must first be deleted. Deleting the global section while the system is active may cause a user's program to fail; therefore the system must be rebooted in order to make an updated TERMTABLE.EXE the default.

To reduce compiling time and the size of the resulting global section, the terminal definitions in SYS$SYSTEM:TERMTABLE.TXT should be kept to a minimum. Only the types of terminals that are actually attached to the computer system should be defined.

5.6. Capability Fields Used by Screen Management

The tables in Section 5.2 show whether or not the Screen Management Facility can request a particular capability string. Some functions, such as wide characters or line drawing, are requested only if the user calls the screen management routines that output wide text or draw lines. If all you want to do is write normal text to the screen, only the following set of fields needs to be defined.

Essential Capabilities

  • NAME

  • SET_CURSOR_ABS

If SET_CURSOR_ABS is omitted, the Screen Management Facility treats the terminal as a hardcopy device. (For more information on using the Screen Management Facility with a hardcopy device, refer to the SMG$SNAPSHOT routine.

Operation of the Screen Management Facility is more efficient if the following optional capabilities are also provided:

  • ERASE_TO_END_DISPLAY

  • ERASE_TO_END_LINE

  • SET_SCROLLING_REGION

If you do not include ERASE_TO_END_DISPLAY, ERASE_TO_END_LINE, or SET_SCROLLING_REGION, the Screen Management Facility inserts blanks to perform these functions. However, inserting blanks is a slower operation. Similarly, hardware scrolling also improves output speed; if scrolling is not available, the Screen Management Facility must rewrite the entire screen.

The Screen Management Facility uses the ASCII character set. If your terminal has a line-drawing character set, you should define the line drawing characters (bottom_t_char, horizontal_bar, and so forth). If line-drawing characters are not defined, the Screen Management Facility uses normal ASCII characters to draw borders.

The Screen Management Facility also relies on the terminal characteristics maintained by the terminal driver. You can change these characteristics with the DCL command SET TERMINAL. For example, if you type SET TERMINAL/NOTAB, then the Screen Management Facility does not send tabs to the terminal.

5.7. Input Support for Foreign Terminals

A foreign terminal is any terminal for which the device type is not one of the standard terminals recognized by the OpenVMS operating system, or any terminal on which the ANSI_CRT characteristic is not set.

When you use an ANSI terminal, typing a special key such as a function key or a keypad key sends an escape sequence (as defined by the ANSI standard) to the OpenVMS terminal driver. The OpenVMS terminal driver understands this ANSI standard and interprets the escape sequence according to this standard. Thus, the OpenVMS terminal driver knows how long the escape sequence is and what characters are allowed in which positions in that sequence.

The OpenVMS terminal driver does not echo any of the printing characters from the sequence because those characters are interpreted with special meaning as part of the escape sequence. Normal keys are echoed unless the TRM$M_TM_NOECHO modifier is specified.

The OpenVMS terminal driver returns to the Screen Management Facility the sequence, the length of the sequence, and the number of characters entered before the function key was pressed. The Screen Management Facility determines which key was pressed by comparing the sequence and its length against the list of key definitions for that particular terminal in TERMTABLE.EXE. This code is returned to the user in the format SMG$K_TRM_xxx, where xxx is used to specify the particular key.

When you press a special key such as a function key or a keypad key on a foreign terminal, a non-ANSI sequence is sent to the OpenVMS terminal driver. If this sequence starts with a control character, the OpenVMS terminal driver interprets this character as a terminator. (By default all control characters are terminators unless you use a terminator mask to specify otherwise.) The terminal driver then stops reading characters and returns to the Screen Management Facility the character, a length of 1, and the number of characters entered before the function key was pressed.

The Screen Management Facility looks at the returned character. If it is a control character, the Screen Management Facility looks in the type-ahead buffer for the next characters of the sequence. If there are characters in the type-ahead buffer, the Screen Management Facility reads one character from the type-ahead buffer, appends it to the control sequence it has already, and checks this new sequence against the list of key definitions for this terminal in TERMTABLE.EXE to determine which key was pressed. If the sequence is not matched, the next character is read from the type-ahead buffer. This continues until a match is found or the type-ahead buffer is empty. Since the terminal driver does not know about this sequence, any printable characters in the sequence are echoed by the terminal driver unless the noecho modifier was specified by the user. Because the Screen Management Facility does not know what characters make up this sequence, it disables line editing in order to allow the actual characters that make up the sequence to be returned to the Screen Management Facility.

Terminals whose special keys send a sequence that does not start with a control character are not supported by the Screen Management Facility for input. Changing the terminator mask to exclude the control character that starts the function key sequence is not supported. In addition, the performance of a foreign terminal doing input will not match that of a non-foreign terminal doing the same input since SMG$ must parse the sequence in place of the OpenVMS terminal driver.

5.8. Support for SET and SHOW TERMINAL Commands

The DCL command SET TERMINAL is the mechanism for setting your terminal to conform to a TERMTABLE definition. SET TERMINAL causes the following three fields to be retrieved from the TERMTABLE database and set for your terminal:

  • Terminal type—A signed integer assigned by the system and associated with a particular device type

  • Width—The number of columns on the physical screen

  • Page size—The number of rows on the screen

In addition, if the corresponding Boolean capability is set in the terminal definition, the following flags are set:

  • ADVANCED_VIDEO

  • ANSI_COLOR

  • ANSI_CRT

  • BLOCK_MODE

  • DEC_CRT

  • EDIT

  • EIGHT_BIT

  • FORM

  • FULLDUP

  • LOWERCASE

  • REGIS

  • SCOPE

  • SIXEL_GRAPHICS

  • SOFT_CHARACTERS

  • TAB

If any of these fields is missing from your definition, the previous setting for that characteristic is retained; SET TERMINAL does not try to set that characteristic for your terminal. You should include all of the above capabilities in your definitions to avoid unpredictable settings.

SET TERMINAL operates as it always has for known terminals such as the VT300 series, VT200 series, VT100, and VT52. When SET TERMINAL encounters an unknown device name, it searches TERMTABLE for a definition with that name. Notice that your definitions must have names other than the names that SET TERMINAL currently recognizes. The terminals currently recognized are listed as follows:

LA12VT05VT131
LA34VT52VT132
LA36VT55VT200-SERIES
LA38VT100VT300-SERIES
LA100VT101VT400-SERIES
LA120VT102VT500-SERIES
LQP02VT125FT1 through FT8
Unknown

If SET TERMINAL finds the device name in its own internal tables, it does not search the TERMTABLE database.

Since the SET TERMINAL command recognizes only the first 15 characters of a device name, you may want to limit your terminal names to 15 characters.

The SET TERMINAL/DEVICE=name command causes the TERMTABLE database to be searched for the named terminal, if that terminal is unknown to the OpenVMS operating system. SET TERMINAL/DEVICE=name then sets various terminal characteristics, as shown in the following table, based on the presence of these capabilities in the TERMTABLE database:

Capability FieldTerminal Characteristic
LOWERCASELOWERCASE
PHYSICAL_TABSTABS
SCOPESCOPE
EIGHT_BITEIGHTBIT
PHYSICAL_FFFORM
FULLDUPFULLDUP
SIXEL_GRAPHICSSIXEL
SOFT_CHARACTERSSOFT
ANSI_CRTANSI_CRT
ANSI_COLORANSI_COLOR
REGISREGIS
BLOCK_MODEBLOCK
ADVANCED_VIDEOAVO
EDIT_MODEEDIT
DEC_CRTDEC_CRT

The SET TERMINAL/DEVICE_TYPE=format must be used with TERMTABLE terminals. SET TERMINAL/name is an old format that works for a small set of device names and is maintained only for compatibility with previous versions of the OpenVMS operating system.

Chapter 6. Using Screen Management Routines to Develop New Programs

This chapter discusses some recommended methods for using the Screen Management Facility for developing new programs.

Important

Screen management routines are not AST reentrant.

6.1. Calling Screen Management Routines

There are two ways in which an application can call screen management routines.

  • Directly

    Applications that call the Screen Management Facility directly already use pasteboards and virtual displays.

  • Indirectly

    This kind of application does not use the Screen Management Facility directly, but may use it in the course of invoking other routines.

    Because many callable routines may use the Screen Management Facility to produce their output, it is difficult to determine whether your application is in this category.

In either case, the calling routine is likely at some point to call a subsystem so that the subsystem can write data to the screen.

At some later point, the terminal user will want to remove the subsystem-specific display. However, if the subsystem created and used a virtual display to display the data, the display identifier is not available to the calling program and therefore the calling program cannot remove it. Furthermore, unless the calling program is a direct user of the Screen Management Facility, the screen's pasteboard identifier is also not available to it.

The solution is to require that all callable routines that use the Screen Management Facility, directly or indirectly, have an (optional) input argument for the pasteboard-id and an (optional) output argument for the virtual display-id. Passing the pasteboard and display identifiers lets you avoid accumulating subsystem-specific data on the screen that cannot be removed by the calling program.

These guidelines are developed as follows:

  • If the pasteboard-id argument is provided by the calling program, then:

    • The called program should not create a pasteboard of its own.

    • The called program must deliver all of its output to the pasteboard supplied by the calling program; that is, the called program may paste its displays only to the pasteboard specified by pasteboard-id.

    • The called program can delete any virtual displays it created by calling SMG$DELETE_VIRTUAL_DISPLAY, but it must not delete the pasteboard.

      Note that the called program should not simply call the SMG$UNPASTE_VIRTUAL_DISPLAY routine with the expectation that this virtual display can be reused in a later invocation. Since the called program and the calling program are sharing a pasteboard, the calling program may use the SMG$POP_VIRTUAL_DISPLAY routine to delete all displays created by the called program.

    • The called program must pass the pasteboard-id on to any routines it in turn calls. Thus all output is directed to the specified pasteboard.

  • If the pasteboard-id argument is not provided by the calling program, then:

    • The called program must create a pasteboard on its own. The called program may allocate any physical device for the pasteboard, unless specifically directed to a particular device by some other mechanism.

      The called program must check the status of the SMG$CREATE_PASTEBOARD call to see whether it created a unique pasteboard identifier or whether it received the pasteboard identifier of an already existing pasteboard. If the pasteboard already exists, the called program must not delete the pasteboard.

    • If the called routine creates a pasteboard and in turn calls subroutines that may use pasteboards, it should pass the pasteboard-id to the subroutines.

    • The called program can clean up by using the SMG$UNPASTE_VIRTUAL_DISPLAY routine, and the displays can be saved for reuse on a subsequent invocation if such a call seems likely. However, the SMG$UNPASTE_VIRTUAL_DISPLAY routine should be used only if the called program creates its own pasteboard, because in this case the calling program cannot delete the virtual displays created by the called program.

  • If the virtual display-id argument is provided by the calling program, then the calling program must clean up any virtual displays created by the called program. The called program must return to the calling program the identifier of the first virtual display pasted. The calling program can then remove this and all later-pasted virtual displays by calling the SMG$POP_VIRTUAL_DISPLAY routine.

  • If the virtual display-id argument is not provided by the calling program, the called program must remove all the virtual displays it pastes to the pasteboard.

By adhering to the following guidelines, you can develop your application in a modular fashion:

  • Calling programs control the pasteboard on which information is pasted. Pasteboard identifiers flow downward in a hierarchy, with each routine using the pasteboard-id provided by the caller and passing it along to subroutines.

  • If a calling program supplies a virtual display-id argument to be filled in by the called program, then the calling program assumes responsibility for cleaning up any displays created by the called program. The called program passes back the display-id of the first virtual display pasted so that the calling program can remove this and all later-pasted displays by calling the SMG$POP_VIRTUAL_DISPLAY routine.

  • Virtual displays are created (and pasted) in the routine where they are needed. If the calling program does not supply a display-id argument, then displays are unpasted and/or deleted in the routine that created them.

6.2. Calling Routines That Do Not Use the Screen Management Facility

A different situation exists if you call a subroutine (or subsystem) that writes to the screen without using the Screen Management Facility. When the Screen Management Facility is bypassed (that is, when text is placed on the screen outside screen management's control), problems result when an attempt is made to perform a screen update.

For this reason, the Screen Management Facility provides two routines for turning over the screen (or a part of it) temporarily to a program that does not use screen management, and for restoring the screen to its previous state after control is returned from the non-SMG$ routine. These routines are SMG$SAVE_PHYSICAL_SCREEN and SMG$RESTORE_PHYSICAL_SCREEN.

Before you call a routine that performs non-SMG$ I/O to the screen, you should call the SMG$SAVE_PHYSICAL_SCREEN routine, specifying what part of the screen is to be turned over to the non-SMG$ routine. SMG$SAVE_PHYSICAL_SCREEN erases the specified area, sets the terminal's physical scrolling region to this area, and sets the physical cursor to row 1, column 1 of the area. If the non-SMG$ code does only sequential input and output (that is, if it does no direct cursor addressing) its output will be confined to the specified area of the screen.

When control is returned from the non-SMG$ routine, you simply call SMG$RESTORE_PHYSICAL_SCREEN, which restores the screen image as it was before the call to SMG$SAVE_PHYSICAL_SCREEN.

Chapter 7. Examples of Calling SMG$ Routines

This chapter contains examples demonstrating how to call the routine SMG$READ_KEYSTROKE from the major programming languages. Note that not all of the languages represented in these examples are available on OpenVMS Alpha systems. The following languages are supported on Alpha systems:

AdaBASICBLISSC
C++COBOLFortranMACRO-32?
MACRO-64PascalPL/I

Other SMG$ routines such as SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD, SMG$CREATE_VIRTUAL_KEYBOARD, SMG$PASTE_VIRTUAL_DISPLAY, and SMG$PUT_LINE are also used throughout these examples.

Example 7.1 demonstrates the use of SMG$READ_KEYSTROKE from a VSI Ada program. This program also uses SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD, SMG$CREATE_VIRTUAL_KEYBOARD, SMG$PASTE_VIRTUAL_DISPLAY, and SMG$PUT_LINE.

Example 7.1. Using SMG$ Routines in VSI Ada
with SYSTEM, CONDITION_HANDLING; use SYSTEM;
package SMG is  -- declarations of SMG$ routines used

    procedure CREATE_VIRTUAL_DISPLAY (
        STATUS: out CONDITION_HANDLING.COND_VALUE_TYPE;
        ROWS, COLUMNS: INTEGER;
        DISPLAY_ID: out INTEGER;
        DISPLAY_ATTRIBUTES, VIDEO_ATTRIBUTES, CHAR_SET: UNSIGNED_LONGWORD
            := UNSIGNED_LONGWORD'NULL_PARAMETER);
    pragma INTERFACE (SMG, CREATE_VIRTUAL_DISPLAY);
    pragma IMPORT_VALUED_PROCEDURE
        (CREATE_VIRTUAL_DISPLAY, "SMG$CREATE_VIRTUAL_DISPLAY");

    procedure CREATE_PASTEBOARD (
        STATUS: out CONDITION_HANDLING.COND_VALUE_TYPE;
        PASTEBOARD_ID: out INTEGER;
        OUTPUT_DEVICE: STRING := STRING'NULL_PARAMETER;
        ROWS, COLUMNS: INTEGER := INTEGER'NULL_PARAMETER;
        PRESERVE_SCREEN_FLAG: BOOLEAN := BOOLEAN'NULL_PARAMETER);
    pragma INTERFACE (SMG, CREATE_PASTEBOARD);
    pragma IMPORT_VALUED_PROCEDURE
        (CREATE_PASTEBOARD, "SMG$CREATE_PASTEBOARD");

    procedure CREATE_VIRTUAL_KEYBOARD (
        STATUS: out CONDITION_HANDLING.COND_VALUE_TYPE;
        KEYBOARD_ID: out INTEGER;
        FILESPEC, DEFAULT_FILESPEC, RESULTANT_FILESPEC: STRING
            := STRING'NULL_PARAMETER);
    pragma INTERFACE (SMG, CREATE_VIRTUAL_KEYBOARD);
    pragma IMPORT_VALUED_PROCEDURE
        (CREATE_VIRTUAL_KEYBOARD, "SMG$CREATE_VIRTUAL_KEYBOARD");
    procedure PASTE_VIRTUAL_DISPLAY (
        STATUS: out CONDITION_HANDLING.COND_VALUE_TYPE;
        DISPLAY_ID, PASTEBOARD_ID: INTEGER;
        ROW, COLUMN: INTEGER);
    pragma INTERFACE (SMG, PASTE_VIRTUAL_DISPLAY);
    pragma IMPORT_VALUED_PROCEDURE
        (PASTE_VIRTUAL_DISPLAY, "SMG$PASTE_VIRTUAL_DISPLAY");

    procedure READ_KEYSTROKE (
        STATUS: out CONDITION_HANDLING.COND_VALUE_TYPE;
        KEYBOARD_ID: INTEGER;
        TERMINATOR_CODE: out UNSIGNED_WORD;
        PROMPT: STRING := STRING'NULL_PARAMETER;
        TIMEOUT, DISPLAY_ID: INTEGER := INTEGER'NULL_PARAMETER);
    pragma INTERFACE (SMG, READ_KEYSTROKE);
    pragma IMPORT_VALUED_PROCEDURE
        (READ_KEYSTROKE, "SMG$READ_KEYSTROKE");

    procedure PUT_LINE (
        STATUS: out CONDITION_HANDLING.COND_VALUE_TYPE;
        DISPLAY_ID: INTEGER;
        TEXT: STRING;
        LINE_ADVANCE: INTEGER := INTEGER'NULL_PARAMETER;
        RENDITION_SET, RENDITION_COMPLEMENT: UNSIGNED_LONGWORD
            := UNSIGNED_LONGWORD'NULL_PARAMETER;
        WRAP_FLAG: BOOLEAN := BOOLEAN'NULL_PARAMETER;
        CHAR_SET: UNSIGNED_LONGWORD := UNSIGNED_LONGWORD'NULL_PARAMETER);
    pragma INTERFACE (SMG, PUT_LINE);
    pragma IMPORT_VALUED_PROCEDURE
        (PUT_LINE, "SMG$PUT_LINE");
end SMG;

-- This routine demonstrates the use of the SMG$ routines, in particular
-- SMG$READ_KEYSTROKE.

with SMG, STARLET, CONDITION_HANDLING, SYSTEM;
procedure SMG_DEMO is
    STATUS: CONDITION_HANDLING.COND_VALUE_TYPE;
    PASTEBOARD_1, DISPLAY_1, KEYBOARD_1: INTEGER;
    TERMINATOR: SYSTEM.UNSIGNED_WORD;
begin
    -- Create virtual display, pasteboard and virtual keyboard.

    SMG.CREATE_VIRTUAL_DISPLAY (STATUS, ROWS => 7, COLUMNS => 60,
        DISPLAY_ID => DISPLAY_1,
        DISPLAY_ATTRIBUTES => STARLET.SMG_M_BORDER);
    SMG.CREATE_PASTEBOARD (STATUS, PASTEBOARD_ID => PASTEBOARD_1);
    SMG.CREATE_VIRTUAL_KEYBOARD (STATUS, KEYBOARD_ID => KEYBOARD_1);

    -- Paste the virtual display at row 3, column 9.

    SMG.PASTE_VIRTUAL_DISPLAY (STATUS, DISPLAY_ID => DISPLAY_1,
        PASTEBOARD_ID => PASTEBOARD_1, ROW => 3, COLUMN => 9);

    -- Write the instructions to the virtual display.
    SMG.PUT_LINE (STATUS, DISPLAY_ID => DISPLAY_1,
        TEXT => "Enter the character K after the >> prompt.");
    SMG.PUT_LINE (STATUS, DISPLAY_ID => DISPLAY_1,
        TEXT => "This character will not be echoed as you type it.");
    SMG.PUT_LINE (STATUS, DISPLAY_ID => DISPLAY_1,
        TEXT => "The terminal character equivalent of K is displayed.");
    SMG.PUT_LINE (STATUS, DISPLAY_ID => DISPLAY_1,
        TEXT => " ");

    -- Read the keystroke from the virtual keyboard.

    SMG.READ_KEYSTROKE (STATUS, KEYBOARD_ID => KEYBOARD_1,
        DISPLAY_ID => DISPLAY_1,
        TERMINATOR_CODE => TERMINATOR, PROMPT => ">>");

    -- Display the decimal value of the terminator code.

    SMG.PUT_LINE (STATUS, DISPLAY_ID => DISPLAY_1,
        TEXT => " ");
    SMG.PUT_LINE (STATUS, DISPLAY_ID => DISPLAY_1,
        TEXT => "TERMINAL CHARACTER IS " &
            SYSTEM.UNSIGNED_WORD'IMAGE(TERMINATOR));

end SMG_DEMO;
Example 7.2 uses SMG$READ_KEYSTROKE to read a keystroke from the terminal. This BASIC program also uses SMG$CREATE_VIRTUAL_KEYBOARD and SMG$DELETE_VIRTUAL_KEYBOARD.
Example 7.2. Using SMG$ Routines in VSI BASIC
1       OPTION TYPE=EXPLICIT

        !+
        ! This routine demonstrates the use of SMG$READ_KEYSTROKE to read
        ! a keystroke from the terminal.
        !
        ! Build this program using the following commands.
        !
        !$ BASIC READ_KEY
        !$ CREATE SMGDEF.MAR
        !       .TITLE  SMGDEF - Define SMG$ constants
        !       .Ident  /1-000/
        !
        !       $SMGDEF GLOBAL
        !
        !       .END
        !$ MACRO SMGDEF
        !$ LINK READ_KEY,SMGDEF
        !
        !-

        DECLARE LONG KB_ID, RET_STATUS, TERM_CODE, I, TIMER
        EXTERNAL SUB LIB$SIGNAL( LONG BY VALUE )
        EXTERNAL SUB LIB$STOP( LONG BY VALUE )
        EXTERNAL LONG CONSTANT SS$_TIMEOUT
        EXTERNAL LONG CONSTANT SMG$K_TRM_PF1
        EXTERNAL LONG CONSTANT SMG$K_TRM_PERIOD
        EXTERNAL LONG CONSTANT SMG$K_TRM_UP
        EXTERNAL LONG CONSTANT SMG$K_TRM_RIGHT
        EXTERNAL LONG CONSTANT SMG$K_TRM_F6
        EXTERNAL LONG CONSTANT SMG$K_TRM_F20
        EXTERNAL LONG CONSTANT SMG$K_TRM_FIND
        EXTERNAL LONG CONSTANT SMG$K_TRM_NEXT_SCREEN
        EXTERNAL LONG CONSTANT SMG$K_TRM_TIMEOUT
        EXTERNAL LONG FUNCTION SMG$CREATE_VIRTUAL_KEYBOARD( LONG, STRING )
        EXTERNAL LONG FUNCTION SMG$DELETE_VIRTUAL_KEYBOARD( LONG )
        EXTERNAL LONG FUNCTION SMG$READ_KEYSTROKE( LONG, LONG, STRING, &
            LONG, LONG )

        !+
        ! Prompt the user for the timer value.  A value of 0 will cause
        ! the type-ahead buffer to be read.
        !-

        INPUT "Enter timer value (0 to read type-ahead buffer):  ";TIMER

        !+
        ! Establish a SMG connection to SYS$INPUT.  Signal any unexpected
        ! errors.
        !-

        RET_STATUS = SMG$CREATE_VIRTUAL_KEYBOARD( KB_ID, "SYS$INPUT:" )
        IF (RET_STATUS AND 1%) = 0% THEN
            CALL LIB$SIGNAL( RET_STATUS )
        END IF

        !+
        !   Read a keystroke, tell the user what we found.
        !-

        RET_STATUS = SMG$READ_KEYSTROKE( KB_ID, TERM_CODE, , TIMER, )
        IF (RET_STATUS <> SS$_TIMEOUT) AND ((RET_STATUS AND 1%) = 0%) THEN
            CALL LIB$SIGNAL( RET_STATUS )
        END IF

        PRINT "term_code = ";TERM_CODE

        SELECT TERM_CODE

            CASE 0 TO 31
                PRINT "You typed a control character"

            CASE 32 TO 127
                PRINT "You typed: ";CHR$(TERM_CODE)

            CASE SMG$K_TRM_PF1 TO SMG$K_TRM_PERIOD
                PRINT "You typed one of the keypad keys"

            CASE SMG$K_TRM_UP TO SMG$K_TRM_RIGHT
                PRINT "You typed one of the cursor positioning keys"

            CASE SMG$K_TRM_F6 TO SMG$K_TRM_F20
                PRINT "You typed one of the function keys"

            CASE SMG$K_TRM_FIND TO SMG$K_TRM_NEXT_SCREEN
                PRINT "You typed one of the editing keys"

            CASE SMG$K_TRM_TIMEOUT
                PRINT "You did not type a key fast enough"

            CASE ELSE
                PRINT "I'm not sure what key you typed"

        END SELECT

        !+
        ! Close the connection to SYS$INPUT, and signal any errors.
        !-

        RET_STATUS = SMG$DELETE_VIRTUAL_KEYBOARD( KB_ID )
        IF (RET_STATUS AND 1%) = 0% THEN
            CALL LIB$SIGNAL( RET_STATUS )
        END IF

        END
The BLISS program in Example 7.3 demonstrates the use of SMG$READ_KEYSTROKE from a lower-level language.
Example 7.3. Using SMG$ Routines in VAX BLISS-32
MODULE READ_SINGLE_CHAR (       MAIN = PERFORM_READ,
                                %TITLE 'Read a Keystroke from SYS$INPUT'
                                IDENT = '1-001'  ) =
BEGIN

!+
! Facility:     Example programs
!
! Abstract:     This example program uses the routine SMG$READ_KEYSTROKE
!               to get a single character input from the current SYS$INPUT
!               device and then indicates the nature of the input to the user.
!
! Environment:  User mode, AST reentrant
!
! Author:       John Doe        Creation Date:  8-Apr-1985
!
! Modified by:
! 1-001 - Original.  JD 8-Apr-1985
!-

!+
! General mode addressing must be used for external references.
!-

%SBTTL 'Declarations'
SWITCHES ADDRESSING_MODE (EXTERNAL=GENERAL, NONEXTERNAL=WORD_RELATIVE);

!+
! Obtain SMG$, SS$, etc. definitions.
!-

LIBRARY 'SYS$LIBRARY:STARLET';

!+
! Use the TUTIO package for the purposes of this small example.
!-

REQUIRE 'SYS$LIBRARY:TUTIO';

!+
! Declare screen management routines used by this program, as well as
! any other external routines.
!-

EXTERNAL ROUTINE
    SMG$CREATE_VIRTUAL_KEYBOARD,
    SMG$DELETE_VIRTUAL_KEYBOARD,
    SMG$READ_KEYSTROKE,
    LIB$SIGNAL : NOVALUE;
!+
! Define a convenient way to check the return status from a routine.
!-

MACRO CHECK (X) =
IF NOT X
THEN
    LIB$SIGNAL (X)
%;

%SBTTL 'Routine PERFORM_READ'
ROUTINE PERFORM_READ: NOVALUE =

!+
! Functional Description:
!
!       This routine uses screen management I/O to get a single character
!       input from the current SYS$INPUT device, and then processes it by
!       what its character or termination code is.
!
! Calling Sequence:
!
!       Not Callable
!
! Formal Arguments:
!
!       Not Applicable
!
! Implicit Inputs:
!
!       None
!
! Implicit Outputs:
!
!       None
!
! Side Effects:
!
!       Any error returned by screen management routines except for
!       SS$_TIMEOUT will be signaled.
!-

BEGIN

    LITERAL
        ZERO = 0;

    LOCAL
        KBID : INITIAL(0),
        TERM_CODE : INITIAL(0),
        TIMER_VALUE : INITIAL(0),
        SMG_STATUS;


    !+
    ! Obtain a read timeout value.
    !-

    TIMER_VALUE = 10;

    !+
    ! Establish a screen managed connection to SYS$INPUT.
    !-

    SMG_STATUS = SMG$CREATE_VIRTUAL_KEYBOARD (KBID, %ASCID'SYS$INPUT');
    CHECK (.SMG_STATUS);

    !+
    ! Read a keystroke and tell the user what was found.
    !-

    SMG_STATUS = SMG$READ_KEYSTROKE (KBID, TERM_CODE, ZERO, TIMER_VALUE);
    IF (.SMG_STATUS NEQ SS$_TIMEOUT)
    THEN
       CHECK (.SMG_STATUS);

    SELECTONE .TERM_CODE OF
    SET
        [0 TO 31]:
        TTY_PUT_QUO ('You typed a control character.');

        [32 TO 127]:
        TTY_PUT_QUO ('You typed a printable character.');

        [SMG$K_TRM_PF1 TO SMG$K_TRM_PERIOD]:
        TTY_PUT_QUO ('You typed one of the keypad keys.');

        [SMG$K_TRM_UP TO SMG$K_TRM_RIGHT]:
        TTY_PUT_QUO ('You typed one of the cursor positioning keys.');

        [SMG$K_TRM_F6 TO SMG$K_TRM_F20]:
        TTY_PUT_QUO ('You typed one of the function keys.');

        [SMG$K_TRM_FIND TO SMG$K_TRM_NEXT_SCREEN]:
        TTY_PUT_QUO ('You typed one of the editing keys.');

        [SMG$K_TRM_TIMEOUT]:
        TTY_PUT_QUO ('You did not type a key fast enough.');

        [OTHERWISE]:
        TTY_PUT_QUO ('I am not sure what you typed.');

    TES;
    TTY_PUT_CRLF ();
    !+
    ! Terminate the screen managed connection to SYS$INPUT.
    !-

    SMG_STATUS = SMG$DELETE_VIRTUAL_KEYBOARD (KBID);
    CHECK (.SMG_STATUS);

END;

END
ELUDOM
Example 7.4 shows the techniques used to call SMG$READ_KEYSTROKE from VSI COBOL.
Example 7.4. Using SMG$ Routines in VSI COBOL
IDENTIFICATION DIVISION.
PROGRAM-ID.    KEYSTROKE.
*
*  This routine creates a VIRTUAL DISPLAY and writes it to the PASTEBOARD.
*  Data is placed in the VIRTUAL DISPLAY using the routine SMG$PUT_LINE.
*  SMG$READ_KEYSTROKE is called to read a keystroke from the VIRTUAL KEYBOARD.
*
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01  DISPLAY1            PIC 9(9)  COMP.
01  PASTE1              PIC 9(9)  COMP.
01  KEYBOARD1           PIC 9(9)  COMP.
01  ROWS                PIC S9(9) COMP    VALUE 7.
01  COLUMNS             PIC S9(9) COMP    VALUE 60.
01  DISPLAY_NAME        PIC X(13) VALUE " DISPLAY ONE ".
01  TERM_CHAR           PIC 9(4)  COMP.
01  T_TEXT              PIC X(6).
01  TEXT_OUTPUT         PIC X(24) VALUE " TERMINAL CHARACTER IS: ".
01  PROMPT              PIC X(2)  VALUE ">>".
01  LINE_1    PIC X(12) VALUE "Hit any key.".
01  LINE_2    PIC X(34) VALUE "This character will not be echoed.".
01  LINE_3    PIC X(47) VALUE "The terminal character equivalent is displayed.".
01  LINE_4    PIC X     VALUE " ".
01  THREE               PIC S9(9) COMP   VALUE 3.
01  NINE                PIC S9(9) COMP   VALUE 9.
01  SEVEN               PIC S9(9) COMP   VALUE 7.
01  TWENTY_FIVE         PIC S9(9) COMP   VALUE 25.
PROCEDURE DIVISION.
P0.

* Create the virtual display with a border.

        CALL "SMG$CREATE_VIRTUAL_DISPLAY" USING
                                       ROWS, COLUMNS, DISPLAY1.
* Create the pasteboard

        CALL "SMG$CREATE_PASTEBOARD" USING PASTE1.

* Create a virtual keyboard

        CALL "SMG$CREATE_VIRTUAL_KEYBOARD" USING KEYBOARD1.

* Paste the virtual display at row 3, column 9.

        CALL "SMG$LABEL_BORDER" USING DISPLAY1, BY DESCRIPTOR DISPLAY_NAME.

        CALL "SMG$PASTE_VIRTUAL_DISPLAY" USING
                                         DISPLAY1, PASTE1, THREE, NINE.
* Place data in the virtual display

        CALL "SMG$PUT_LINE" USING DISPLAY1, BY DESCRIPTOR LINE_1.
        CALL "SMG$PUT_LINE" USING DISPLAY1, BY DESCRIPTOR LINE_2.
        CALL "SMG$PUT_LINE" USING DISPLAY1, BY DESCRIPTOR LINE_3.
        CALL "SMG$PUT_LINE" USING DISPLAY1, BY DESCRIPTOR LINE_4.

* Read a keystroke from the virtual pasteboard.

        CALL "SMG$READ_KEYSTROKE" USING KEYBOARD1, TERM_CHAR,
                         BY DESCRIPTOR PROMPT, OMITTED, BY REFERENCE DISPLAY1.

        CALL "SMG$PUT_LINE" USING DISPLAY1, BY DESCRIPTOR LINE_4.

* Convert the decimal value of TERM_CHAR to a decimal ASCII text string.

        CALL "OTS$CVT_L_TI" USING TERM_CHAR, BY DESCRIPTOR T_TEXT.

* Print out the decimal ASCII text string.

        CALL "SMG$PUT_LINE" USING DISPLAY1, BY DESCRIPTOR TEXT_OUTPUT.
        CALL "SMG$PUT_CHARS" USING DISPLAY1, BY DESCRIPTOR T_TEXT,
                                BY REFERENCE SEVEN, TWENTY_FIVE.
            STOP RUN.
The Fortran program shown in Example 7.5 uses SMG$READ_KEYSTROKE as well as SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD, SMG$PASTE_VIRTUAL_DISPLAY, SMG$CREATE_VIRTUAL_KEYBOARD, and SMG$PUT_LINE.
Example 7.5. Using SMG$ Routines in VSI Fortran
C+
C This routine creates a virtual display and writes it to the PASTEBOARD.
C Data is placed in the virtual display using the routine SMG$PUT_CHARS.
C Include the SMG definitions. In particular, we want SMG$M_BORDER.
C-
        INCLUDE '($SMGDEF)'
        INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD
        INTEGER SMG$PASTE_VIRTUAL_DISPLAY,
      1         SMG$CREATE_VIRTUAL_KEYBOARD
        INTEGER SMG$READ_KEYSTROKE, SMG$PUT_LINE
        INTEGER DISPLAY1, PASTE1, KEYBOARD1, ROWS, COLUMNS,
      1         TERM_CHAR
        CHARACTER*3 TEXT
        CHARACTER*27 TEXT_OUTPUT
C+
C Create the virtual display with a border.
C-
        ROWS = 7
        COLUMNS = 60

        ISTATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
C+
C Create the pasteboard.
C-
        ISTATUS = SMG$CREATE_PASTEBOARD (PASTE1)
C+
C Create a virtual keyboard.
C-
        ISTATUS = SMG$CREATE_VIRTUAL_KEYBOARD ( KEYBOARD1)
C+
C Paste the virtual display at row 3, column 9.
C-
        ISTATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 3, 9)

        ISTATUS = SMG$PUT_LINE (DISPLAY1,
     1          'Enter the character K after the >> prompt.')
        ISTATUS = SMG$PUT_LINE (DISPLAY1,
     1          'This character will not be echoed as you type it.')
        ISTATUS = SMG$PUT_LINE (DISPLAY1,
     1  'The terminal character equivalent of K is displayed.')
        ISTATUS = SMG$PUT_LINE (DISPLAY1, ' ')
C+
C Read a keystroke from the virtual pasteboard.
C-
        ISTATUS = SMG$READ_KEYSTROKE ( KEYBOARD1, TERM_CHAR, '>>', ,
     1          DISPLAY1)

        ISTATUS = SMG$PUT_LINE (DISPLAY1, ' ')
C+
C Convert the decimal value of TERM_CHAR to a decimal ASCII text string.
C-
        ISTATUS = OTS$CVT_L_TI( TERM_CHAR, TEXT)

        TEXT_OUTPUT = ' TERMINAL CHARACTER IS: ' // TEXT
C+
C Print the decimal ASCII text string.
C-
        ISTATUS = SMG$PUT_LINE (DISPLAY1, TEXT_OUTPUT)
        ISTATUS = SMG$PUT_CHARS (DISPLAY1, TEXT, 7, 25)

        END
The VAX MACRO program shown in Example 7.6 demonstrates the precise steps required to call SMG$READ_KEYSTROKE from a low-level language.
Example 7.6. Using SMG$ Routines in VAX MACRO
        .TITLE  SMG_DEMO

;+
; This program demonstrates the use of the SMG$ routines, in particular
; SMG$READ_KEYSTROKE.
;-

        $DSCDEF         ; Declare DSC$ symbols
        $SMGDEF         ; Declare SMG$ symbols
;+
; Declare external routines.
;-
        .EXTRN  SMG$CREATE_PASTEBOARD
        .EXTRN  SMG$CREATE_VIRTUAL_DISPLAY
        .EXTRN  SMG$CREATE_VIRTUAL_KEYBOARD
        .EXTRN  SMG$PUT_LINE
        .EXTRN  SMG$READ_KEYSTROKE
;+
; Declare data PSECT and objects.
;-
        .PSECT  $DATA RD,WRT,NOEXE,NOSHR,PIC

LINE1:  .ASCID  "Enter the character K after the prompt."
LINE2:  .ASCID  "This character will not be echoed as you type it."
LINE3:  .ASCID  "The terminal character equivalent of K is displayed."
PROMPT: .ASCID  ">>"
BLANK:  .ASCID  " "
FAOSTR: .ASCID  "TERMINAL CHARACTER IS !UL"

TEXT:   .BLKB   80      ; Buffer for formatted text
TEXT_LEN = . - TEXT     ; Length of TEXT
TEXT_DSC:               ; Descriptor for TEXT string
        .WORD   TEXT_LEN        ; DSC$W_LENGTH
        .BYTE   DSC$K_DTYPE_T   ; DSC$B_DTYPE
        .BYTE   DSC$K_CLASS_S   ; DSC$B_CLASS
        .ADDRESS TEXT           ; DSC$A_POINTER

TERM_CHAR:
        .BLKL           ; Space for terminator character code
PASTEBOARD_1:
        .BLKL           ; Pasteboard ID
DISPLAY_1:
        .BLKL           ; Display ID
KEYBOARD_1:
        .BLKL           ; Keyboard ID

;+
; Declare PSECT for code.
;-

        .PSECT  $CODE RD,NOWRT,EXE,SHR,PIC
;+
; Begin main routine.
;-
        .ENTRY  SMG_DEMO, ^M<>  ; Save no registers
;+
; Create virtual display.
;-
        PUSHL   #SMG$M_BORDER   ; Put flag on stack
        PUSHL   #60             ; Put columns on stack
        PUSHL   #7              ; Put rows on stack
        PUSHAB  8(SP)           ; Address of flag
        PUSHABL ^DISPLAY_1      ; Address of display ID
        PUSHAB  12(SP)          ; Address of columns
        PUSHAB  12(SP)          ; Address of rows
        CALLS   #4,  G^SMG$CREATE_VIRTUAL_DISPLAY
        ADDL2   #12, SP         ; Pop off temporaries

; Create pasteboard.
        PUSHAB  L^PASTEBOARD_1  ; Address of pasteboard
        CALLS   #1, G^SMG$CREATE_PASTEBOARD

; Create virtual keyboard.
        PUSHAB  L^KEYBOARD_1    ; Address of keyboard
        CALLS   #1, G^SMG$CREATE_VIRTUAL_KEYBOARD

; Paste the virtual display at row 3, column 9.
        PUSHL   #9              ; Put column on stack
        PUSHL   #3              ; Put row on stack
        PUSHAB  4(SP)           ; Address of column
        PUSHAB  4(SP)           ; Address of row
        PUSHABL ^PASTEBOARD_1   ; Address of pasteboard
        PUSHABL ^DISPLAY_1      ; Address of display
        CALLS   #4, G^SMG$PASTE_VIRTUAL_DISPLAY
        ADDL2   #8, SP          ; Pop off temporaries

; Write instructions.
        PUSHAB  L^LINE1         ; "Enter the character..."
        PUSHABL ^DISPLAY_1      ; Display ID
        CALLS   #2, G^SMG$PUT_LINE
        PUSHABL ^LINE2          ; "This character will not..."
        PUSHABL ^DISPLAY_1      ; Display ID
        CALLS   #2, G^SMG$PUT_LINE
        PUSHABL ^LINE3          ; "The terminal character..."
        PUSHABL ^DISPLAY_1      ; Display ID
        CALLS   #2, G^SMG$PUT_LINE
        PUSHABL ^BLANK          ; Blank line
        PUSHABL ^DISPLAY_1      ; Display ID
        CALLS   #2, G^SMG$PUT_LINE

; Read a keystroke from the virtual keyboard.
        PUSHAB  L^DISPLAY_1     ; Display ID
        CLRL    -(SP)           ; No timeout
        PUSHAB  L^PROMPT        ; Prompt string
        PUSHAB  L^TERM_CHAR     ; Longword for terminator code
        PUSHAB  L^KEYBOARD_1    ; Keyboard ID
        CALLS   #5, G^SMG$READ_KEYSTROKE

; Format the terminator code using $FAO.
        $FAO_S  CTRSTR=L^FAOSTR,-                       ; FAO control string
                OUTLEN=L^TEXT_DSC+DSC$W_LENGTH,-        ; Output string length
                OUTBUF=L^TEXT_DSC,-                     ; Output buffer
                P1=L^TERM_CHAR                          ; Value to format

; Display the formatted text.
        PUSHABL ^BLANK          ; Blank line
        PUSHAB  L^DISPLAY_1     ; Display ID
        CALLS   #2, G^SMG$PUT_LINE
        PUSHAB  L^TEXT_DSC      ; Text to display
        PUSHAB  L^DISPLAY_1     ; Display ID
        CALLS   #2, G^SMG$PUT_LINE

; Return with status from last call.
        RET

        .END    SMG_DEMO        ; Specify SMG_DEMO as main program
Example 7.7 uses SMG$READ_KEYSTROKE from VSI Pascal. It also demonstrates the use of SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD, SMG$CREATE_VIRTUAL_KEYBOARD, SMG$PASTE_VIRTUAL_DISPLAY, and SMG$PUT_LINE.
Example 7.7. Using SMG$ Routines in VSI Pascal
{ This program demonstrates the use of the SMG$ routines, in particular }
{ SMG$READ_KEYSTROKE. }

[INHERIT('SYS$LIBRARY:STARLET')]
PROGRAM SMG_DEMO;

TYPE
    UNSIGNED_WORD = [WORD] 0..65535;

FUNCTION SMG$CREATE_VIRTUAL_DISPLAY (
    ROWS, COLUMNS: INTEGER;
    VAR DISPLAY_ID: INTEGER;
    DISPLAY_ATTRIBUTES, VIDEO_ATTRIBUTES, CHAR_SET: UNSIGNED
        := %IMMED 0): UNSIGNED; EXTERN;

FUNCTION SMG$CREATE_PASTEBOARD (
    VAR PASTEBOARD_ID: INTEGER;
    OUTPUT_DEVICE: PACKED ARRAY [A..B:INTEGER] OF CHAR:= %IMMED 0;
    ROWS, COLUMNS: INTEGER := %IMMED 0;
    PRESERVE_SCREEN_FLAG: BOOLEAN := %IMMED 0): UNSIGNED; EXTERN;

FUNCTION SMG$CREATE_VIRTUAL_KEYBOARD (
    VAR KEYBOARD_ID: INTEGER;
    FILESPEC: PACKED ARRAY [A..B:INTEGER] OF CHAR := %IMMED 0;
    DEFAULT_FILESPEC: PACKED ARRAY [C..D:INTEGER] OF CHAR := %IMMED 0;
    RESULTANT_FILESPEC: PACKED ARRAY [E..F:INTEGER] OF CHAR := %IMMED 0
    ): UNSIGNED; EXTERN;

FUNCTION SMG$PASTE_VIRTUAL_DISPLAY (
    DISPLAY_ID, PASTEBOARD_ID: INTEGER;
    ROW, COLUMN: INTEGER): UNSIGNED; EXTERN;

FUNCTION SMG$READ_KEYSTROKE (
    KEYBOARD_ID: INTEGER;
    VAR TERMINATOR_CODE: UNSIGNED_WORD;
    PROMPT: PACKED ARRAY [A..B:INTEGER] OF CHAR := %IMMED 0;
    TIMEOUT, DISPLAY_ID: INTEGER := %IMMED 0): UNSIGNED; EXTERN;

FUNCTION SMG$PUT_LINE (
    DISPLAY_ID: INTEGER;
    TEXT: PACKED ARRAY [A..B:INTEGER] OF CHAR;
    LINE_ADVANCE: INTEGER := %IMMED 0;
    RENDITION_SET, RENDITION_COMPLEMENT: UNSIGNED := %IMMED 0;
    WRAP_FLAG: BOOLEAN := %IMMED 0;
    CHAR_SET: UNSIGNED := %IMMED 0): UNSIGNED; EXTERN;

var
    PASTEBOARD_1, DISPLAY_1, KEYBOARD_1: INTEGER;
    TERMINATOR: UNSIGNED_WORD;

BEGIN
    { Create virtual display, pasteboard and virtual keyboard }

    SMG$CREATE_VIRTUAL_DISPLAY (ROWS := 7, COLUMNS := 60,
        DISPLAY_ID := DISPLAY_1,
        DISPLAY_ATTRIBUTES := SMG$M_BORDER);
    SMG$CREATE_PASTEBOARD (PASTEBOARD_ID := PASTEBOARD_1);
    SMG$CREATE_VIRTUAL_KEYBOARD (KEYBOARD_ID := KEYBOARD_1);

    { Paste the virtual display at row 3, column 9 }

    SMG$PASTE_VIRTUAL_DISPLAY (DISPLAY_ID := DISPLAY_1,
        PASTEBOARD_ID := PASTEBOARD_1, ROW := 3, COLUMN := 9);

    { Write the instructions to the virtual display }

    SMG$PUT_LINE (DISPLAY_ID := DISPLAY_1,
        TEXT := 'Enter the character K after the >> prompt.');
    SMG$PUT_LINE (DISPLAY_ID := DISPLAY_1,
        TEXT := 'This character will not be echoed as you type it.');
    SMG$PUT_LINE (DISPLAY_ID := DISPLAY_1,
        TEXT := 'The terminal character equivalent of K is displayed.');
    SMG$PUT_LINE (DISPLAY_ID := DISPLAY_1,
        TEXT := ' ');

    { Read the keystroke from the virtual keyboard }

    SMG$READ_KEYSTROKE (KEYBOARD_ID := KEYBOARD_1,
        DISPLAY_ID := DISPLAY_1,
        TERMINATOR_CODE := TERMINATOR, PROMPT := '>>');

    { Display the decimal value of the terminator code }

    SMG$PUT_LINE (DISPLAY_ID := DISPLAY_1,
        TEXT := ' ');
    SMG$PUT_LINE (DISPLAY_ID := DISPLAY_1,
        TEXT := 'TERMINAL CHARACTER IS ' + DEC(TERMINATOR,5,1));
END.
The program shown in Example 7.8 calls SMG$READ_KEYSTROKE from VAX PL/I.
Example 7.8. Using SMG$ Routines in VAX PL/I
/*
 *  Example of SMG$READ_KEYSTROKE.
 */

/*
 *  Declare the RTL entry points.
 */
declare
    SMG$CREATE_VIRTUAL_KEYBOARD external entry(
        fixed binary(31),       /* new-keyboard-id */
        character(*),           /* filespec */
        character(*),           /* default-filespec */
        character(*) varying )  /* resultant-filespec */
        returns(fixed binary(31)) options(variable);

declare
    SMG$DELETE_VIRTUAL_KEYBOARD external entry(
        fixed binary(31) )       /* keyboard-id */
        returns(fixed binary(31));

declare
    SMG$READ_KEYSTROKE external entry(
        fixed binary(31),       /* keyboard-id */
        fixed binary(15),       /* terminator-code */
        character(*),           /* prompt-string */
        fixed binary(31),       /* timeout */
        fixed binary(31) )      /* display-id */
        returns(fixed binary(31)) options(variable);

/*
 *  Get the value of the SMG constants from PLISTARLET.
 */
%include $SMGDEF;
declare SMG$_EOF globalref value fixed binary(31);

/*
 *  Misc. constants.
 */
%replace false by '0'b;
%replace true  by '1'b;

/*
 *  The following compile-time routine will signal an error at run-time
 *  if the status value that it is passed does not have success or
 *  informational severity (that is, if the low bit is not set).
 */
%signal_if: procedure (status_val) returns(character);
    %declare status_val character;
    %return( 'if posint(' || status_val || ',1,1) = 0 ' ||
                'then signal vaxcondition(' || status_val || ')' );
    %end;

main: proc options(main, ident('V4.2'));

    declare exit bit initial(false);
    declare status fixed binary(31);
    declare keyboard_id fixed binary(31);
    declare terminator fixed binary(15);

    /*
     *  Create the virtual keyboard necessary for the read.
     */
    status = smg$create_virtual_keyboard( keyboard_id );
    signal_if( status );
    /*
     *  Read a single keystroke.  If that keystroke is an end-of-file,
     *  then exit.  Otherwise, SELECT the appropriate action based on
     *  the key.
     */
    do while(^exit);

        status = smg$read_keystroke( keyboard_id, terminator,
            'Command: ', 20 );

        if status = SMG$_EOF
            then exit = true;

            else do;
                signal_if( status );

                select (terminator);

                    when (SMG$K_TRM_PF2,
                          SMG$K_TRM_HELP,
                          rank('H'),
                          rank('h'),
                          rank('?') )   call display_help;

                    when(SMG$K_TRM_DO)  call do_command;
                    when(rank('E'),
                         rank('e'))     exit = true;

                    otherwise           call command_error;

                       end;
                end;
        end;

    /*
     *  We're done, so delete the virtual keyboard.
     */
    status = smg$delete_virtual_keyboard( keyboard_id );
    signal_if( status );

    end main;

display_help: procedure;

    put skip edit('This program uses single keystroke commands.') (A);
    put skip edit('The following keys are valid:') (A);
    put skip;
    put skip edit('     Key             Function') (A);
    put skip edit('     E/e             Exit') (A);
    put skip edit('     <DO>  Your choice...') (A);
    put skip edit('     ?/H/h/<HELP> Help') (A);
    put skip;

    end display_help;

do_command: procedure;

    put skip edit('The DO key was pressed') (A);
    put skip;

    end do_command;

command_error: procedure;

    put skip edit('The key pressed was not valid - please try again.') (A);
    put skip edit('(H for HELP).' ) (A);
    put skip;

    end command_error;

Chapter 8. Screen Management (SMG$) Routines

This chapter contains detailed descriptions of all routines provided by the RTL Screen Management (SMG$) Facility.

SMG$ADD_KEY_DEF

SMG$ADD_KEY_DEF — The Add Key Definition routine adds a keypad key definition to a table of key definitions.

Format

SMG$ADD_KEY_DEF
   key-table-id ,key-name [,if-state] [,attributes] [,equivalence-string]
   [,state-string]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

key-table-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifies the key table to which you are adding a key definition. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.

The key table identifier argument is returned by the SMG$CREATE_KEY_TABLE routine.

key-name
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

Identifies the key whose value you are defining. The key-name argument is the address of a descriptor pointing to this key name. The SMG$ADD_KEY_DEF routine changes the string to uppercase and removes trailing blanks.

Table 3.1 lists the valid key names.

if-state
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

Qualifies the value returned when key-name is pressed. The if-state argument is the address of a descriptor pointing to the state string.

If if-state is specified, this definition of key-name is used only if the current state matches the specified if-state string. The if-state argument must be from 1 to 31 characters in length. If this argument is omitted, if-state defaults to the value DEFAULT.

attributes
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Longword bit mask specifying additional attributes of this key definition. The attributes argument is the address of an unsigned longword that contains this attribute mask. If omitted, the mask is zero.

Valid attributes are described in the following list:

SMG$M_KEY_NOECHOIf set, this bit specifies that equivalence-string is not to be echoed when this key is pressed. If clear, equivalence-string is echoed. If SMG$M_KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is ignored.
SMG$M_KEY_TERMINATEIf set, this bit specifies that when this key is pressed (as qualified by if-state) the input line is complete and more characters should not be accepted. If clear, more characters may be accepted. In other words, setting this bit causes equivalence-string to be treated as a terminator.
SMG$M_KEY_LOCKIf set, and if state-string is specified, the state name specified bystate-string remains the current state until explicitly changed by a subsequent keystroke whose definition includes a state-string. If clear, the state name specified by state-string remains in effect only for the next defined keystroke.
SMG$M_KEY_PROTECTEDIf set, this bit specifies that this key definition cannot be modified or deleted. If clear, the key definition can be modified or deleted.

The remaining bits are undefined and must be zero. It is possible to perform a logical OR operation on these values to set more than one attribute at a time.

equivalence-string
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

Character string to be substituted for the keystroke in the returned line. The equivalence-string argument is the address of a descriptor pointing to this equivalence string.

The equivalence-string argument is displayed unless SMG$M_KEY_NOECHO is set. If equivalence-string is omitted, no equivalence string is defined for this key.

state-string
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

Contains a new state name that becomes the current state when this key is pressed. The state-string argument is the address of a descriptor pointing to the new state string.

If omitted, no new state is defined. If the current state is temporary (that is, if SMG$M_KEY_LOCKSTATE was not specified for the most recently pressed defined key), the current state-string becomes DEFAULT.

Description

SMG$ADD_KEY_DEF inserts a key definition into a key definition table. The table must have been created with a call to SMG$CREATE_KEY_TABLE. After SMG$ADD_KEY_DEF executes, the specified equivalence string is returned when the user types the specified key in response to the SMG$READ_COMPOSED_LINE routine.

You can define all keys on the VT100, VT200-series, VT300-series, VT400-series, and VT500-series keyboards and keypads.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_PREDEFREPSuccessful completion. The previous key definition has been replaced.
SMG$_INVDEFATTInvalid key definition attributes.
SMG$_INVKEYNAMInvalid key-name.
SMG$_INVKTB_IDInvalid key-table-id.
SMG$_KEYDEFPROKey definition is protected against change or deletion.
SMG$_WRONUMARGWrong number of arguments.

SMG$BEGIN_DISPLAY_UPDATE

SMG$BEGIN_DISPLAY_UPDATE — The Begin Batching of Display Updates routine saves, or batches, all output to a virtual display until a matching call to SMG$END_DISPLAY_UPDATE is encountered.

Format

SMG$BEGIN_DISPLAY_UPDATE display-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display for which output is to be batched. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

Description

SMG$BEGIN_DISPLAY_UPDATE lets you make more than one change to a display and have the changes appear only after all changes are complete. Thus, the user sees the display change from its initial state to its final state, without seeing any of the intermediate states.

Batching terminates when SMG$END_DISPLAY_UPDATE has been called the same number of times for a given display as has SMG$BEGIN_DISPLAY_UPDATE. The Screen Management Facility keeps track of batching for a given display; thus, the calls to the SMG$BEGIN_DISPLAY_UPDATE and SMG$END_DISPLAY_UPDATE need not occur in the same module.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_BATWAS_ONSuccessful completion; batching has already been initiated.
SMG$_INVDIS_IDInvalid display-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$BEGIN_PASTEBOARD_UPDATE

SMG$BEGIN_PASTEBOARD_UPDATE — The Begin Batching of Pasteboard Updates routine saves, or batches, all output to a pasteboard until a matching call to SMG$END_PASTEBOARD_UPDATE is encountered.

Format

SMG$BEGIN_PASTEBOARD_UPDATE pasteboard-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard for which output is to be batched. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

Description

SMG$BEGIN_PASTEBOARD_UPDATE lets you make more than one change to a pasteboard and have the changes appear only after all changes are complete. Thus, the user sees the pasteboard change from its initial state to its final state, without seeing any of the intermediate states.

Batching terminates when SMG$END_PASTEBOARD_UPDATE has been called the same number of times for a given pasteboard as has SMG$BEGIN_PASTEBOARD_UPDATE. The Screen Management Facility keeps track of batching for a given pasteboard; thus, the calls to the SMG$BEGIN_PASTEBOARD_UPDATE and SMG$END_PASTEBOARD_UPDATE need not occur in the same module.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_BATWAS_ONSuccessful completion; batching has already been initiated.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$CANCEL_INPUT

SMG$CANCEL_INPUT — The Cancel Input Request routine immediately cancels any read-in-progress that was issued by SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, or SMG$READ_VERIFY.

Format

SMG$CANCEL_INPUT keyboard-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

keyboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual keyboard for which the input is to be canceled. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier.

The keyboard identifier is returned by SMG$CREATE_VIRTUAL_KEYBOARD.

Description

SMG$CANCEL_INPUT causes immediate termination of an SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, or SMG$READ_VERIFY input operation from a terminal. The condition code SS$_CANCEL or SS$_ABORT is returned to those routines when you use SMG$CANCEL_INPUT. Note that if the specified virtual keyboard is associated with an OpenVMS RMS file, this procedure has no effect because it is not possible to cancel an outstanding RMS input operation.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVKBD_IDInvalid keyboard-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$CHANGE_PBD_CHARACTERISTICS

SMG$CHANGE_PBD_CHARACTERISTICS — The Change Pasteboard Characteristics routine lets you change the characteristics associated with a pasteboard.

Format

SMG$CHANGE_PBD_CHARACTERISTICS
   pasteboard-id [,desired-width] [,width] [,desired-height][,height]
   [,desired-background-color] [,background-color]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard whose characteristics are to be changed. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

desired-width
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

New width for the pasteboard. The desired-width argument is the address of a signed longword that contains the desired width. If omitted, the width does not change.

width
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Receives the physical width of the pasteboard. The width argument is the address of a signed longword into which is written the actual width of the pasteboard.

If the terminal cannot be set exactly to desired-width, width may be larger than desired-width. If the physical width of the terminal is smaller than desired-width, width may be smaller than desired-width.

desired-height
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

New height for the pasteboard. The desired-height argument is the address of a signed longword that contains the desired height of the pasteboard. If desired-height is omitted, the height does not change.

height
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Receives the physical height of the pasteboard. The height argument is the address of a signed longword into which is written the actual height of the pasteboard.

If the terminal cannot be set exactly to desired-height, height may be larger than desired-height. If the physical height of the terminal is smaller than desired-height, height may be smaller than desired-height.

desired-background-color
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Symbolic name for the desired background color. The desired-background-color argument is the address of an unsigned longword that contains the desired color.

The symbols listed below are defined in $SMGDEF. Valid values for desired-background-color are as follows:
SMG$C_COLOR_WHITELight background
SMG$C_COLOR_BLACKDark background
SMG$C_COLOR_BLUEBlue background
SMG$C_COLOR_CYANCyan (green-blue) background
SMG$C_COLOR_GREENGreen background
SMG$C_COLOR_MAGENTAMagenta background
SMG$C_COLOR_REDRed background
SMG$C_COLOR_YELLOWYellow background
SMG$C_COLOR_LIGHTWhite background
SMG$C_COLOR_DARKBlack background
SMG$C_COLOR_USER1User-defined background 1
SMG$C_COLOR_USER2User-defined background 2
SMG$C_COLOR_USER3User-defined background 3
SMG$C_COLOR_USER4User-defined background 4
SMG$C_COLOR_USER5User-defined background 5
SMG$C_COLOR_USER6User-defined background 6
SMG$C_COLOR_USER7User-defined background 7
SMG$C_COLOR_USER8User-defined background 8

If you omit desired-background-color, or if the terminal hardware does not support the background color specified, the background color is not changed.

background-color
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the background color chosen. The background-color argument is the address of an unsigned longword into which is written the background color.

This routine may return any of the values listed in the desired-background-color argument description or SMG$C_COLOR_UNKNOWN. If the desired-background-color argument is omitted, the value of background-color does not change.

Description

SMG$CHANGE_PBD_CHARACTERISTICS lets you change the width, height, and background color associated with a pasteboard.

If necessary, this routine will notify the OpenVMS operating system of the change in pasteboard characteristics by updating the terminal characteristics displayed when you enter the DCL command SHOW TERMINAL.

Do not use SMG$CHANGE_PBD_CHARACTERISTICS on a batched pasteboard.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVCOLARGUnknown background color specified.
SMG$_INVPAGARGInvalid height of 0 desired.
SMG$_INVWIDARGInvalid width of 0 desired.
SMG$_PBDIN_USECannot change characteristics while batching is on.
SMG$_WRONUMARGWrong number of arguments.
SS$_xxxAny error from $QIOW.

SMG$CHANGE_RENDITION

SMG$CHANGE_RENDITION — The Change Default Rendition routine changes the video attributes for all or part of a virtual display.

Format

SMG$CHANGE_RENDITION
   display-id ,start-row ,start-column ,number-of-rows ,number-of-columns
   [,rendition-set] [,rendition-complement]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display whose default rendition is to be changed. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Starting row position to receive the new rendition. The start-row argument is the address of a signed longword that contains the starting row number.

start-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Starting column position to receive the new rendition. The start-column argument is the address of a signed longword that contains the starting column number.

number-of-rows
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Number of rows to receive the new rendition. The number-of-rows argument is the address of a signed longword that contains the number of rows to be affected.

number-of-columns
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Number of columns to receive the new rendition. The number-of-columns argument is the address of a signed longword that contains the number of columns to be affected.

rendition-set
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, whilerendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:

SetComplementAction
00Attribute set to default
10Attribute on
01Attribute set to complement of default setting
11Attribute off

Description

This procedure changes the default video rendition of a rectangular block of text already in the specified virtual display. For example, you might use this procedure to redisplay a particular row in reverse video.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGInvalid number of rows, invalid number of columns, unrecognizedrendition-set code, or unrecognized rendition-complement code.
SMG$_INVCOLInvalid start-column. The specified column is outside the virtual display.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid start-row. The specified row is outside the virtual display.
SMG$_NO_CHADISNo change in virtual display.
SMG$_WRONUMARGWrong number of arguments.

SMG$CHANGE_VIEWPORT

SMG$CHANGE_VIEWPORT — The Change the Viewport Associated with a Virtual Display routine changes the size of an existing viewport in a virtual display. The text currently in the viewport is remapped to fit the new dimensions.

Format

SMG$CHANGE_VIEWPORT
   display-id [,viewport-row-start] [,viewport-column-start]
   [,viewport-number-rows] [,viewport-number-columns]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the virtual display containing the viewport to be changed. The display-id argument is the address of an unsigned longword containing this identifier.

viewport-row-start
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Optional row number in the virtual display that will become row 1 in the changed viewport. The viewport-row-start argument is the address of a signed longword containing the row number. If omitted, the present viewport-row-start value is used.

viewport-column-start
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Optional column number in the virtual display that will become column 1 in the changed viewport. The viewport-column-start argument is the address of a signed longword containing the column number. If omitted, the present viewport-column-start value is used.

viewport-number-rows
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Optional number of rows in the changed viewport. The viewport-number-rows argument is the address of a signed longword containing the number of rows. If omitted, the present viewport-number-rows value is used.

viewport-number-columns
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Optional number of columns in the changed viewport. The viewport-number-columns argument is the address of a signed longword containing the number of columns. If omitted, the present viewport-number-columns value is used.

Description

SMG$CHANGE_VIEWPORT lets you change the size of an existing viewport in a virtual display. The text currently in this viewport is remapped to fit the new dimensions, starting at the position specified by the viewport-row-start and viewport-column-start arguments. This position also specifies the resulting virtual cursor location.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGNumber of rows or columns is less than zero.
SMG$_INVCOLInvalid column specified.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row specified.
SMG$_NO_WINASSOCNo viewport associated with the virtual display.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of
C SMG$CHANGE_VIEWPORT.
C-


 IMPLICIT INTEGER (A-Z)
 INCLUDE '($SMGDEF)'

C Create the virtual display. Give it a border.

 ROWS = 9
 COLUMNS = 50

 STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1         (ROWS, COLUMNS, DISPLAY1,SMG$M_BORDER )
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%val(STATUS))

C Create the pasteboard.

 STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%val(STATUS))

C Put data in the virtual display.

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
 1 'This is row 1 in a virtual display with 9 rows.',1,1)
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
 1 'This is row 2 in a virtual display with 9 rows.',2,1)
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
 1 'This is row 3 in a virtual display with 9 rows.',3,1)
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
 1 'This is row 4 in a virtual display with 9 rows.',4,1)
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
 1 'This is row 5 in a virtual display with 9 rows.',5,1)
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
 1 'This is row 6 in a virtual display with 9 rows.',6,1)
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
 1 'This is row 7 in a virtual display with 9 rows.',7,1)
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
 1 'This is row 8 in a virtual display with 9 rows.',8,1)
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
 1 'This is row 9 in a virtual display with 9 rows.',9,1)
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

C Paste the virtual display.

 STATUS = SMG$COPY_VIRTUAL_DISPLAY(DISPLAY1,DISPLAY2)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$LABEL_BORDER (DISPLAY1, 'Full Display',,,SMG$M_BOLD)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$LABEL_BORDER (DISPLAY2, 'Viewport',,,SMG$M_BOLD)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 2, 10)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 13, 10)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
 CALL LIB$WAIT (4.0)

 STATUS = SMG$CREATE_VIEWPORT ( DISPLAY2, 2, 1, 5, 21)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
 CALL LIB$WAIT (4.0)

 STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 13, 10)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
 CALL LIB$WAIT (4.0)

 STATUS = SMG$CHANGE_VIEWPORT ( DISPLAY2, 4, 8, 3, 15)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
 call lib$wait (4.0)

 END
The output generated by this Fortran example is shown in the following figures. In Figure 8.1, the program has copied the initial virtual display into a second virtual display, labeled "Viewport."
Figure 8.1. Output Generated After Virtual Displays Are Pasted
Output Generated After Virtual Displays Are Pasted
After the two identical virtual displays are pasted, the program creates a viewport on the second (copy) virtual display. Once the second display is "repasted," only the portion located in the viewport is visible. This is shown in Figure 8.2.
Figure 8.2. Output Generated After the Viewport Is Created
Output Generated After the Viewport Is Created
By calling SMG$CHANGE_VIEWPORT, the portion of the virtual display that is visible through the viewport is changed. This is shown in Figure 8.3.
Figure 8.3. Output Generated After Calling SMG$CHANGE_VIEWPORT
Output Generated After Calling SMG$CHANGE_VIEWPORT

SMG$CHANGE_VIRTUAL_DISPLAY

SMG$CHANGE_VIRTUAL_DISPLAY — The Change Virtual Display routine lets you change the dimensions, border, and video attributes of a virtual display.

Format

SMG$CHANGE_VIRTUAL_DISPLAY
   display-id [,number-of-rows] [,number-of-columns] [,display-attributes]
   [,video-attributes] [,character-set]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display whose attributes are to be changed. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

number-of-rows
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the new number of rows for the virtual display. The number-of-rows argument is the address of a signed longword that contains the number of rows in the virtual display.

number-of-columns
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the new number of columns for the virtual display. The number-of-columns argument is the address of a signed longword that contains the number of columns in the virtual display.

display-attributes
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the attributes of the virtual display. The display-attributes argument is the address of a longword bit mask that contains the display attributes.

Valid values for display-attributes are as follows:

SMG$M_BORDERSpecifies a bordered display. If omitted, the display is not bordered.
SMG$M_BLOCK_BORDERSpecifies a block bordered display. If omitted, the display is not bordered.
SMG$M_DISPLAY_CONTROLSSpecifies that control characters such as carriage return and line feed are displayed as graphic characters, if your terminal supports them.
SMG$M_TRUNC_ICONSpecifies that an icon (generally a diamond shape) is displayed where truncation of a line exceeding the width of the virtual display has occurred.
video-attributes
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the default rendition to be applied to all output in a virtual display, unless overridden by a call to a specific output routine. The video-attributes argument is the address of an unsigned longword that contains the video attributes mask.

For example, a call to SMG$PUT_CHARS with an explicit rendition specified would override the default rendition.

The bits that can be set for this argument are as follows:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video; that is, to the opposite of the current default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.

You can specify any combination of attributes in a single call. All other bits are reserved to OpenVMS and must be 0.

character-set
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set specifier. Valid values are SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.

Description

SMG$CHANGE_VIRTUAL_DISPLAY lets you change the size or default attributes of an existing virtual display. If the size of the virtual display is changed, the Screen Management Facility attempts to remap the text associated with the display to fit the new dimensions (starting at row 1 and column 1). If the new size of the virtual display is smaller than the old size, text may be truncated. If the new size of the virtual display is larger than the old size, text may be padded on the right with spaces.

When a display is redimensioned, the virtual cursor for the display is moved to row 1 and column 1. If a labeled border applies to the virtual display and does not fit the redimensioned display, the label is deleted.

If a program calls both SMG$CREATE_PASTEBOARD and SMG$CREATE_VIRTUAL_KEYBOARD, make sure SMG$CREATE_PASTEBOARD is called first. The program will not function correctly if SMG$CREATE_VIRTUAL_KEYBOARD is called before SMG$CREATE_PASTEBOARD.

Condition Values Returned

SS$_NORMALNormal successful completion.
LIB$_INSVIRMEMInsufficient virtual memory to reallocate needed buffers.
SMG$_INVARGInvalid video or display attributes.
SMG$_INVDIS_IDInvalid display-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$CHECK_FOR_OCCLUSION

SMG$CHECK_FOR_OCCLUSION — The Check for Occlusion routine checks to see whether a virtual display is covered (occluded) by another virtual display.

Format

SMG$CHECK_FOR_OCCLUSION display-id ,pasteboard-id ,occlusion-state

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display to be checked. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard to be checked. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

occlusion-state
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Receives the value denoting whether the display is occluded. The occlusion-state argument is the address of a signed longword into which the occlusion state is written. Occlusion-state is set to 1 if the display is occluded or set to 0 if the display is not occluded on the specified pasteboard. If the procedure does not return SS$_NORMAL, the contents of occlusion-state are undefined.

Description

SMG$CHECK_FOR_OCCLUSION determines whether a specified virtual display as pasted to the specified pasteboard is occluded, or covered, by another virtual display.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_NOTPASTEDSpecified virtual display is not pasted to the specified pasteboard.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of
C SMG$CHECK_FOR_OCCLUSION.
C
C This routine creates a virtual display and writes it to the
C pasteboard.  Data is placed in the virtual display using SMG$PUT_CHARS.
C-

        INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD
        INTEGER SMG$PASTE_VIRTUAL_DISPLAY,  SMG$PUT_CHARS
        INTEGER SMG$CHECK_FOR_OCCLUSION
        INTEGER DISPLAY1, DISPLAY2, PASTE1, PASTE2, ROWS, COLUMNS, BORDER
        INTEGER OCCLUSION, STATUS
        CHARACTER*29 TEXT

C+
C Include the SMG definitions. In particular, we want SMG$M_BORDER.
C-

        INCLUDE '($SMGDEF)'

C+
C Create two virtual displays using SMG$CREATE_VIRTUAL_DISPLAY.
C Give them borders.
C-

        ROWS = 6
        COLUMNS = 50

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        ROWS = 5
        COLUMNS = 30

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY2, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Create the pasteboard using SMG$CREATE_PASTEBOARD.
C-

        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$PUT_CHARS to put data into the virtual displays.
C-

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' This virtual display has 6 rows and 50 columns.', 2, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' This is a bordered virtual display.', 3, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' SMG$PUT_CHARS puts data in this virtual display.', 4,
     1          1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' This text should be partially occluded.', 5, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' So should part of this row.', 6, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY2, ' This is virtual', 3, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY2,
     1         ' display #2.', 4, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY2,
     1         ' This is just some more text.', 5, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 8, 15)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Check the two virtual displays for occlusion by calling
C SMG$CHECK_FOR_OCCLUSION.
C-

        TEXT = 'This display is not occluded.'

        STATUS = SMG$CHECK_FOR_OCCLUSION (DISPLAY1, PASTE1, OCCLUSION)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        IF (OCCLUSION .EQ. 0) THEN
                STATUS = SMG$PUT_CHARS (DISPLAY1, TEXT, 1, 1)
                IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
        ELSE
                STATUS = SMG$PUT_CHARS (DISPLAY1, 'Occluded.', 1 , 1)
                IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
        END IF

        STATUS = SMG$CHECK_FOR_OCCLUSION (DISPLAY2, PASTE1, OCCLUSION)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        IF (OCCLUSION .EQ. 0) THEN
                STATUS = SMG$PUT_CHARS (DISPLAY2, TEXT, 1, 1)
                IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
        ELSE
                STATUS = SMG$PUT_CHARS (DISPLAY2, 'Occluded.', 1 , 1)
                IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
        END IF

        END
The output generated by this Fortran program is shown in Figure 8.4.
Figure 8.4. Output Generated by Fortran Program Calling SMG$CHECK_FOR_OCCLUSION
Output Generated by Fortran Program Calling SMG$CHECK_FOR_OCCLUSION

SMG$CONTROL_MODE

SMG$CONTROL_MODE — The Control Mode routine controls the mode of the pasteboard. This includes buffering, minimal updating, whether the screen is cleared when the pasteboard is deleted, and whether tab characters are used for screen formatting.

Format

SMG$CONTROL_MODE pasteboard-id [,new-mode] [,old-mode] [,buffer-size]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard to be changed. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

new-mode
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the new control settings to be used. The optional new-mode argument is the address of an unsigned longword that contains the mode settings. A bit set to 1 forces that mode to be employed; a bit set to 0 inhibits that mode of operation.

Valid settings are as follows:

SMG$M_BUF_ENABLEDEnables buffering.
SMG$M_CLEAR_SCREENCauses the Screen Management Facility to clear the screen when the program exits if you have not previously deleted the pasteboard.
SMG$M_IGNOREAllows you to delete the pasteboard even if batching is in effect.
SMG$M_MINUPDEnables minimal update (the default).
SMG$M_NOTABSCauses the Screen Management Facility not to use tab characters to format the screen.
SMG$M_PROTECTProtect pasteboard operations from AST interrupts (the default).
SMG$M_RELEASE_PBDAllows you to change the pasteboard size (using the SMG$CHANGE_PBD_CHARACTERISTICS routine) and prevents the Screen Management Facility from modifying anything on the screen outside of the smaller pasteboard.

All other bits must be 0 and are reserved for future OpenVMS use.

old-mode
OpenVMS usage:mask_longword
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the control settings that were in effect before calling this procedure. The optional old-mode argument is the address of an unsigned longword into which the former mode settings are written. A bit set to 1 indicates that the specified mode was employed; a bit set to 0 indicates that the mode was inhibited.

buffer-size
OpenVMS usage:word_unsigned
type:word (unsigned)
access:read only
mechanism:by reference

Specifies the size of the buffer in bytes. The optional buffer-size argument is the address of an unsigned word that contains the size of the buffer. The buffer-size argument is used when buffering mode is enabled (SMG$M_BUF_ENABLED). The default and minimum buffer size is 256 bytes. The maximum value is 65535. The buffer-size value depends on user authorization file (UAF) values and is maximized with the SYSGEN parameter MAXBUF.

Description

SMG$CONTROL_MODE lets you determine and change the mode of the Screen Management Facility operation for a specified pasteboard. By specifying different combinations of the new-mode and old-mode arguments, SMG$CONTROL_MODE can be used in the following ways:

  • To use SMG$CONTROL_MODE to determine the current mode settings, use the following format:
    SMG$CONTROL_MODE (pasteboard_id ,,old_mode)
  • To use SMG$CONTROL_MODE to set the bits without regard to their current setting, use the following format:
    SMG$CONTROL_MODE (pasteboard_id ,new_mode)
  • To use SMG$CONTROL_MODE to save the current settings, set new modes, and later restore the original settings, use the following format:
    SMG$CONTROL_MODE (pasteboard_id ,new_mode ,old_mode)

    This retrieves the current bit settings and then sets the mode according to the new-mode argument.

    Later, to restore the mode to its former state, specify the following format:
    SMG$CONTROL_MODE (pasteboard_id ,old_mode)

    This sets the new mode according to the settings previously retrieved.

If both arguments are omitted, no information is returned.

The modes that can be determined and changed using SMG$CONTROL_MODE are as follows:

  • Buffering

    In this mode, the Screen Management Facility buffers all output for efficient use of system QIOs. When the buffer fills, SMG$ writes the buffer to the terminal. By calling SMG$FLUSH_BUFFER, the user can force to the screen any output that has been placed in the pasteboard buffer but not yet written to the terminal.

  • Minimal Screen Update

    By default, the Screen Management Facility tries to minimize the number of characters actually sent to the terminal. It does this by keeping track of the current contents of the pasteboard and the new contents of the pasteboard. SMG$ then sends only those characters that have changed.

    Nonminimal updating rewrites any line containing a change, starting with the first changed character on that line.

  • Clear Screen

    By default, the Screen Management Facility does not clear the screen when the program exits if you have not already deleted the pasteboard. Use the clear screen mode to prevent this default behavior.

  • No Tabs

    If this bit is set, the Screen Management Facility does not rely on the terminal's tab settings. If it is not set, the Screen Management Facility will use physical tabs for the minimal update procedure. However, note that such use implicitly assumes that the tab stops are set to the default locations (every eight characters). Specify "no tabs" if you want to be sure that the application will run regardless of the tab settings the user has set on the terminal. By default, this bit is clear. A terminal setting of SET TERM/NOTABS may also be used to override this default.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGInvalid argument. New-mode has a bit set that does not correspond to SMG$M_BUF_ENABLED, SMG$M_MINUPD, SMG$M_CLEAR_SCREEN, or SMG$M_NOTABS, or buffer size is less than 256.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$COPY_VIRTUAL_DISPLAY

SMG$COPY_VIRTUAL_DISPLAY — The Copy a Virtual Display routine creates a copy of an existing virtual display and assigns to it a new virtual display identifier.

Format

SMG$COPY_VIRTUAL_DISPLAY current-display-id ,new-display-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

current-display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Display identifier of the virtual display to be replicated. The current-display-id argument is the address of the unsigned longword that contains the display identifier.

new-display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the display identifier of the newly created virtual display. The new-display-id argument is the address of the unsigned longword that receives the new display identifier.

Description

MG$COPY_VIRTUAL_DISPLAY creates a copy of an existing virtual display and assigns to it a new virtual display number. This newly created virtual display will not be pasted anywhere; use SMG$PASTE_VIRTUAL_DISPLAY and the new-display-id identifier to paste the newly created virtual display. The existing display being replicated does not have to be pasted when SMG$COPY_VIRTUAL_DISPLAY is invoked.

Condition Values Returned

SS$_NORMALNormal successful completion.
LIB$_INSVIRMEMInsufficient virtual memory to allocate needed buffer.

Example

C+
C This Fortran example program demonstrates the use of
C SMG$COPY_VIRTUAL_DISPLAY.
C
C This routine creates a virtual display and writes it to the
C pasteboard.  Data is placed in the virtual display using SMG$PUT_CHARS.
C-

        IMPLICIT INTEGER (A-Z)
        CHARACTER*29 TEXT

C+
C Include the SMG definitions. In particular, we want SMG$M_BORDER.
C-

        INCLUDE '($SMGDEF)'

C+
C Create two virtual displays using SMG$CREATE_VIRTUAL_DISPLAY.
C Give them borders.
C-

        ROWS = 6
        COLUMNS = 50

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        ROWS = 5
        COLUMNS = 30

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY2, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Create the pasteboard using SMG$CREATE_PASTEBOARD.
C-

        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$PUT_CHARS to put data into the virtual displays.
C-

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' This virtual display has 6 rows and 50 columns.', 2, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' This is a bordered virtual display.', 3, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' SMG$PUT_CHARS puts data in this virtual display.', 4,
     1          1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' This text should be partially occluded.', 5, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' So should part of this row.', 6, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY2, ' This is virtual', 3, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY2,
     1         ' display #2.', 4, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY2,
     1         ' This is just some more text.', 5, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 8, 15)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Copy the first virtual display, the one that is partially occluded.
C-

 STATUS = SMG$COPY_VIRTUAL_DISPLAY ( DISPLAY1, NEW_DISPLAY)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Now paste this new virtual display so that it occludes the other displays.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( NEW_DISPLAY, PASTE1, 4, 20)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
The first virtual display created by this Fortran example is shown in Figure 8.5.
Figure 8.5. First Virtual Display Generated by SMG$COPY_VIRTUAL_DISPLAY
First Virtual Display Generated by SMG$COPY_VIRTUAL_DISPLAY
The second virtual display created by this Fortran example is shown in Figure 8.6.
Figure 8.6. Second Virtual Display Generated by SMG$COPY_VIRTUAL_DISPLAY
Second Virtual Display Generated by SMG$COPY_VIRTUAL_DISPLAY
The output generated after the call to SMG$COPY_VIRTUAL_DISPLAY is shown in Figure 8.7.
Figure 8.7. Output Generated After the Call to SMG$COPY_VIRTUAL_DISPLAY
Output Generated After the Call to SMG$COPY_VIRTUAL_DISPLAY

SMG$CREATE_KEY_TABLE

SMG$CREATE_KEY_TABLE — The Create Key Table routine creates a table for key definitions.

Format

SMG$CREATE_KEY_TABLE key-table-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

key-table-id
OpenVMS usage:identifier
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the identifier of the newly created key table. The key-table-id argument is the address of an unsigned longword into which the key table identifier is written.

Description

SMG$CREATE_KEY_TABLE creates a key definition table. You can add key definitions to this table with the SMG$ADD_KEY_DEF, SMG$LOAD_KEY_DEFS, and SMG$DEFINE_KEY routines. You can list the key definitions in this table with the SMG$LIST_KEY_DEFS routine. The key definitions in this table are used by the SMG$READ_COMPOSED_LINE routine.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_WRONUMARGWrong number of arguments.
LIB$_INSVIRMEMInsufficient virtual memory.

SMG$CREATE_MENU

SMG$CREATE_MENU — The Fill the Virtual Display with a Menu routine displays menu choices in the virtual display indicated, starting at the specified row.

Format

SMG$CREATE_MENU
   display-id ,choices [,menu-type] [,flags] [,row] [,rendition-set]
   [,rendition-complement]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Display identifier of the virtual display in which the menu is created. The display-id argument is the address of an unsigned longword containing this identifier.

choices
OpenVMS usage:static array of char_string
type:character string
access:read only
mechanism:by descriptor

Static array in which each element corresponds to an item to be displayed in the menu. The choices argument is the address of a descriptor pointing to this static array of character strings. Note that blank menu items are ignored.

menu-type
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Optional bit mask specifying the type of menu to be displayed. The menu-type argument is the address of a longword bit mask that specifies this menu type. Valid values are as follows:

SMG$K_BLOCKThe menu items are displayed in matrix format (default).
SMG$K_VERTICALEach menu item is displayed on its own line.
SMG$K_HORIZONTALThe menu items are displayed all on one line.
flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Optional bit mask specifying the attributes to be used for the menu. The flags argument is the address of an unsigned longword that contains the flag. Valid values are as follows:

SMG$M_DOUBLE_SPACEDouble-spaced rows of menu items. The default is single spaced.
SMG$M_FIXED_FORMATEach menu item is in a fixed-length field. The field is the size of the largest menu item. The default is compress.
SMG$M_FULL_FIELDThe full field is highlighted when you move within the menu using item keys. The default is that menu items only are highlighted. If you specify this flag value, it also implies SMG$M_FIXED_FORMAT.
SMG$M_WIDE_MENUWide characters are used in the menu items. The default is normal sized characters.
SMG$M_WRAP_MENUThe up arrow and down arrow keys cause the menu to wrap when the cursor is on the first or last rows of the menu.
row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Optional row number in the specified virtual display at which the first menu item is displayed. The row argument is the address of a signed longword that contains this row number. If row is omitted, the first row of the virtual display's scrolling region is used.

rendition-set
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be used when writing out the menu choices. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, whilerendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed byrendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:

SetComplementAction
00Attribute set to default
10Attribute on
01Attribute set to complement of default setting
11Attribute off

Description

SMG$CREATE_MENU displays a list of menu choices in the virtual display's virtual scrolling region, starting in a specified row. Menu items start in the second column of the virtual display. Multiple menu items on the same row are separated by four spaces.

The choices are displayed with the specified rendition attributes in any one of the following formats:

VerticalEach menu item is on its own line.
HorizontalThe menu items are all on one line.
BlockThe menu items appear in matrix format.

Any menu items that do not fit within the bounds of the virtual display are not displayed, but are saved for later scrolling by SMG$SELECT_FROM_MENU. The choices are single spaced by default, but if requested this can be changed to double spaced. Four spaces separate each menu item horizontally. If requested, the items can also be displayed in fixed format columns where the width of the column is equal to the size of the largest string passed.

After a call to SMG$CREATE_MENU, the user must not output any characters to the display that disturb the rows containing the newly created menu. If characters are output that do interfere with the menu, unpredictable results will be generated. Use the SMG$SELECT_FROM_MENU routine to select an item from this menu.

SMG$CREATE_MENU supports one-dimensional Noncontiguous Array (NCA) and Varying String Array (VSA) string arrays. NCA and VSA string arrays include all string arrays generated by VSI Ada, VSI BASIC, VAX DIBOL, VSI Fortran, VSI Pascal, and VAX PL/I. (Note that if you are calling SMG$CREATE_MENU from VAX BASIC, you must still use a MAP statement to declare the array.)

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVDIS_IDThe display identifier is invalid or contains a viewport.
SMG$_xxxxAny condition value returned by SMG$PUT_CHARS, SMG$BEGIN_DISPLAY_UPDATE, and SMG$END_DISPLAY_UPDATE.
LIB$_xxxxAny condition value returned by LIB$CREATE_VM_ZONE, LIB$GET_VM, LIB$FREE_VM.

SMG$CREATE_PASTEBOARD

SMG$CREATE_PASTEBOARD — The Create a Pasteboard routine creates a pasteboard and returns its assigned pasteboard identifier.

Format

SMG$CREATE_PASTEBOARD
   pasteboard-id [,output-device] [,number-of-pasteboard-rows]
   [,number-of-pasteboard-columns] [,flags] [,type-of-terminal]
   [,device-name]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the identifier of the newly created pasteboard. The pasteboard-id argument is the address of an unsigned longword into which the new pasteboard identifier is written.

output-device
OpenVMS usage:device_name
type:character string
access:read only
mechanism:by descriptor

Specifies the file specification or logical name to which the output associated with this pasteboard will be written. The output-device argument is the address of a descriptor that points to the name of the output device. If omitted, output is sent to SYS$OUTPUT.

number-of-pasteboard-rows
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Receives the number of rows on the device specified in the output-device argument. The number-of-pasteboard-rows argument is the address of a signed longword into which is written the number of rows on the specified device, which will be the number of rows in the pasteboard.

number-of-pasteboard-columns
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Receives the number of columns on the device specified in the output-device argument. The number-of-pasteboard-columns argument is the address of a signed longword into which the number of columns on the specified device is written.

flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the attributes to be used in the pasteboard. The flags argument is the address of an unsigned longword that contains the flag. The default action is to clear the screen when the pasteboard is created.

Valid values are as follows:

SMG$M_KEEP_CONTENTSThe screen is not initially cleared. The Screen Management Facility works best when it can manage the entire screen. Therefore, using SMG$M_KEEP_CONTENTS is discouraged.
SMG$M_WORKSTATIONCalls DECterm to create a DECterm window if the Screen Management Facility is running on a workstation that is running DECwindows. If it is not running on a workstation that is running DECwindows, this flag is ignored.
type-of-terminal
OpenVMS usage:mask_longword
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the SMG$ internal device type to which the output associated with this pasteboard will be written. The type-of-terminal argument is the address of an unsigned longword into which is written the terminal type.

The returned values are as follows:
  • SMG$K_UNKNOWN
  • SMG$K_VTFOREIGN
  • SMG$K_HARDCOPY
  • SMG$K_VTTERMTABLE

If a value other than SMG$K_VTTERMTABLE is returned, you must use SMG$SNAPSHOT to output the contents of the pasteboard.

device-name
OpenVMS usage:char_string
type:character string
access:write only
mechanism:by descriptor

Receives the device name of the device on which the output associated with this pasteboard is written. The device-name argument is the address of a descriptor into which is written the device name.

If you specify the SMG$M_WORKSTATION value to the flags argument, this argument returns the DECwindows terminal device name created by the Screen Management Facility for this pasteboard. (You can then specify the device name in a call to SMG$CREATE_VIRTUAL_KEYBOARD to allow reading of input from the DECterm window.) Otherwise, the string specified by OUT_DEVICE is returned.

Description

SMG$CREATE_PASTEBOARD creates a new pasteboard, associates it with the device specified by output-device, and returns its assigned pasteboard-id. Note that if you request a pasteboard on a device that already has a pasteboard assigned, this routine returns the pasteboard-id of the existing pasteboard and returns the SMG$_PASALREXI status code.

If a program calls both SMG$CREATE_PASTEBOARD and SMG$CREATE_VIRTUAL_KEYBOARD, make sure SMG$CREATE_PASTEBOARD is called first. The program will not function correctly if SMG$CREATE_VIRTUAL_KEYBOARD is called before SMG$CREATE_PASTEBOARD.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_PASALREXISuccessful completion. A pasteboard already exists for this device.
SMG$_WRONUMARGWrong number of arguments.
LIB$_INSVIRMEMInsufficient virtual memory to allocate needed buffer.

Any condition values returned by LIB$GET_EF, LIB$GET_VM, $QIO, $GETDVI, $ASSIGN.

Example

C+                                            SMG1.FOR

C This Fortran example program demonstrates the use of
C SMG$CREATE_PASTEBOARD.
C-

        IMPLICIT INTEGER*4 (A-Z)
        SMG$M_BOLD = 1
        SMG$M_REVERSE = 2
        SMG$M_BLINK = 4
        SMG$M_UNDERLINE = 8
C+
C Establish the terminal screen as a pasteboard
C by calling SMG$CREATE_PASTEBOARD.
C-

        STATUS = SMG$CREATE_PASTEBOARD (NEW_PID,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Establish a virtual display region by calling
C SMG$CREATE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY (5,80,DISPLAY_ID,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Paste the virtual display to the screen, starting at
C row 10, column 15 using SMG$PASTE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY_ID,NEW_PID,10,15)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Write three lines to the screen using SMG$PUT_LINE.
C-

        STATUS = SMG$PUT_LINE (DISPLAY_ID,'This line is underlined',2,
        1                               SMG$M_UNDERLINE,0,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

        STATUS = SMG$PUT_LINE (DISPLAY_ID,'This line is blinking',2,
        1                               SMG$M_BLINK,0,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

        STATUS = SMG$PUT_LINE (DISPLAY_ID,'This line is reverse video',2,
        1                               SMG$M_REVERSE,0,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

        END

This Fortran program calls SMG$ routines to format screen output.

SMG$CREATE_SUBPROCESS

SMG$CREATE_SUBPROCESS — The Create and Initialize a Subprocess routine creates a DCL subprocess and associates it with a virtual display.

Format

SMG$CREATE_SUBPROCESS display-id [,AST-routine] [,AST-argument] [,flags]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the virtual display with which the newly created subprocess is associated. The display-id argument is the address of an unsigned longword containing this identifier.

AST-routine
OpenVMS usage:ast_procedure
type:procedure value
access:call without stack unwinding
mechanism:by value

Optional AST routine to be called when the currently executing command completes. The AST-routine argument is the routine's procedure value.

The AST routine is called with five parameters. The first parameter is a pointer to a data structure that contains the display-id, AST-argument, and the command-status values. The remaining four parameters for the AST routine are R0, R1, PC, and PSL. The following figure illustrates the AST-routine parameters and the data structure pointed to by the first parameter.

If the AST-routine argument is specified, the routine SMG$EXECUTE_COMMAND buffers any commands passed to it and executes them in order, calling the specified AST routine when each command completes. If the AST-routine argument is not specified, SMG$EXECUTE_COMMAND waits until the specified command completes before returning control to the user.

AST-argument
OpenVMS usage:user_arg
type:longword (unsigned)
access:read only
mechanism:by value

Optional argument you supply to the AST routine. The AST-argument parameter is an unsigned longword that contains the value to be passed to the AST routine.

flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Optional argument you supply to SMG$CREATE_SUBPROCESS. SMG$CREATE_SUBPROCESS calls LIB$SPAWN to create the subprocess. The flags argument lets you control some of the flags used in that call. Flags available to SMG$CREATE_SUBPROCESS correspond to flags in LIB$SPAWN as follows:

SMG$CREATE_SUBPROCESS FlagLIB$SPAWN FlagFunction
SMG$M_TRUSTEDTRUSTEDIf this bit is set, it indicates a SPAWN command on behalf of the application. If this bit is not set, it indicates that the SPAWN command originates from the user. SPAWN commands originating from users are disallowed in captive accounts (DCL).
SMG$M_AUTHPRIVAUTHPRIVIf this bit is set, the subprocess inherits the caller's authorized privileges. If this bit is clear, the spawned processes' authorized mask is set equal to the caller's current (active) privilege mask.
SMG$M_SUBSYSTEMSUBSYSTEMIf this bit is set, a spawned process inherits protected subsystem IDs for the duration of LOGINOUT.EXE (used to map the command line interpreter). The IDs will be removed in the process of transferring control to the command language interpreter (CLI) (as a user mode $RUNDWN is performed). If this bit is clear, LOGINOUT does not execute under the subsystem IDs.

The default is that none of these bits is set. See online Help or the VSI OpenVMS RTL Library (LIB$) Manual for a complete description of LIB$SPAWN, these flags, and the security consideration surrounding their use.

Description

SMG$CREATE_SUBPROCESS lets you create a DCL subprocess and associate this subprocess with a virtual display. (The subprocess is initialized using the DCL commands SET NOVERIFY and SET NOON.) From your main process you can then specify commands to be executed by the subprocess using the SMG$EXECUTE_COMMAND routine. Communication between processes is performed using mailboxes, thus allowing you to control the input commands and the output text. When buffering commands, use the optional AST routine to notify your main process whenever a command is completed. Broadcast trapping and unsolicited input do not have to be disabled to use this routine. For more information on mailboxes, see the mailbox driver section of the VSI OpenVMS I/O User's Reference Manual.

Before creating the subprocess, the Screen Management Facility checks to ensure that you have sufficient resources to create the necessary mailboxes and the subprocess. A remaining BYTLM value of at least 5000 and a remaining PRCLM value of at least 1 are required.

The Screen Management Facility declares an exit handler that deletes the subprocess if the user exits without first calling the routine SMG$DELETE_SUBPROCESS. Under some circumstances, however, these facility-supplied exit handlers are not executed. In this case, you must delete the subprocess with the DCL command SHOW PROCESS/SUB followed by the DCL command STOP.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INSQUOCREInsufficient quota remaining to create subprocess.
SMG$_INVDIS_IDInvalid display-id.
SMG$_SUBALREXISubprocess already exists for this display-id (alternate success status).
SS$_xxxxAny status from $GETDVI, $GETJPI, $DCLEXH, or $CREMBX.
LIB$_xxxxAny status from LIB$SPAWN, LIB$GET_EF, LIB$GET_VM.

Example

10
!
! This VAX BASIC program demonstrates the use of
! SMG$CREATE_SUBPROCESS.
!

OPTION TYPE = EXPLICIT
OPTION CONSTANT TYPE = INTEGER

%INCLUDE "LIB$ROUTINES" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
%INCLUDE "SMG$ROUTINES" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET" !*** new
                                                                       line
%INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
%INCLUDE "$SSDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

COMMON LONG NUM_COMMANDS

DECLARE SMG$R_SUBPROCESS_INFO_TABLE SMG_INFO     !***
DECLARE LONG S, PASTEBOARD_ID, DISPLAY_ID, STATUS_DISPLAY_ID

EXTERNAL INTEGER COMPLETION_ROUTINE              !***

S = SMG$CREATE_PASTEBOARD (PASTEBOARD_ID)
IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

S = SMG$CREATE_VIRTUAL_DISPLAY (12,75,DISPLAY_ID,SMG$M_BORDER)
IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

S = SMG$CREATE_VIRTUAL_DISPLAY (5,75,STATUS_DISPLAY_ID,SMG$M_BORDER)
IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

S = SMG$PASTE_VIRTUAL_DISPLAY (DISPLAY_ID,PASTEBOARD_ID,2,2)
IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

S = SMG$PASTE_VIRTUAL_DISPLAY (STATUS_DISPLAY_ID,PASTEBOARD_ID,17,2)
IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

S = SMG$CREATE_SUBPROCESS (DISPLAY_ID,    &
   LOC(COMPLETION_ROUTINE),  &
   STATUS_DISPLAY_ID)
IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

NUM_COMMANDS = 1
S= SMG$EXECUTE_COMMAND(DISPLAY_ID, "$SHOW DEFAULT")
IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

NUM_COMMANDS = NUM_COMMANDS + 1
S= SMG$EXECUTE_COMMAND(DISPLAY_ID, "$SHOW TIME")
IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF

NUM_COMMANDS = NUM_COMMANDS + 1
S= SMG$EXECUTE_COMMAND(DISPLAY_ID, "$SHOW QUOTA")
IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF
SLEEP (5) UNTIL NUM_COMMANDS <= 0
END

20 SUB COMPLETION_ROUTINE(SMG$R_SUBPROCESS_INFO_TABLE SMG_INFO,  &  !***
   LONG R0, LONG R1, LONG PC, LONG PSL)
OPTION TYPE = EXPLICIT
OPTION CONSTANT TYPE = INTEGER
%INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
%INCLUDE "$SSDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

COMMON LONG NUM_COMMANDS

DECLARE LONG S

EXTERNAL LONG FUNCTION LIB$SIGNAL(LONG),  &
  SMG$PUT_LINE (LONG, STRING)

NUM_COMMANDS = NUM_COMMANDS - 1

IF (SMG_INFO::SMG$L_STATUS AND 1) <> 0
THEN
 S = SMG$PUT_LINE(SMG_INFO::SMG$L_USR_ARG, "command completed")
 IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF
ELSE
 S = SMG$PUT_LINE(SMG_INFO::SMG$L_USR_ARG, "command failed")
 IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL (S) END IF
END IF

SUBEND

SMG$CREATE_VIEWPORT

SMG$CREATE_VIEWPORT — The Create a Virtual Viewport routine creates a viewport and associates it with a virtual display. The location and size of the viewport are specified by the caller.

Format

SMG$CREATE_VIEWPORT
   display-id ,viewport-row-start ,viewport-column-start
   ,viewport-number-rows ,viewport-number-columns

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Display identifier of the virtual display associated with the newly created viewport. The display-id argument is the address of an unsigned longword containing this identifier.

viewport-row-start
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Row number in the virtual display that will become row 1 in the viewport. The viewport-row-start argument is the address of a signed longword containing the row number.

viewport-column-start
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Column number in the virtual display that will become column 1 in the viewport. The viewport-column-start argument is the address of a signed longword containing the column number.

viewport-number-rows
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Number of rows in the viewport. The viewport-number-rows argument is the address of a signed longword containing the number of rows in the newly created viewport.

viewport-number-columns
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Number of columns in the viewport. The viewport-number-columns argument is the address of a signed longword containing the number of columns in the newly created viewport.

Description

SMG$CREATE_VIEWPORT creates a viewport and associates it 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. You can delete a viewport with the SMG$DELETE_VIEWPORT routine.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGNumber of rows or columns is less than zero.
SMG$_INVCOLInvalid column specified.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row specified.
SMG$_WINEXISTSViewport already exists on the virtual display (alternate success status).
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example creates two virtual displays, one
C being a copy of the other. The initial virtual display is
C filled and pasted to the pasteboard. The second virtual
C display is assigned a viewport and then pasted to the
C pasteboard. Therefore, only the section of the second
C virtual display that falls inside the viewport is visible.
C-
 IMPLICIT INTEGER (A-Z)
 INCLUDE '($SMGDEF)'

C Create the Virtual Display. Give it a border.

 ROWS = 9
   COLUMNS = 32

 STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1         (ROWS, COLUMNS, DISPLAY1,SMG$M_BORDER )
 IF (.NOT. STATUS) call lib$signal(%val(STATUS))

C Create the Pasteboard

 STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
 IF (.NOT. STATUS) call lib$signal(%val(STATUS))

C Put data in the Virtual Display

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 1, you see.', 1, 1)
 IF (.not. STATUS) call lib$signal(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 2, you see.', 2, 1)
 IF (.not. STATUS) call lib$signal(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 3, you see.', 3, 1)
 IF (.not. STATUS) call lib$signal(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 4, you see.', 4,1)
 IF (.not. STATUS) call lib$signal(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 5, you see.', 5, 1)
 IF (.not. STATUS) call lib$signal(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 6, you see.', 6, 1)
 IF (.not. STATUS) call lib$signal(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 7, you see.', 7, 1)
 IF (.not. STATUS) call lib$signal(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 8, you see.', 8, 1)
 IF (.not. STATUS) call lib$signal(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 9, you see.', 9, 1)
 IF (.not. STATUS) call lib$signal(%val(STATUS))

C Paste the Virtual Display
 STATUS = SMG$PASTE_VIRTUAL_DISPLAY (DISPLAY1, PASTE1, 2, 2)
 IF (.NOT. STATUS) call lib$signal(%VAL(STATUS))

     STATUS = SMG$LABEL_BORDER (DISPLAY1, 'Full Display',,,SMG$M_BOLD)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$COPY_VIRTUAL_DISPLAY (DISPLAY1, DISPLAY2)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$LABEL_BORDER (DISPLAY2, 'Viewport',,,SMG$M_BOLD)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$CREATE_VIEWPORT ( DISPLAY2, 3, 9, 3, 12)
 IF (.NOT. STATUS) call lib$signal(%VAL(STATUS))

 STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 15, 20)
 IF (.NOT. STATUS) call lib$signal(%VAL(STATUS))

 END
In this VSI Fortran example, the initial virtual display is copied to a second virtual display that has a viewport associated with it. When the second virtual display is pasted, only the portion of the virtual display that falls inside the viewport is visible. This is shown in Figure 8.8.
Figure 8.8. Output Generated by Creating a Viewport
Output Generated by Creating a Viewport

SMG$CREATE_VIRTUAL_DISPLAY

SMG$CREATE_VIRTUAL_DISPLAY — The Create Virtual Display routine creates a virtual display and returns its assigned display identifier.

Format

SMG$CREATE_VIRTUAL_DISPLAY
   number-of-rows ,number-of-columns ,display-id [,display-attributes]
   [,video-attributes] [,character-set]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

number-of-rows
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the number of rows in the newly created virtual display. The number-of-rows argument is the address of a signed longword that contains the desired number of rows.

number-of-columns
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the number of columns in the newly created virtual display. The number-of-columnsargument is the address of a signed longword that contains the desired number of columns.

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the display-id of the newly created virtual display. The display-id argument is the address of an unsigned longword into which is written the display identifier.

display-attributes
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Receives the current default display attributes. The optional display-attributes argument is the address of an unsigned longword into which the current display attributes are written.

Valid values for display-attributes are as follows:

SMG$M_BORDERSpecifies a bordered display. If omitted, the display is not bordered.
SMG$M_BLOCK_BORDERSpecifies a block-bordered display. If omitted, the display is not bordered.
SMG$M_DISPLAY_CONTROLSSpecifies that control characters such as carriage return and line feed are displayed as graphic characters, if your terminal supports them.
SMG$M_PROTECT_DISPLAYInstructs the Screen Management Facility to return an error (SMG$_DSPIN_USE) if an SMG$ call is made from an AST routine that interrupted an SMG$ call on the same display.
SMG$M_TRUNC_ICONSpecifies that an icon (generally a diamond shape) is displayed where truncation of a line exceeding the width of the virtual display has occurred.
video-attributes
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the default rendition to be applied to all output in this virtual display unless overridden by a call to a specific output routine (for example, SMG$CHANGE_RENDITION). The video-attributesargument is the address of an unsigned longword that contains the video attributes mask.

Valid values for this argument are as follows:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video, that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.
character-set
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set specifier. Valid values are SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.

Description

SMG$CREATE_VIRTUAL_DISPLAY creates a new virtual display and returns its display identifier. Initially, the virtual display contains blanks, and the virtual cursor is positioned at row 1, column 1. The virtual scrolling region is the entire virtual display. To make the display visible, use the SMG$PASTE_VIRTUAL_DISPLAY routine.

Condition Values Returned

SS$_NORMALNormal successful completion.
LIB$_INSVIRMEMInsufficient virtual memory.
SMG$_DSPIN_USEAn SMG$ call was made from an AST routine that interrupted an SMG$ call on the same display.
SMG$_INVARGInvalid argument. The video-attributes or display-attributes argument contains an unknown value.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of
C SMG$ERASE_PASTEBOARD.
C-

        IMPLICIT INTEGER*4 (A-Z)
        CHARACTER*80    OUT_STR,TRIM_STR
        CHARACTER*18    PROMPT          /'Please enter data '/

        SMG$M_BOLD = 1
        SMG$M_REVERSE = 2
        SMG$M_BLINK = 4
        SMG$M_UNDERLINE = 8
C+
C Establish the terminal screen as a pasteboard using
C SMG$CREATE_PASTEBOARD.
C-

        STATUS = SMG$CREATE_PASTEBOARD (NEW_PID,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Establish the terminal keyboard as the virtual keyboard
C by calling SMG$CREATE_VIRTUAL_KEYBOARD.
C-

        STATUS = SMG$CREATE_VIRTUAL_KEYBOARD(KEYBOARD_ID,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Establish a virtual display region by
C calling SMG$CREATE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY (5,80,DISPLAY_ID,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Paste the virtual display to the screen, starting at
C row 10, column 15.  To paste the virtual display, use
C SMG$PASTE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY_ID,NEW_PID,10,15)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Prompt the user for input, and accept that input using
C SMG$READ_STRING.
C-

        STATUS = SMG$READ_STRING(KEYBOARD_ID,OUT_STR,PROMPT,,,,,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Clear the screen using SMG$ERASE_PASTEBOARD.
C-

        STATUS = SMG$ERASE_PASTEBOARD (NEW_PID)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Trim any trailing blanks from the user input
C by calling STR$TRIM.
C-
        STATUS = STR$TRIM(TRIM_STR,OUT_STR,STR_LEN)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

C+
C Display the data input by the user using SMG$PUT_CHARS
C and SMG$PUT_LINE.
C-

        STATUS = SMG$PUT_CHARS(DISPLAY_ID,'You entered: ',,,,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
        STATUS = SMG$PUT_LINE(DISPLAY_ID,TRIM_STR(1:STR_LEN),,
     1                               SMG$M_REVERSE,0,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
        END
The output generated by this Fortran example is shown in Figure 8.9.
Figure 8.9. Output of Fortran Program Calling SMG$CREATE_VIRTUAL_DISPLAY
Output of Fortran Program Calling SMG$CREATE_VIRTUAL_DISPLAY

SMG$CREATE_VIRTUAL_KEYBOARD

SMG$CREATE_VIRTUAL_KEYBOARD — The Create a Virtual Keyboard routine creates a virtual keyboard and returns its assigned keyboard identifier.

Format

SMG$CREATE_VIRTUAL_KEYBOARD
   keyboard-id [,input-device] [,default-filespec] [,resultant-filespec]
   [,recall-size]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

keyboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the keyboard identifier of the newly created virtual keyboard. The keyboard-id argument is the address of an unsigned longword into which is written the keyboard identifier.

input-device
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

String containing the file specification or logical name of the file or terminal to be used for this virtual keyboard. The input-device argument is the address of a descriptor pointing to the file specification. If omitted, this defaults to SYS$INPUT.

default-filespec
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

String containing the default file specification. The default-filespec argument is the address of a descriptor pointing to the default file specification. If omitted, the null string is used.

The default-filespec argument might be used to specify a default device and directory, leaving theinput-device argument to supply the file name and type.

resultant-filespec
OpenVMS usage:char_string
type:character string
access:write only
mechanism:by descriptor

String into which the procedure writes the fully expanded file specification of the file used. The resultant-filespec argument is the address of a descriptor pointing to the string into which is written the file specification that was used.

recall-size
OpenVMS usage:byte_unsigned
type:byte (unsigned)
access:read only
mechanism:by reference

Number of input lines to be saved for later recall. The optional recall-size argument is the address of an unsigned byte containing the specified number of lines. A value of 0 turns off input line recall. By default, 20 lines are saved for later recall.

Description

SMG$CREATE_VIRTUAL_KEYBOARD creates the association between a file specification (terminal name or OpenVMS RMS file) and a virtual keyboard. The keyboard identifier is then passed to other SMG$ procedures in order to identify the input stream being acted upon.

If your program also calls the routine SMG$CREATE_PASTEBOARD, be sure to call that routine before you call SMG$CREATE_VIRTUAL_KEYBOARD.

If input-device does not refer to a terminal, the file is opened using RMS and all further access to that file is performed through RMS. If input-device is a terminal, this procedure assigns a channel to the terminal and sets the terminal's keyboard to application mode (if supported). These attributes are restored to their previous values when the virtual keyboard is deleted. The virtual keyboard is deleted automatically when the image exits and can also be deleted by a call to SMG$DELETE_VIRTUAL_KEYBOARD.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_FILTOOLONFile specification is too long (over 255 characters).
SMG$_WRONUMARGWrong number of arguments.
LIB$_INSEFInsufficient number of event flags.
LIB$_INSVIRMEMInsufficient virtual memory.
LIB$_INVSTRDESInvalid string descriptor.

Any RMS condition values returned by $OPEN or $CONNECT.

Any condition values returned by $GETDVIW, $ASSIGN, or $DCLEXH.

Example

C+
C This Fortran example program demonstrates the use of
C SMG$CREATE_VIRTUAL_KEYBOARD, SMG$CREATE_KEY_TABLE,
C SMG$ADD_KEY_DEF, and SMG$READ_COMPOSED_LINE.
C-


        INTEGER SMG$CREATE_VIRTUAL_KEYBOARD, SMG$CREATE_KEY_TABLE
        INTEGER SMG$ADD_KEY_DEF, SMG$READ_COMPOSED_LINE
        INTEGER SMG$DELETE_KEY_DEF, KEYBOARD, KEYTABLE, STATUS

C+
C Include the SMG definitions. In particular, we want SMG$M_KEY_NOECHO
C and SMG$M_KEY_TERMINATE.
C-

        INCLUDE '($SMGDEF)'

C+
C Create a virtual keyboard (using SMG$CREATE_VIRTUAL_KEYBOARD)
C and create a key table (using SMG$CREATE_KEY_TABLE).
C-

        STATUS = SMG$CREATE_VIRTUAL_KEYBOARD (KEYBOARD)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$CREATE_KEY_TABLE (KEYTABLE)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Prompt the user with the following instructions.
C-

        WRITE (6,*) 'When you see the prompt (->), strike the following'
        WRITE (6,*) 'keys (on the KEYPAD): '
        WRITE (6,*) '           PF1 '
        WRITE (6,*) '           5 '
        WRITE (6,*) '           PF3 '
        WRITE (6,*) ' '
        WRITE (6,*) 'When you have done this, the following sentence'
        WRITE (6,*) '(and nothing more) should appear following the'
        WRITE (6,*) 'prompt: '
        WRITE (6,*) '(PF3 should act as a carriage return.)'
        WRITE (6,*) ' '
        WRITE (6,*) 'NOW IS THE TIME FOR ALL TEXT TO APPEAR.'

C+
C Add key definitions by calling SMG$ADD_KEY_DEF.
C-

        STATUS = SMG$ADD_KEY_DEF (KEYTABLE, 'PF1', , ,
     1  'NOW IS THE TIME FOR ')
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$ADD_KEY_DEF (KEYTABLE, 'KP5', , ,
     1  'TEXT TO APPEAR.')
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$ADD_KEY_DEF (KEYTABLE, 'PF3', ,
     1  SMG$M_KEY_NOECHO + SMG$M_KEY_TERMINATE ,
     1  'THIS SHOULD NOT BE ECHOED.  IF YOU CAN
     1  SEE THIS, AN ERROR EXISTS.')
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$READ_COMPOSED_LINE to read a line of input.
C-

        WRITE(6,*) ' '
        STATUS = SMG$READ_COMPOSED_LINE (KEYBOARD, KEYTABLE, R_TEXT,
     1          '->')
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
Output session:
$ RUN example

When you see the prompt (->), strike the following
keys (on the KEYPAD):
           PF1
           5
           PF3

When you have done this, the following sentence
(and nothing more) should appear following the
prompt:
(PF3 should act as a carriage return.)

NOW IS THE TIME FOR ALL TEXT TO APPEAR.

->NOW IS THE TIME FOR ALL TEXT TO APPEAR.

$

SMG$CURSOR_COLUMN

SMG$CURSOR_COLUMN — The Return Cursor Column Position routine returns the virtual cursor's current column position in a specified virtual display.

Format

SMG$CURSOR_COLUMN display-id

Returns

OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:write only
mechanism:by value

SMG$CURSOR_COLUMN returns the current virtual cursor column position.

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

The display for which the column position is returned. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

Description

SMG$CURSOR_COLUMN returns a longword containing the value of the current virtual cursor column position for the specified virtual display. If the display-id is omitted, this routine signals SMG$_WRONUMARG. If the display-id is invalid, this routine signals SMG$_INVDIS_ID.

Condition Values Returned

SMG$_INVDIS_IDInvalid display-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$CURSOR_ROW

SMG$CURSOR_ROW — The Return Cursor Row Position routine returns the virtual cursor's current row position in a specified virtual display.

Format

SMG$CURSOR_ROW display-id

Returns

OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:write only
mechanism:by value

SMG$CURSOR_ROW returns the current row position.

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

The display for which the row position is returned. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

Description

SMG$CURSOR_ROW returns a longword containing the value of the current virtual cursor row position for the specified virtual display. If the display-id is omitted, this routine signals SMG$_WRONUMARG. If the display-id is invalid, this routine signals SMG$_INVDIS_ID.

Condition Values Returned

SMG$_INVDIS_IDInvalid display-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$DEFINE_KEY

SMG$DEFINE_KEY — The Perform a DEFINE/KEY Command routine performs the DEFINE/KEY command you provide.

Format

SMG$DEFINE_KEY key-table-id ,command-string

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

key-table-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifies the key definition table for which the DEFINE/KEY command is to be performed. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.

The key table identifier is returned by SMG$CREATE_KEY_TABLE.

command-string
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

String containing the DEFINE/KEY command to be performed. The command-string argument is the address of a descriptor pointing to the command to be performed.

The valid qualifiers for the DEFINE/KEY command are as follows:

  • /TERMINATE

  • /NOECHO

  • /LOCK

  • /IF_STATE

  • /SET_STATE

The following two restrictions apply to the DEFINE/KEY qualifiers:

  • If you use the /LOCK qualifier, you must also use the /SET_STATE qualifier.

  • If you use both the /SET_STATE and /TERMINATE qualifiers, you may not use /LOCK.

Description

SMG$DEFINE_KEY parses and performs a DEFINE/KEY command. It can be used by programs that accept DEFINE/KEY commands but do not parse the commands themselves.

SMG$DEFINE_KEY calls CLI$DCL_PARSE to parse the command line and then makes the appropriate call to SMG$ADD_KEY_DEF. The original command is then restored with a call to CLI$DCL_PARSE. Use of this procedure requires that the image be run under the DCL command language interpreter (CLI).

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_WRONUMARGWrong number of arguments.

Any condition values returned by LIB$SCOPY_DXDX.

Any condition values returned by CLI$ routines.

Any condition values returned by SMG$ADD_KEY_DEF.

SMG$DELETE_CHARS

SMG$DELETE_CHARS — The Delete Characters routine deletes characters in a virtual display.

Format

SMG$DELETE_CHARS display-id ,number-of-characters ,start-row,start-column

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifies the virtual display from which characters are to be deleted. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

number-of-characters
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the number of characters to be deleted. The number-of-characters argument is the address of a signed longword that contains the number of characters to be deleted.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row position at which to start the deletion. The start-row argument is the address of a signed longword that contains the row number at which to start the deletion.

start-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column position at which to start the deletion. The start-column argument is the address of a signed longword that contains the column position at which to start the deletion.

Description

SMG$DELETE_CHARS deletes a specified number of characters, starting at a specified row and column position. Remaining characters on the line are shifted to the left to occupy the vacated spaces. Note that this routine deletes characters only on a single line.

If you specify more characters than are available for deletion, SMG$DELETE_CHARS deletes all characters from the specified column position to the end of the line.

This routine leaves the virtual cursor at the position of the first character deleted.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGInvalid argument. The number of characters specified extends outside the virtual display.
SMG$_INVCOLInvalid column position. The specified column is outside the virtual display.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row position. The specified row is outside the virtual display.
SMG$_WILUSERMSPasteboard is not a video terminal.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of
C SMG$DELETE_CHARS.
C-

        INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD
        INTEGER SMG$PASTE_VIRTUAL_DISPLAY,  SMG$PUT_CHARS
        INTEGER SMG$DELETE_CHARS, DISPLAY1, PASTE1
        INTEGER ROWS, COLUMNS, BORDER, STATUS
C+
C Create the virtual display be calling SMG$CREATE_VIRTUAL_DISPLAY.
C To give it a border, set BORDER = 1. No border would be BORDER = 0.
C-

        ROWS = 7
        COLUMNS = 50
        BORDER = 1

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1                                (ROWS, COLUMNS, DISPLAY1, BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$CREATE_PASTEBOARD to create the pasteboard.
C-

        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$PUT_CHARS to put data in the virtual display.
C-
        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' This virtual display has 7 rows and 50 columns.', 2, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' This is a bordered virtual display.', 4, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1         ' SMG$PUT_CHARS puts data in this virtual display.',6, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Paste the virtual display to the pasteboard using
C SMG$PASTE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$DELETE_CHARS to delete 4 characters from row 4
C starting from character (column) 14, removing the characters
C "rder" from the word "bordered".
C-

        STATUS = SMG$DELETE_CHARS ( DISPLAY1, 4, 4, 14)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
The output generated by this Fortran program before the call to SMG$DELETE_CHARS is shown in Figure 8.10.
Figure 8.10. Output Generated Before the Call to SMG$DELETE_CHARS
Output Generated Before the Call to SMG$DELETE_CHARS
The output generated after the call to SMG$DELETE_CHARS is shown in Figure 8.11.
Figure 8.11. Output Generated After the Call to SMG$DELETE_CHARS
Output Generated After the Call to SMG$DELETE_CHARS

ml

SMG$DELETE_KEY_DEF

SMG$DELETE_KEY_DEF — The Delete Key Definition routine deletes a key definition from the specified table of key definitions.

Format

SMG$DELETE_KEY_DEF key-table-id ,key-name [,if-state]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

key-table-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifies the key table from which the key definition is deleted. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.

key-name
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

String containing the name of the key whose definition is to be deleted. The key-name argument is the address of a descriptor pointing to the key name. The key name is stripped of trailing blanks and converted to uppercase before use.

Table 3.1 lists the valid key names.

if-state
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

String containing a state name that further qualifies key-name. The if-state argument is the address of a descriptor pointing to the state name. If omitted, the null state is used. Thus if a key has several definitions depending on various values of if-state, this routine lets you delete only one of those definitions.

Description

SMG$DELETE_KEY_DEF deletes a key definition from the specified table of key definitions.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVKEYNAMInvalid key-name.
SMG$_INVKTB_IDInvalid key-table-id.
SMG$_KEYDEFPROKey definition is protected.
SMG$_KEYNOTDEFKey is not defined.
SMG$_WRONUMARGWrong number of arguments.

SMG$DELETE_LINE

SMG$DELETE_LINE — The Delete Line routine deletes lines from a virtual display.

Format

SMG$DELETE_LINE display-id ,start-row [,number-of-rows]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifies the virtual display from which lines are to be deleted. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the first line to be deleted from the virtual display. The start-row argument is the address of a signed longword that contains the number of the first line to be deleted.

number-of-rows
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the number of lines to be deleted. The number-of-rows argument is the address of a signed longword that contains the number of lines to be deleted. If omitted, one line is deleted.

Description

SMG$DELETE_LINE deletes one or more lines from a virtual display and scrolls the remaining lines up into the space created by the deletion. Blank lines fill the display on the bottom. The virtual cursor is left at the first column position in start-row.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGInvalid argument.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row.
SMG$_WILUSERMSPasteboard is not a video terminal.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of SMG$DELETE_LINE.
C-

        IMPLICIT INTEGER (A-Z)
C+
C Create the virtual display by calling SMG$CREATE_VIRTUAL_DISPLAY.
C To give it a border, set BORDER = 1.  No border would be BORDER = 0.
C-

        ROWS = 7
        COLUMNS = 50
        BORDER = 1

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1        (ROWS, COLUMNS, DISPLAY1, BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$CREATE_PASTEBOARD to create the pasteboard.
C-

        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$PUT_CHARS to put data in the virtual display.
C-

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1        ' This virtual display has 7 rows and 50 columns.', 2, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1        ' This is a bordered virtual display.', 4, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1        ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Paste the virtual display to the pasteboard using
C SMG$PASTE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))



C+
C Call SMG$DELETE_LINE to delete rows 3, 4, and 5.
C-

        STATUS = SMG$DELETE_LINE ( DISPLAY1, 3, 3)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
The output generated by this Fortran program before the call to SMG$DELETE_LINE is shown in Figure 8.12.
Figure 8.12. Output Generated by Fortran Program Before the Call to SMG$DELETE_LINE
Output Generated by Fortran Program Before the Call to SMG$DELETE_LINE
The output generated after the call to SMG$DELETE_LINE is shown in Figure 8.13.
Figure 8.13. Output Generated After the Call to SMG$DELETE_LINE
Output Generated After the Call to SMG$DELETE_LINE

SMG$DELETE_MENU

SMG$DELETE_MENU — The End Access to a Menu in the Virtual Display routine ends access to the menu choices in the specified virtual display.

Format

SMG$DELETE_MENU display-id [,flags]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the virtual display in which the menu choices are displayed. The display-id argument is the address of an unsigned longword containing this identifier.

flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Optional bit mask specifying possible actions to take when deleting the menu. The flags argument is the address of an unsigned longword that contains the flag. At this time, the only valid value is SMG$M_ERASE_MENU. If this option is specified, all rows containing menu items are erased.

Description

SMG$DELETE_MENU discontinues access to the menu choices in the specified virtual display. The optional flags argument lets you specify that the menu choices be removed from the display when the menu is deleted.

Condition Values Returned

SS$_NORMALNormal successful completion.
LIB$_xxxxAny condition value returned by LIB$FREE_VM.
SMG$_xxxxAny condition value returned by SMG$ERASE_DISPLAY.

SMG$DELETE_PASTEBOARD

SMG$DELETE_PASTEBOARD — The Delete Pasteboard routine deletes a pasteboard.

Format

SMG$DELETE_PASTEBOARD pasteboard-id [,flags]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard to be deleted. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Optional bit mask specifying whether the screen is cleared after the specified pasteboard is deleted. The flags argument is the address of an unsigned longword that contains the flag. Valid values are as follows:

0Does not clear the screen.
SMG$M_ERASE_PBDClears the screen (default).
SMG$M_IGNORE_BATCHEDDeletes the pasteboard even if batching is in effect.

Description

SMG$DELETE_PASTEBOARD flushes all output to the display, terminates all use of the specified pasteboard, and deallocates all resources associated with the pasteboard.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_NOTPASTEDThe specified virtual display is not pasted to the specified pasteboard.
SMG$_WILUSERMSPasteboard is not a video terminal.
SMG$_WRONUMARGWrong number of arguments.

Any condition values returned by $DASSGN, LIB$FREE_VM, LIB$FREE_EF, or SMG$FLUSH_BUFFER.

SMG$DELETE_SUBPROCESS

SMG$DELETE_SUBPROCESS — The Terminate a Subprocess routine deletes a subprocess that was created with the SMG$CREATE_SUBPROCESS routine.

Format

SMG$DELETE_SUBPROCESS display-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the virtual display associated with the subprocess being deleted. The display-idargument is the address of an unsigned longword that contains this virtual display identifier.

Description

SMG$DELETE_SUBPROCESS deletes a subprocess that was created by a call to SMG$CREATE_SUBPROCESS. Because the Screen Management Facility provides its own exit handlers, do not invoke SMG$DELETE_SUBPROCESS from within your own exit handler. For more information, see Section 4.4.

Condition Values Returned

SS$_NORMALNormal successful completion.
SS$_xxxxAny status returned by $DELPRC.
SMG$_INVDIS_IDInvalid display-id.
SMG$_NOSUBEXINo subprocess exists.
LIB$_xxxxAny status returned by LIB$FREE_VM.

SMG$DELETE_VIEWPORT

SMG$DELETE_VIEWPORT — The Delete a Viewport routine deletes the specified viewport from any pasteboards to which it is pasted.

Format

SMG$DELETE_VIEWPORT display-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the virtual display associated with the viewport to be deleted. The display-id argument is the address of an unsigned longword containing the display identifier.

Description

SMG$DELETE_VIEWPORT deletes a viewport. The viewport is automatically "unpasted" from any pasteboards to which it is pasted. However, the virtual display associated with the deleted viewport has not been deleted. To view this virtual display, you must paste it to the pasteboard with the SMG$PASTE_VIRTUAL_DISPLAY routine. To delete this virtual display, use the SMG$DELETE_VIRTUAL_DISPLAY routine.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVDIS_IDInvalid display-id.
SMG$_NO_WINASSOCNo viewport associated with the virtual display.
SMG$_WRONUMARGWrong number of arguments.

SMG$DELETE_VIRTUAL_DISPLAY

SMG$DELETE_VIRTUAL_DISPLAY — The Delete Virtual Display routine deletes a virtual display.

Format

SMG$DELETE_VIRTUAL_DISPLAY display-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display to be deleted. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY.

Description

SMG$DELETE_VIRTUAL_DISPLAY deletes a virtual display and removes it from any pasteboard on which it is pasted. It also deallocates any buffer space associated with the virtual display.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVDIS_IDInvalid display-id.
SMG$_NOTPASTEDThe specified virtual display is not pasted to the specified pasteboard.
SMG$_WILUSERMSPasteboard is not a video terminal.
SMG$_WRONUMARGWrong number of arguments.

Any condition values returned by LIB$FREE_VM.

SMG$DELETE_VIRTUAL_KEYBOARD

SMG$DELETE_VIRTUAL_KEYBOARD — The Delete Virtual Keyboard routine deletes a virtual keyboard.

Format

SMG$DELETE_VIRTUAL_KEYBOARD keyboard-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

keyboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual keyboard to be deleted. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier.

The keyboard identifier is returned by SMG$CREATE_VIRTUAL_KEYBOARD.

Description

SMG$DELETE_VIRTUAL_KEYBOARD deletes a virtual keyboard. Any terminal attributes specified when the keyboard was created are reset to their previous values and the keypad mode (numeric or application) is reset to its original state. In addition, the channel is deassigned and, if the virtual keyboard was a file, the file is closed.

Because SMG$ provides its own exit handlers, this routine should not be called from your own exit handler. For more information, see Section 4.4.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVKBD_IDInvalid keyboard-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$DEL_TERM_TABLE

SMG$DEL_TERM_TABLE — The Delete Terminal Table routine terminates access to a private TERMTABLE.EXE and frees the associated virtual address space.

Format

SMG$DEL_TERM_TABLE

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

None.

Description

SMG$DEL_TERM_TABLE terminates access to a private TERMTABLE.EXE. Calling this routine is optional. This routine is useful in the case where a calling program might need to reuse the virtual address space used by a private TERMTABLE. This routine should be used only when you perform direct (non-SMG$) I/O to terminals.

Condition Values Returned

SS$_NORMALNormal successful completion.

SMG$DISABLE_BROADCAST_TRAPPING

SMG$DISABLE_BROADCAST_TRAPPING — The Disable Broadcast Trapping routine disables trapping of broadcast messages for the specified terminal.

Format

SMG$DISABLE_BROADCAST_TRAPPING pasteboard-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard for the terminal to be affected. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

Description

SMG$DISABLE_BROADCAST_TRAPPING disables trapping of broadcast messages for the specified terminal. SMG$DISABLE_BROADCAST_TRAPPING deassigns the mailbox set with SMG$SET_BROADCAST_TRAPPING, resets the terminal characteristics, and therefore allows the user to call LIB$SPAWN. This routine must be used to disable any broadcast trapping set with the routine SMG$SET_BROADCAST_TRAPPING.

When you disable broadcast trapping, any broadcast messages that have been queued to the terminal are lost. If you enable broadcast trapping with SMG$SET_BROADCAST_TRAPPING but do not disable it with SMG$DISABLE_BROADCAST_TRAPPING before the image exits, any messages that have been broadcast to the terminal are lost when the image exits.

Note that if both broadcast trapping and the trapping of unsolicited input are enabled, then both SMG$DISABLE_BROADCAST_TRAPPING and SMG$DISABLE_UNSOLICITED_INPUT must be invoked to deassign the mailbox.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_WRONUMARGWrong number of arguments.

Any condition value returned by $QIOW.

Example

10      !+
        !This VAX BASIC program creates three virtual displays on
        !one pasteboard.
        !
        !The first virtual display contains instructions for the user,
        !the second shows trapped unsolicited input, and the third
        !lists trapped broadcast messages. The program sits in an
        !infinite loop until the user types a Ctrl/Z.
        !
        !When the program traps unsolicited input, both broadcast message
        !and unsolicited input trapping are disabled, and a subprocess
        !is spawned which executes the trapped user input.
        !
        !When control returns to the main process, broadcast trapping and
        !the trapping of unsolicited input are both reenabled. If the
        !unsolicited input which is trapped is a Ctrl/Z, the program exits.
        !-

        OPTION TYPE = EXPLICIT

        !+
        !Declaration of all routines called by the main program.
        !-

        %INCLUDE "LIB$ROUTINES" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
        %INCLUDE "SMG$ROUTINES" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

        !+
        !Declaration of the two AST routines:
        !GET_MSG is called when a broadcast message is trapped
        !GET_INPUT is called when there is unsolicited input
        !GET_INPUT is the routine which spawns the subprocess
        !-

        EXTERNAL INTEGER GET_MSG
        EXTERNAL INTEGER GET_INPUT

        DECLARE LONG pb_id, ret_status, display_id, display2_id,
                     display3_id, & key_id, key_tab_id, counter

        !+
        !Create a MAP area for variables which must be shared between the
        !main program and the AST routines.
        !-

        MAP (params) LONG disp_info(2), LONG keyboard_info(4),
        LONG done_flag

        DECLARE STRING CONSTANT top_label = "User Input"
        DECLARE STRING CONSTANT ins_label = "Instructions"
        DECLARE STRING CONSTANT msg_label = "Messages"
        DECLARE STRING CONSTANT instr_0 = "Type commands to fill INPUT
                                           display."
        DECLARE STRING CONSTANT instr_1 = "Type Ctrl/T to fill MESSAGES
                                           display."
        DECLARE STRING CONSTANT instr_2 = "Type Ctrl/Z to exit."
        DECLARE LONG CONSTANT   advance = 1

        %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
        %INCLUDE "$SMGMSG" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

        !+
        !The done_flag variable is clear (0) unless the user input was
        !a Ctrl/Z. In that case, the program exits.
        !-
        done_flag = 0

        !+
        !Create the pasteboard and the virtual keyboard
        !-

        ret_status = SMG$CREATE_PASTEBOARD (pb_id)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        !+
        !This is one of the values which must be stored in the MAP area.
        !-

        disp_info(0) = pb_id

        ret_status = SMG$CREATE_VIRTUAL_KEYBOARD (key_id)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        ret_status = SMG$CREATE_KEY_TABLE (key_tab_id)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF


        !+
        !Create the three virtual displays
        !-

        ret_status = SMG$CREATE_VIRTUAL_DISPLAY(3 BY REF, 75 BY REF, &
                display3_id, SMG$M_BORDER BY REF, SMG$M_REVERSE BY REF)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        ret_status = SMG$CREATE_VIRTUAL_DISPLAY(6 BY REF, 75 BY REF, &
                display_id, SMG$M_BORDER BY REF, SMG$M_REVERSE BY REF)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        ret_status = SMG$CREATE_VIRTUAL_DISPLAY(6 BY REF, 75 BY REF, &
                display2_id, SMG$M_BORDER BY REF, SMG$M_REVERSE BY REF)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        !+
        !The disp_info and keyboard_info arrays are required in the MAP.
        !-
        disp_info(1) = display2_id


        keyboard_info(0) = key_id
        keyboard_info(1) = key_tab_id
        keyboard_info(2) = display_id
        keyboard_info(4) = pb_id

        !+
        !Put Label borders around the three virtual displays.
        !-

        ret_status = SMG$LABEL_BORDER (display3_id, ins_label,,, &
                SMG$M_BOLD BY REF, SMG$M_REVERSE BY REF)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        ret_status = SMG$LABEL_BORDER (display_id, top_label,,, &
                SMG$M_BOLD BY REF,)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        ret_status = SMG$LABEL_BORDER (display2_id, msg_label,,, &
                SMG$M_BOLD BY REF,)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF


        !+
        !Fill the INSTRUCTIONS virtual display with user instructions.
        !-

        ret_status = SMG$PUT_LINE(display3_id, instr_0, &
    advance,,, smg$m_wrap_char)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        ret_status = SMG$PUT_LINE(display3_id, instr_1, &
    advance,,, smg$m_wrap_char)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        ret_status = SMG$PUT_LINE(display3_id, instr_2, &
    advance,,, smg$m_wrap_char)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF


        !+
        !Paste the virtual displays to the screen.
        !-

        ret_status = SMG$PASTE_VIRTUAL_DISPLAY(display3_id, pb_id, &
                2 BY REF, 4 BY REF)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        ret_status = SMG$PASTE_VIRTUAL_DISPLAY(display_id, pb_id, &
                8 BY REF, 4 BY REF)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        ret_status = SMG$PASTE_VIRTUAL_DISPLAY(display2_id, pb_id, &
                18 BY REF, 4 BY REF)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF


        !+
        !Enable the trapping of unsolicited input. GET_INPUT is the
        !AST procedure that is called when unsolicited input is
        !received. This AST has one parameter, passed as null.
        !-

        ret_status = SMG$ENABLE_UNSOLICITED_INPUT(pb_id, LOC(GET_INPUT))
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        !+
        !Enable the trapping of broadcast messages. GET_MSG is the
        !AST which is called when broadcast messages are received.
        !This AST outputs the trapped message into the MESSAGES display.
        !-

        ret_status = SMG$SET_BROADCAST_TRAPPING(pb_id, LOC(GET_MSG))
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP(ret_status BY VALUE)
        END IF

        !+
        !This loop continually executes until done_flag is set to 1.
        !Done_flag is set to 1 when the user input is a Ctrl/Z.
        !If done_flag is 1, delete the pasteboard and exit the program.
        !-

      Infinite_loop:
        IF done_flag = 0 THEN
           GOTO infinite_loop
        ELSE
           ret_status = SMG$DELETE_PASTEBOARD (pb_id)
           GOTO all_done
        END IF

     All_done:
        END

20      !+
        !Start of AST routine GET_INPUT. This AST is called whenever there
        !is unsolicited input. The unsolicited input is displayed in the
        !INPUT virtual display, and if this input is not Ctrl/Z, a subprocess
        !is spawned and the input command is executed. While this spawned
        !subprocess is executing, broadcast and unsolicited input trapping
        !are disabled.
        !-

        SUB GET_INPUT (paste_id, param, nl_1, nl_2, nl_3, nl_4)

        MAP (params) LONG disp_info(2), LONG keyboard_info(4),
        LONG done_flag

        DECLARE LONG z_status, status2, keybd_id, keybd_tab_id, disp_id, &
                     pastebd, new_display, spawn_status
        DECLARE WORD msg2_len
        DECLARE STRING msg2
        DECLARE LONG CONSTANT next_line = 1

        %INCLUDE "SMG$ROUTINES" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
        %INCLUDE "LIB$ROUTINES" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
        %INCLUDE "$SMGMSG" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

        EXTERNAL INTEGER GET_MSG
        EXTERNAL INTEGER GET_INPUT

        !+
        !Assign to the local variables the values that were stored from
        !the main program using the MAP area.
        !-

        keybd_id = keyboard_info(0)
        keybd_tab_id = keyboard_info(1)
        disp_id = keyboard_info(2)
        pastebd = keyboard_info(3)

        !+
        !SMG$ENABLE_UNSOLICITED_INPUT does not read the input, it simply
        !signals the specified AST when there is unsolicited input present.
        !You must use SMG$READ_COMPOSED_LINE to actually read the input.
        !
        !At this time, we check to see if the unsolicited input was a Ctrl/Z.
        !If so, we skip over the program lines that spawn the subprocess and
        !get ready to exit the program.
        !-

        status2 = SMG$READ_COMPOSED_LINE (keybd_id, keybd_tab_id, msg2,, &
                   msg2_len, disp_id)
        IF (status2 = SMG$_EOF) THEN
           GOTO Control_Z
        END IF

        IF (status2 AND 1%) = 0% THEN
           CALL LIB$STOP (status2 BY VALUE)
        END IF

        !+
        !In order to spawn a subprocess, we must first disable
        !unsolicited input trapping and broadcast trapping.
        !-

        status2 = SMG$DISABLE_UNSOLICITED_INPUT (pastebd)
        IF (status2 AND 1%) = 0% THEN
           CALL LIB$STOP (status2 BY VALUE)
        END IF

        status2 = SMG$DISABLE_BROADCAST_TRAPPING (pastebd)
        IF (status2 AND 1%) = 0% THEN
           CALL LIB$STOP (status2 BY VALUE)
        END IF


        !+
        !Save the current screen so that it will not be destroyed when
        !the subprocess is executing.
        !-

        status2 = SMG$SAVE_PHYSICAL_SCREEN (pastebd, new_display)
        IF (status2 AND 1%) = 0% THEN
           CALL LIB$STOP (status2 BY VALUE)
        END IF

        !+
        !Call LIB$SPAWN to create the subprocess, and pass the unsolicited
        !input as the command line.
        !-

        spawn_status = LIB$SPAWN (msg2)

        !+
        !Restore the saved screen image.
        !-

        status2 = SMG$RESTORE_PHYSICAL_SCREEN (pastebd, new_display)
        IF (status2 AND 1%) = 0% THEN
           CALL LIB$STOP (status2 BY VALUE)
        END IF

        !+
        !Reenable broadcast trapping and unsolicited input trapping.
        !-

        status2 = SMG$ENABLE_UNSOLICITED_INPUT (pastebd, LOC(GET_INPUT))
        IF (status2 AND 1%) = 0% THEN
           CALL LIB$STOP (status2 BY VALUE)
        END IF

        status2 = SMG$SET_BROADCAST_TRAPPING (pastebd, LOC(GET_MSG))
        IF (status2 AND 1%) = 0% THEN
           CALL LIB$STOP (status2 BY VALUE)
        END IF

        !+
        !Skip the steps which are performed if the unsolicited input
        !was a Ctrl/Z.
        !-

        GOTO Out_of_sub

      Control_Z:
        !+
        !We should disable unsolicited input and broadcast trapping
        !before we leave the program.
        !-

        status2 = SMG$DISABLE_UNSOLICITED_INPUT (pastebd)
        IF (status2 AND 1%) = 0% THEN
           CALL LIB$STOP (status2 BY VALUE)
        END IF
        status2 = SMG$DISABLE_BROADCAST_TRAPPING (pastebd)
        IF (status2 AND 1%) = 0% THEN
           CALL LIB$STOP (status2 BY VALUE)
        END IF

        !+
        !Set the done_flag to 1 so that the main program knows we have
        !to exit.
        !-

        done_flag = 1

      Out_of_sub:
        END SUB

30      !+
        !Start of AST routine GET_MSG. This AST is called whenever there
        !is a broadcast message. This routine prints the message in the
        !MESSAGES virtual display.
        !-

        SUB GET_MSG (paste_id, nl_1, nl_2, nl_3, nl_4)
        DECLARE LONG status1, pasteboard, second_disp
        DECLARE WORD msg_len
        DECLARE STRING msg
        DECLARE LONG CONSTANT forward = 1

        MAP (params) LONG disp_info(2), LONG keyboard_info(4)

        %INCLUDE "SMG$ROUTINES" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
        %INCLUDE "LIB$ROUTINES" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
        %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
        %INCLUDE "$SMGMSG" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

        !+
        !Assign values to the local variables according to the values
        !stored in the MAP area.
        !-

        pasteboard  = disp_info(0)
        second_disp = disp_info(1)

        !+
        !Print the trapped message in the MESSAGES display. If there are no
        !more messages, go back to the infinite loop in the main program.
        !-

        WHILE 1
              status1 = SMG$GET_BROADCAST_MESSAGE (pasteboard,
     msg, msg_len)
              IF (status1 = SMG$_NO_MORMSG) THEN
                 GOTO Exitloop
              END IF
              IF (status1 AND 1%) = 0% THEN
                 CALL LIB$STOP (status1 BY VALUE)
              END IF

              status1 = SMG$PUT_LINE (second_disp, msg, &
     forward,,, SMG$M_WRAP_CHAR)
              IF (status1 AND 1%) = 0% THEN
                 CALL LIB$STOP (status1 BY VALUE)
              END IF
        NEXT
    Exitloop:
        END SUB
To run the example program, use the following commands:
$ BASIC TRAPPING
$ LINK TRAPPING
$ RUN TRAPPING
The output for this program is shown in the following figures. In Figure 8.14, the program is waiting for either unsolicited input or broadcast messages.
Figure 8.14. Output Generated Before Any Input or Messages Are Trapped
Output Generated Before Any Input or Messages Are Trapped
The output generated after the user presses Ctrl/T is shown in Figure 8.15.
Figure 8.15. Output Generated After a Broadcast Message Is Trapped
Output Generated After a Broadcast Message Is Trapped
If the user types a command, that command is displayed in the INPUT display, and a subprocess is spawned. The output generated after the user types the MAIL command is shown in Figure 8.16.
Figure 8.16. Output Generated After a Call to LIB$SPAWN
Output Generated After a Call to LIB$SPAWN

Once the subprocess completes execution, control is returned to the main process. At this point, the screen is repainted and the program continues to wait for broadcast messages or unsolicited input. The user must press Ctrl/Z to exit the program.

SMG$DISABLE_UNSOLICITED_INPUT

SMG$DISABLE_UNSOLICITED_INPUT — The Disable Unsolicited Input routine disables the trapping of unsolicited input.

Format

SMG$DISABLE_UNSOLICITED_INPUT pasteboard-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the keyboard (associated with the specified pasteboard) for which unsolicited input is being disabled. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

Description

SMG$DISABLE_UNSOLICITED_INPUT disables unsolicited input ASTs for the specified pasteboard. SMG$DISABLE_UNSOLICITED_INPUT deassigns the mailbox set with SMG$ENABLE_UNSOLICITED_INPUT, resets the terminal characteristics and, therefore, allows the user to call LIB$SPAWN. This routine must be used to disable any unsolicited input trapping enabled with the SMG$ENABLE_UNSOLICITED_INPUT routine.

Note that if both unsolicited input trapping and the trapping of broadcast messages are enabled, then both SMG$DISABLE_UNSOLICITED_INPUT and SMG$DISABLE_BROADCAST_TRAPPING must be invoked in order to deassign the mailbox.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

Any condition values returned by $QIOW.

Example

For an example of using SMG$DISABLE_UNSOLICITED_INPUT, see the example for the SMG$DISABLE_BROADCAST_TRAPPING routine.

SMG$DRAW_CHAR

SMG$DRAW_CHAR — The Draw a Character in a Virtual Display routine draws a character at the specified position in a virtual display.

Format

SMG$DRAW_CHAR
   display-id ,flags [,row] [,column] [,rendition-set]
   [,rendition-complement]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id

OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the virtual display. The display-id argument is the address of an unsigned longword containing this identifier.

flags

OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Optional bit mask indicating the character to be drawn. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following character values:

  • SMG$M_UP

  • SMG$M_DOWN

  • SMG$M_LEFT

  • SMG$M_RIGHT

Note that you may perform a logical OR operation to draw T characters, corner characters, cross characters, and so forth. A value of 0 draws a diamond character.

row

OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Optional row number specifying the row position at which the specified character is drawn. The rowargument is the address of a signed longword containing the row number. If row is omitted, the character is drawn at the row position of the current virtual cursor.

column

OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Optional column number specifying the column position at which the specified character is drawn. The column argument is the address of a signed longword containing the column number. If columnis omitted, the character is drawn at the column position of the current virtual cursor.

rendition-set

OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement

OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, whilerendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed byrendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:

SetComplementAction
00Attribute set to default
10Attribute on
01Attribute set to complement of default setting
11Attribute off

Description

SMG$DRAW_CHAR draws a designated character at the specified position in the specified virtual display. Note that this routine does not change the position of the virtual cursor. The characters drawn depend on the type of terminal. For example, SMG$ uses the terminal's line-drawing character set if possible. If that is not available, SMG$ uses the plus sign (+), minus sign (-), and vertical bar (|) to draw a line.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVCOLInvalid column number.
SMG$_INVROWInvalid row number.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example demonstrates the use of
C SMG$DRAW_CHAR to use the terminal line drawing
C characters.
C-
 IMPLICIT INTEGER (A-Z)
 INCLUDE '($SMGDEF)'

 s = SMG$CREATE_PASTEBOARD(p_id)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$CREATE_VIRTUAL_DISPLAY(17,7,d_id,SMG$M_BORDER)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$PASTE_VIRTUAL_DISPLAY(d_id,p_id,4,30)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$SET_CURSOR_REL(d_id,1,3)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))

 s = SMG$DRAW_CHAR(d_id,SMG$M_UP,1,4,SMG$M_BOLD)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_DOWN,2,4,0,SMG$M_REVERSE)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_LEFT,3,4,SMG$M_BLINK)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_RIGHT,4,4,0,0)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_UP + SMG$M_DOWN,5)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_UP + SMG$M_LEFT,6)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_UP + SMG$M_RIGHT,7)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_DOWN + SMG$M_LEFT,8)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_DOWN + SMG$M_RIGHT,9)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_LEFT + SMG$M_RIGHT,10)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_UP + SMG$M_DOWN + SMG$M_LEFT,11)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_UP + SMG$M_DOWN + SMG$M_RIGHT,12)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_DOWN + SMG$M_LEFT + SMG$M_RIGHT,13)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_UP + SMG$M_LEFT + SMG$M_RIGHT,14)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,SMG$M_UP + SMG$M_DOWN + SMG$M_RIGHT +
     1          SMG$M_LEFT, 15)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))
 s = SMG$DRAW_CHAR(d_id,0,16)
 IF (.NOT. s) CALL LIB$SIGNAL(%VAL(s))

 END

This example generates line-drawing characters in a single column.

SMG$DRAW_LINE

SMG$DRAW_LINE — The Draw a Line routine draws a horizontal or vertical line.

Format

SMG$DRAW_LINE
   display-id ,start-row ,start-column ,end-row ,end-column
   [,rendition-set] [,rendition-complement]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display on which the line is to be drawn. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row at which to begin drawing the line. The start-row argument is the address of a signed longword that contains the row number at which to begin drawing the line.

start-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column at which to begin drawing the line. The start-column argument is the address of a signed longword that contains the column number at which to begin drawing the line.

end-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row at which the drawn line ends. The end-row argument is the address of a signed longword that contains the row number at which the drawn line ends.

end-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column at which the drawn line ends. The end-column argument is the address of a signed longword that contains the column number at which the drawn line ends.

rendition-set
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, whilerendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed byrendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:

SetComplementAction
00Attribute set to default
10Attribute on
01Attribute set to complement of default setting
11Attribute off

Description

SMG$DRAW_LINE draws a line from a specified starting row and column to a specified ending row and column. Note that this routine does not change the virtual cursor position. You can draw only horizontal or vertical lines. The characters used to draw the line depend on the type of terminal. If possible, SMG$ uses the terminal's line-drawing character set. If that is not available, SMG$ uses the plus sign (+), minus sign (-), and vertical bar (|) to draw the line.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_DIALINNOTDiagonal line not allowed.
SMG$_INVCOLInvalid column number. The specified column is outside the virtual display.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row number. The specified row is outside the virtual display
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of SMG$DRAW_LINE.
C-

        INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD
        INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$DRAW_LINE
        INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS, BORDER, STATUS
C+
C First, create the virtual display using SMG$CREATE_VIRTUAL_DISPLAY.
C To give it a border, set BORDER = 1. No border would be BORDER = 0.
C-

        ROWS = 7
        COLUMNS = 50
        BORDER = 1

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1                                (ROWS, COLUMNS, DISPLAY1, BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$CREATE_PASTEBOARD to create the pasteboard.
C-

        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Draw a vertical line using SMG$DRAW_LINE.
C Start at row 2, column 20. End at row 6.
C-

        STATUS = SMG$DRAW_LINE (DISPLAY1, 2, 20, 6, 20)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Now, use SMG$DRAW_LINE to draw a vertical line.
C Start at row 6, column 40. End at row 2.
C This is similar to the line drawn above, but we are drawing the
C line in the reverse direction.
C-

        STATUS = SMG$DRAW_LINE (DISPLAY1, 6, 40, 2, 40)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Draw a horizontal line now, again calling SMG$DRAW_LINE.
C Start at row 4, column 8. End at column 50.
C-

        STATUS = SMG$DRAW_LINE (DISPLAY1, 4, 8, 4, 50)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Paste the virtual display using SMG$PASTE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
The output generated by this Fortran example is shown in Figure 8.17.
Figure 8.17. Output Generated by Fortran Program Calling SMG$DRAW_LINE
Output Generated by Fortran Program Calling SMG$DRAW_LINE

SMG$DRAW_RECTANGLE

SMG$DRAW_RECTANGLE — The Draw a Rectangle routine draws a rectangle.

Format

SMG$DRAW_RECTANGLE
   display-id ,start-row ,start-column ,end-row ,end-column
   [,rendition-set] [,rendition-complement]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display on which the rectangle is to be drawn. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row number of the top left corner of the rectangle. The start-row argument is the address of a signed longword that contains the row number of the top left corner of the rectangle.

start-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column number of the top left corner of the rectangle. The start-column argument is the address of a signed longword that contains the column number of the top left corner of the rectangle.

end-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row number of the bottom right corner of the rectangle. The end-row argument is the address of a signed longword that contains the row number of the bottom right corner of the rectangle.

end-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column number of the bottom right corner of the rectangle. The end-column argument is the address of a signed longword that contains the column number of the bottom right corner of the rectangle.

rendition-set
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, whilerendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed byrendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:

SetComplementAction
00Attribute set to default
10Attribute on
01Attribute set to complement of default setting
11Attribute off

Description

SMG$DRAW_RECTANGLE draws a rectangle in a virtual display, given the position of the upper left corner and the lower right corner. Note that this routine does not change the virtual cursor position. The characters used to draw the lines making up the rectangle depend on the type of terminal. If possible, SMG$ uses the terminal's line-drawing character set. If that is not available, SMG$ uses the plus sign (+), minus sign (-), and vertical bar (|) to draw the lines.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVCOLInvalid column number. The specified column is outside the virtual display.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row number. The specified row is outside the virtual display.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of
C SMG$DRAW_RECTANGLE.
C
C This routine creates a virtual display and uses SMG$DRAW_RECTANGLE
C to draw a rectangle inside the bordered virtual display.
C-

C+
C Include the SMG definitions. In particular, we want SMG$M_BORDER.
C-

        INCLUDE '($SMGDEF)'
        INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD
        INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$DRAW_RECTANGLE
        INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS, STATUS

C+
C Create a virtual display with a border by calling
C SMG$CREATE_VIRTUAL_DISPLAY.
C-

        ROWS = 7
        COLUMNS = 50

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1                    (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$CREATE_PASTEBOARD to create the pasteboard.
C-

        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Using SMG$DRAW_RECTANGLE, draw a rectangle inside the bordered region.
C-

        STATUS = SMG$DRAW_RECTANGLE (DISPLAY1, 2, 10, 6, 20)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Paste the virtual display by calling SMG$PASTE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
The output generated by this Fortran example is shown in Figure 8.18.
Figure 8.18. Output Generated by Fortran Program Calling SMG$DRAW_RECTANGLE
Output Generated by Fortran Program Calling SMG$DRAW_RECTANGLE

SMG$ENABLE_UNSOLICITED_INPUT

SMG$ENABLE_UNSOLICITED_INPUT — The Enable Unsolicited Input routine detects unsolicited input and calls an AST routine in response.

Format

SMG$ENABLE_UNSOLICITED_INPUT pasteboard-id ,AST-routine [,AST-argument]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard for which unsolicited input is being enabled. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_VIRTUAL_PASTEBOARD.

AST-routine
OpenVMS usage:ast_procedure
type:procedure value
access:read only
mechanism:by value
AST routine to be called upon receipt of unsolicited input at the terminal. The AST-routineargument contains the routine's procedure value. SMG$ENABLE_UNSOLICITED_INPUT detects the presence of unsolicited input and calls the AST routine with six arguments: the pasteboard-id, the AST-argument, R0, R1, PC, and PSL (on VAX systems) or PS (on Alpha systems). The AST routine arguments are shown in Figure 8.19.
Figure 8.19. AST Routine Arguments
AST Routine Arguments
AST-argument
OpenVMS usage:user_arg
type:longword (unsigned)
access:read only
mechanism:by value

A value to be passed to the AST routine. The AST-argument argument contains the value to be passed to the AST routine.

Description

SMG$ENABLE_UNSOLICITED_INPUT detects the presence of unsolicited input and calls an AST routine in response.

Note that this routine does not read any input characters; it merely calls an AST routine to "notify" the application that it should issue a read operation with SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING or SMG$READ_VERIFY. It is up to you to read the unsolicited input.

SMG$ENABLE_UNSOLICITED_INPUT establishes a mailbox that receives messages when terminal-related events occur that require the attention of the user image. This mailbox carries status messages, not terminal data, from the driver to the user program. This status message is sent to the mailbox when there is unsolicited data in the type-ahead buffer. In this case, the user process enters into a dialogue with the terminal after an unsolicited data message arrives. Once this dialogue is complete, the Screen Management Facility reenables the unsolicited data message function on the last I/O exchange. Only one message is sent between read operations. (The SYSGEN parameters DEFMBXBUFQUO and DEFMBXMXMSG are used when creating the mailbox.)

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

Any condition values returned by $QIOW.

Example

For an example using SMG$ENABLE_UNSOLICITED_INPUT, see the example for the SMG$DISABLE_BROADCAST_TRAPPING routine.

SMG$END_DISPLAY_UPDATE

SMG$END_DISPLAY_UPDATE — The End Display Update routine ends update batching for a virtual display.

Format

SMG$END_DISPLAY_UPDATE display-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display to be affected. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

Description

SMG$END_DISPLAY_UPDATE and SMG$BEGIN_DISPLAY_UPDATE work together to control the batching of output operations on a given virtual display. Each call to SMG$BEGIN_DISPLAY_UPDATE increments a batch count. Each call to SMG$END_DISPLAY_UPDATE decrements this count. When the batch count reaches 0, the virtual display is updated with all operations done under batching, and written to the pasteboard if the virtual display is pasted.

Calling SMG$END_DISPLAY_UPDATE when the batch count is zero is a valid operation; therefore a success status is returned.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_BATSTIPROSuccessful completion. Note that batching is still in progress.
SMG$_BATWASOFFSuccessful completion. Note that batching was already off.
SMG$_INVDIS_IDInvalid display-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$END_PASTEBOARD_UPDATE

SMG$END_PASTEBOARD_UPDATE — The End Pasteboard Update routine ends update batching for a pasteboard.

Format

SMG$END_PASTEBOARD_UPDATE pasteboard-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard on which the batch count is to be decremented. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. If the batch count reaches 0, all buffered output for the specified pasteboard is written out.

Description

SMG$END_PASTEBOARD_UPDATE and SMG$BEGIN_PASTEBOARD_UPDATE work together to control the batching of output operations on a given pasteboard. Each call to SMG$BEGIN_PASTEBOARD_UPDATE increments a batch count. Each call to SMG$END_PASTEBOARD_UPDATE decrements this count. When the batch count reaches 0, the pasteboard is written to the screen.

Calling SMG$END_PASTEBOARD_UPDATE when the batch count is 0 is a valid operation; a success status is returned.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_BATSTIPROSuccessful completion. Note that batching is still in progress.
SMG$_BATWASOFFSuccessful completion. Note that batching was already off.
SMG$_INVDIS_IDInvalid display-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$ERASE_CHARS

SMG$ERASE_CHARS — The Erase Characters routine erases characters in a virtual display by replacing them with blanks.

Format

SMG$ERASE_CHARS display-id ,number-of-characters ,start-row ,start-column

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display from which characters will be erased. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

number-of-characters
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the number of characters to be replaced with blanks. The number-of-characters argument is the address of a signed longword that contains the number of characters to be replaced with blanks.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row on which the erase operation begins. The start-row argument is the address of a signed longword that contains the number of the row at which the erasure is to begin.

start-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column on which the erase operation begins. The start-column argument is the address of a signed longword that contains the number of the column at which the erasure is to begin.

Description

SMG$ERASE_CHARS erases characters in a virtual display by replacing them with blanks. The remaining text in the display is not moved. An erase operation is limited to the specified line. If number-of-characters is greater than the number of characters remaining in the line, all characters from the specified starting position to the end of the line are erased. This routine leaves the virtual cursor at the position of the first character erased.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVCOLInvalid column.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example demonstrates the use of SMG$ERASE_CHARS.
C
C Include the SMG definitions. In particular, we want SMG$M_BORDER.
C-

        IMPLICIT INTEGER (A-Z)
        INCLUDE '($SMGDEF)'

C+
C Create a virtual display with a border by calling
C SMG$CREATE_VIRTUAL_DISPLAY.
C-

        ROWS = 7
        COLUMNS = 50

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$CREATE_PASTEBOARD to create the pasteboard.
C-

        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Using SMG$PUT_CHARS, put data in the virtual display.
C-

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  ' This virtual display has 7 rows and 50 columns.', 2, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1          ' This is a bordered virtual display.', 4, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Erase 4 characters on row 4 starting from character (column) 14 by
C calling SMG$ERASE_CHARS.  This will remove the characters "rder"
C from the word "bordered".
C-

        STATUS = SMG$ERASE_CHARS ( DISPLAY1, 4, 4, 14)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
The initial output generated by this Fortran example program is shown in Figure 8.20.
Figure 8.20. Output Before the Call to SMG$ERASE_CHARS
Output Before the Call to SMG$ERASE_CHARS
The output generated after the call to SMG$ERASE_CHARS is shown in Figure 8.21.
Figure 8.21. Output After the Call to SMG$ERASE_CHARS
Output After the Call to SMG$ERASE_CHARS

SMG$ERASE_COLUMN

SMG$ERASE_COLUMN — The Erase Column from Display routine erases the specified portion of the virtual display from the given position to the end of the column.

Format

SMG$ERASE_COLUMN display-id [,start-row] [,column-number] [,end-row]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the virtual display to be affected. The display-id argument is the address of an unsigned longword containing this virtual display identifier.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Optional line number at which the erase operation begins. The start-row argument is the address of a signed longword that contains the specified line number. If this argument is omitted, the column-number argument is ignored and the erase operation begins at the current location of the virtual cursor for that virtual display.

column-number
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Optional column number at which the erase operation begins. The column-number argument is the address of a signed longword that contains the specified column number. If this argument is omitted, the start-row argument is ignored and the erase operation begins at the current location of the virtual cursor for that virtual display.

end-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Optional row number at which the erase operation ends. The end-row argument is the address of a signed longword that contains the specified row number.

Description

SMG$ERASE_COLUMN lets you erase a column of the virtual display from the specified position to the end of the column. If the position is not specified, the erase operation begins at the current position of the virtual cursor in the specified virtual display. After the erase operation has completed, this routine leaves the virtual cursor at the position of the first character erased.

Condition Values Returned

SS$_NORMALNormal successful completion.

SMG$ERASE_DISPLAY

SMG$ERASE_DISPLAY — The Erase Virtual Display routine erases all or part of a virtual display by replacing text characters with blanks.

Format

SMG$ERASE_DISPLAY
   display-id [,start-row] [,start-column] [,end-row] [,end-column]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display to be erased. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row at which the erase operation begins. The start-row argument is the address of a signed longword that contains the number of the row at which the erasure begins.

If the start-row argument is not specified, start-column is also ignored and the entire virtual display is erased. If you do not specify start-row and start-column, then end-row and end-column are ignored and the entire virtual display is erased.

start-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column at which the erase operation begins. The start-column argument is the address of a signed longword that contains the number of the column at which the erasure begins.

If the start-column argument is not specified, start-row is also ignored and the entire virtual display is erased. If you do not specify start-row and start-column, then end-row and end-column are ignored and the entire virtual display is erased.

end-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row at which the erase operation ends; that is, the last row to be erased. The end-rowargument is the address of a signed longword that contains the number of the last row to be erased.

If the end-row argument is not specified, end-column is also ignored and all remaining rows in the display are erased.

end-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column at which the erase operation ends; that is, the last column to be erased. The end-column argument is the address of a signed longword that contains the number of the last column to be erased.

If the end-column argument is not specified, end-row is also ignored and all remaining columns in the display are erased.

Description

SMG$ERASE_DISPLAY causes all or part of a virtual display to be erased by replacing text characters with blanks. If omitted, the starting positions default to 1,1. The ending positions default to the last row or column in the display. Thus, to erase the entire virtual display, you need only pass the display-id. This routine leaves the virtual cursor at the start of the erased position. If the entire display is erased, the virtual cursor is left at position 1,1.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVCOLInvalid column number. The specified column is outside the virtual display.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row number. The specified row is outside the virtual display.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of SMG$ERASE_DISPLAY.
C-

        IMPLICIT INTEGER (A-Z)

C+
C Call SMG$CREATE_VIRTUAL_DISPLAY to create the virtual
C display. To give it a border, set BORDER = 1.
C No border would be BORDER = 0.
C-

        ROWS = 7
        COLUMNS = 50
        BORDER = 1

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1                        (ROWS, COLUMNS, DISPLAY1, BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Using SMG$CREATE_PASTEBOARD, create the pasteboard.
C-

        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$PUT_CHARS to put data in the virtual display.
C-
        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1        ' This virtual display has 7 rows and 50 columns.', 2, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1        ' This is a bordered virtual display.', 4, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1        ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Paste the virtual display by calling SMG$PASTE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$ERASE_DISPLAY to erase the display from row 2,
C column 6, through row 4, column 28.
C-

        STATUS = SMG$ERASE_DISPLAY ( DISPLAY1, 2, 6, 4, 28)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
The initial display output by this Fortran program is shown in Figure 8.22.
Figure 8.22. Initial Output of Fortran Program Calling SMG$ERASE_DISPLAY
Initial Output of Fortran Program Calling SMG$ERASE_DISPLAY
This output displayed after the call to SMG$ERASE_DISPLAY is shown in Figure 8.23.
Figure 8.23. Output Displayed After the Call to SMG$ERASE_DISPLAY
Output Displayed After the Call to SMG$ERASE_DISPLAY

SMG$ERASE_LINE

SMG$ERASE_LINE — The Erase Line routine erases all or part of a line in a virtual display.

Format

SMG$ERASE_LINE display-id [,start-row] [,start-column]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display to be affected. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the line at which the erase operation starts. The start-row argument is the address of a signed longword that contains the number of the row at which the erasure starts. If omitted, start-column is also ignored and the current cursor position is used.

start-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column at which the erase operation starts. The start-column argument is the address of a signed longword that contains the number of the column at which the erasure starts. If omitted, start-row is also ignored and the current cursor position is used.

Description

SMG$ERASE_LINE erases a line from the specified starting position to the end of the line. If you do not specify a starting position, SMG$ERASE_LINE erases text from the current virtual cursor position to the end of the line. This routine leaves the virtual cursor at the start of the erased portion.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVCOLInvalid column number. The specified column is outside the virtual display.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row number. The specified row is outside the virtual display.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of
C SMG$ERASE_LINE.
C-

        IMPLICIT INTEGER (A-Z)
        INCLUDE '($SMGDEF)'

C+
C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual display
C with a border.
C-

        ROWS = 7
        COLUMNS = 50

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$CREATE_PASTEBOARD to create the pasteboard.
C-

        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Put data in the virtual display by calling SMG$PUT_CHARS.
C-


        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1       ' This virtual display has 7 rows and 50 columns.', 2, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1       ' This is a bordered virtual display.', 4, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1       ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$ERASE_LINE to erase line 2, and then again to
C erase the last 4 words on line 4.
C-

        STATUS = SMG$ERASE_LINE ( DISPLAY1, 2, 1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$ERASE_LINE ( DISPLAY1, 4, 9)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
The initial output generated by the Fortran program is shown in Figure 8.24.
Figure 8.24. Initial Output Generated by Fortran Program Calling SMG$ERASE_LINE
Initial Output Generated by Fortran Program Calling SMG$ERASE_LINE
The output generated after the call to SMG$ERASE_LINE is shown in Figure 8.25.
Figure 8.25. Output Generated After the Call to SMG$ERASE_LINE
Output Generated After the Call to SMG$ERASE_LINE

SMG$ERASE_PASTEBOARD

SMG$ERASE_PASTEBOARD — The Erase Pasteboard routine erases the contents of a pasteboard.

Format

SMG$ERASE_PASTEBOARD pasteboard-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard to be erased. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

Description

SMG$ERASE_PASTEBOARD erases the contents of a specified pasteboard. The physical cursor is left at position 1,1. If there are any virtual displays pasted to the pasteboard, they will be redrawn the next time the Screen Management Facility is used to output to the pasteboard.

Condition Values Returned

SS$_NORMALNormal successful completion.
SS$_xxxxAny status from $QIOW.
SMG$_BATWAS_ONPasteboard is batched.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of
C SMG$ERASE_PASTEBOARD.
C-

        IMPLICIT INTEGER*4 (A-Z)
        CHARACTER*80    OUT_STR,TRIM_STR
        CHARACTER*18    PROMPT          /'Please enter data '/

        SMG$M_BOLD = 1
        SMG$M_REVERSE = 2
        SMG$M_BLINK = 4
        SMG$M_UNDERLINE = 8
C+
C Establish the terminal screen as a pasteboard using
C SMG$CREATE_PASTEBOARD.
C-

        STATUS = SMG$CREATE_PASTEBOARD (NEW_PID,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Establish the terminal keyboard as the virtual keyboard
C by calling SMG$CREATE_VIRTUAL_KEYBOARD.
C-

        STATUS = SMG$CREATE_VIRTUAL_KEYBOARD(KEYBOARD_ID,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Establish a virtual display region by
C calling SMG$CREATE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY (5,80,DISPLAY_ID,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Paste the virtual display to the screen, starting at
C row 10, column 15.  To paste the virtual display, use
C SMG$PASTE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY_ID,NEW_PID,10,15)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Prompt the user for input, and accept that input using
C SMG$READ_STRING.
C-

        STATUS = SMG$READ_STRING(KEYBOARD_ID,OUT_STR,PROMPT,,,,,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Clear the screen using SMG$ERASE_PASTEBOARD.
C-

        STATUS = SMG$ERASE_PASTEBOARD (NEW_PID)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C+
C Trim any trailing blanks from the user input
C by calling STR$TRIM.
C-
        STATUS = STR$TRIM(TRIM_STR,OUT_STR,STR_LEN)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

C+
C Display the data input by the user using SMG$PUT_CHARS
C and SMG$PUT_LINE.
C-

        STATUS = SMG$PUT_CHARS(DISPLAY_ID,'You entered: ',,,,,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
        STATUS = SMG$PUT_LINE(DISPLAY_ID,TRIM_STR(1:STR_LEN),,
     1                               SMG$M_REVERSE,0,,)
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
        END

This Fortran program calls Run-Time Library Screen Management routines to format screen output, and to accept and display user input.

SMG$EXECUTE_COMMAND

SMG$EXECUTE_COMMAND — The Execute Command in a Subprocess routine executes the specified command in the subprocess created with the SMG$CREATE_SUBPROCESS routine.

Format

SMG$EXECUTE_COMMAND display-id ,command-desc [,flags] [,ret-status]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Display identifier of the virtual display with which the subprocess is associated. The display-idargument is the address of an unsigned longword containing this identifier.

command-desc
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

Command string. The command-desc argument is the address of a descriptor pointing to the command string.

flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Optional bit mask that specifies optional behavior. The flags argument is the address of an unsigned longword that contains the flag. The valid values for flags are as follows:

SMG$M_DATA_FOLLOWSInput data follows. The next call to SMG$EXECUTE_COMMAND contains input data for the currently executing command. Do not specify this value if this is the last input data item. If you do specify this value, ret-status is not returned.
SMG$M_SEND_EOFSend end-of-file marker. The end-of-file marker is sent to the subprocess.
ret-status
OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by reference

Optional status of the executed command, provided that the commands are not being buffered. The ret-status argument is the address of an unsigned longword containing this status.

Description

SMG$EXECUTE_COMMAND lets you execute the specified command in the subprocess created with SMG$CREATE_SUBPROCESS. If commands are being buffered, this routine returns control after the command has been buffered, and the user-specified AST routine is invoked when the command completes. If commands are not being buffered, SMG$EXECUTE_COMMAND waits until the command has completed execution before returning the status of the command.

When specifying the command string, you must specify a dollar sign ($) as the first character of any DCL command. Any command string that does not begin with a dollar sign is assumed to be input data for the previous command. SMG$EXECUTE_COMMAND outputs the commands and their output to the specified virtual display as they are executed. Do not perform I/O to the specified virtual display. Note that the commands SPAWN, GOTO, and LOGOUT are illegal to use as command strings and generate unpredictable results.

Since I/O is performed using mailboxes and not through the terminal driver, command prompts and single-character commands such as Ctrl/C, Ctrl/Y, Ctrl/Z, and so forth have no effect. You should specify SMG$M_SEND_EOF for the flags argument in order to send a Ctrl/Z to the subprocess. For more information on mailboxes, see the mailbox driver section of the VSI OpenVMS I/O User's Reference Manual.

Condition Values Returned

SS$_NORMALNormal successful completion.
SS$_xxxxAny status from $QIO, $DCLAST, or $SYNCH.
SMG$_INPTOOLONInput is longer than 255 characters.
SMG$_INVDIS_IDInvalid display-id.
SMG$_NOSUBEXINo subprocess exists.
SMG$_xxxxAny status from SMG$PUT_LINE.
LIB$_xxxxAny status from LIB$ANALYZE_SDESC.

SMG$FIND_CURSOR_DISPLAY

SMG$FIND_CURSOR_DISPLAY — The Find Display that Contains the Cursor routine returns the identifier of the most recently pasted virtual display that contains the physical cursor.

Format

SMG$FIND_CURSOR_DISPLAY
   pasteboard-id ,display-id [,pasteboard-row] [,pasteboard-column]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard in which the physical cursor is to be found. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the identifier of the display in which the physical cursor was found. The display-idargument is the address of an unsigned longword into which the display identifier is written.

pasteboard-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

The row position at which to begin the search for the physical cursor. The optional pasteboard-rowargument is the address of a signed longword containing the pasteboard row. You can usepasteboard-row instead of the physical cursor row.

pasteboard-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

The column position at which to begin the search for the physical cursor. The optional pasteboard-column argument is the address of a signed longword containing the pasteboard column. You can use pasteboard-column instead of the physical cursor column.

Description

SMG$FIND_CURSOR_DISPLAY determines which virtual display contains the physical cursor on a specified pasteboard, and returns the virtual display's identifier. SMG$FIND_CURSOR_DISPLAY returns the display-id of the most recently pasted virtual display that contains the physical cursor. If no virtual display contains the physical cursor, this routine returns a zero, which is an invalid display identifier.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$FLUSH_BUFFER

SMG$FLUSH_BUFFER — The Flush Buffer routine flushes all buffered output to the terminal.

Format

SMG$FLUSH_BUFFER pasteboard-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard to be flushed. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

Description

SMG$FLUSH_BUFFER causes all buffered output that is not already output to be sent to the pasteboard immediately. The Screen Management Facility outputs the text when the buffer is full; therefore, this routine is only needed when a partial buffer must be output. The calling program would normally call this routine just before performing some CPU-intensive calculations, or whenever the pasteboard must be up to date.

Condition Values Returned

SS$_NORMALNormal successful completion.
SS$_xxxxAny error from $QIOW.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$FLUSH_DISPLAY_UPDATE

SMG$FLUSH_DISPLAY_UPDATE — The Flush Display Update routine flushes any update batching to the screen and leaves the update batching in effect.

Format

SMG$FLUSH_DISPLAY_UPDATE display-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display to be affected. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display argument is returned by SMG$CREATE_VIRTUAL_DISPLAY.

Description

SMG$FLUSH_DISPLAY_UPDATE works with SMG$END_DISPLAY_UPDATE and SMG$BEGIN_DISPLAY_UPDATE to control the batching of output operations on a given virtual display. Each call to SMG$FLUSH_DISPLAY_UPDATE immediately updates the virtual display with all operations previously performed under batching, and written to the pasteboard if the virtual display is pasted.

SMG$FLUSH_DISPLAY_UPDATE can be used in place of a call to SMG$END_DISPLAY_UPDATE that is immediately followed by a call to SMG$BEGIN_DISPLAY_UPDATE, when the batch count is zero, with much better performance than the two calls.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVDIS_IDInvalid display-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$GET_BROADCAST_MESSAGE

SMG$GET_BROADCAST_MESSAGE — The Get Broadcast Message routine determines whether a message has been broadcast to the pasteboard and returns the message.

Format

SMG$GET_BROADCAST_MESSAGE
   pasteboard-id [,message] [,message-length] [,message-type]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard to be checked for the presence of a broadcast message. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

message
OpenVMS usage:char_string
type:character string
access:write only
mechanism:by descriptor

A string that receives the broadcast message, if such a message is available. The message argument is the address of a descriptor that points to the string into which the message text is written. If this argument is omitted, the broadcast message is discarded.

message-length
OpenVMS usage:word_unsigned
type:word (unsigned)
access:write only
mechanism:by reference

Receives the actual length of the broadcast message. The message-length argument is the address of an unsigned word into which is written the length of the message.

message-type
OpenVMS usage:word_unsigned
type:word (unsigned)
access:write only
mechanism:by reference

Receives the type of broadcast message. The message-type argument is the address of an unsigned word into which is written the type of message. Values for message-type are defined by the $MSGDEF library definition. If the value for message-type is not MSG$_TRMBRDCST, the condition value returned is SMG$_NOBRDMSG.

Description

SMG$GET_BROADCAST_MESSAGE determines if any broadcast messages have been sent to the specified pasteboard while broadcast trapping was enabled and, if so, returns the message in the message argument. You may call this routine repeatedly until all broadcast messages have been returned. If there are no more broadcast messages available, SMG$GET_BROADCAST_MESSAGE returns the success status SMG$_NO_MORMSG.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_NO_MORMSGSuccessful completion. No more messages to be returned.
SMG$_NONBRDMSGNonbroadcast message returned.
SMG$_WRONUMARGWrong number of arguments.

Any condition values returned by LIB$SCOPY_DXDX.

SMG$GET_CHAR_AT_PHYSICAL_CURSOR

SMG$GET_CHAR_AT_PHYSICAL_CURSOR — The Return Character at Cursor routine returns the character at the current physical cursor position.

Format

SMG$GET_CHAR_AT_PHYSICAL_CURSOR
   pasteboard-id ,character-code [,rendition] [,user-rendition]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard from which to retrieve the character. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

character-code
OpenVMS usage:byte_unsigned
type:byte (unsigned)
access:write only
mechanism:by reference

Returned character code. The character-code argument is the address of an unsigned byte into which is written the character's ASCII code.

rendition
OpenVMS usage:byte_unsigned
type:byte (unsigned)
access:write only
mechanism:by reference

Receives the rendition code associated with the character code returned by the character-codeargument. The rendition argument is the address of an unsigned byte into which is written the rendition code.

user-rendition
OpenVMS usage:byte_unsigned
type:byte (unsigned)
access:write only
mechanism:by reference

Receives the user rendition code associated with the character code returned by the character-codeargument. The user-rendition argument is the address of an unsigned byte into which is written the user rendition code.

Description

SMG$GET_CHAR_AT_PHYSICAL_CURSOR returns the character that occupies the screen position corresponding to the current physical cursor position.

Note

If the Screen Management Facility has not written to the screen location occupied by the physical cursor, then the contents of that position are unknown.

If the returned character has an ASCII value less than 32 (decimal), it is not a printable character. Rather, it is an internal terminal-independent code denoting what should be displayed at that position (for example, an element of the line-drawing character set). Do not attempt to use this code for subsequent output operations.

SMG$GET_CHAR_AT_PHYSICAL_CURSOR may not return valid data if display batching or pasteboard batching is on. This can occur because the cursor position does not reflect any calls to SMG$SET_PHYSICAL_CURSOR or the SMG$SET_CURSOR_xxxx routines until batching ends.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$GET_DISPLAY_ATTR

SMG$GET_DISPLAY_ATTR — The Get Display Attributes routine receives the attributes associated with a virtual display.

Format

SMG$GET_DISPLAY_ATTR
   display-id[,height] [,width] [,display-attributes] [,video-attributes]
   [,character-set] [,flags]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display for which information is requested. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

height
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Receives the number of rows in the display. The optional height argument is the address of a signed longword into which the height is written.

width
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Receives the number of columns in the display. The optional width argument is the address of a signed longword into which is written the number of columns in the display.

display-attributes
OpenVMS usage:mask_longword
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the current default display attributes. The optional display-attributes argument is the address of an unsigned longword into which the current display attributes are written.

Valid values for display-attributes are as follows:

SMG$M_BORDERSpecifies a bordered display. If omitted, the display is not bordered.
SMG$M_BLOCK_BORDERSpecifies a block bordered display. If omitted, the display is not bordered.
SMG$M_DISPLAY_CONTROLSSpecifies that control characters such as carriage return and line feed are displayed as graphic characters, if your terminal supports them.
SMG$M_TRUNC_ICONSpecifies that an icon (generally a diamond shape) is displayed where truncation of a line exceeding the width of the virtual display has occurred.
video-attributes
OpenVMS usage:mask_longword
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the current default video attributes. The optional video-attributes argument is the address of an unsigned longword into which the current video attributes are written.

Valid video attributes are as follows:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.
character-set
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the default character set for all text in this virtual display. The optional character-set argument is the address of an unsigned longword that specifies the character set. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:write only
mechanism:by reference

Optional bit mask specifying attributes of the specified display. The flags argument is the address of an unsigned longword containing the flag. Valid values for flags are as follows:

SMG$M_SUBPROCESSDisplay has a subprocess attached to it.
SMG$M_MENUDisplay contains a menu.
SMG$M_VIEWPORTDisplay contains a viewport.

Description

SMG$GET_DISPLAY_ATTR receives the attributes of a virtual display.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVDIS_IDInvalid display-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$GET_KEYBOARD_ATTRIBUTES

SMG$GET_KEYBOARD_ATTRIBUTES — The Get Keyboard Attributes routine gets information about a virtual keyboard and leaves it in a user-supplied area: the keyboard information table (KIT).

Format

SMG$GET_KEYBOARD_ATTRIBUTES
   keyboard-id ,keyboard-info-table ,keyboard-info-table-size

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

keyboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Keyboard identifier. The keyboard-id argument is the address of an unsigned longword containing the identifier of the virtual keyboard from which to read.

Create a virtual keyboard by calling the SMG$CREATE_VIRTUAL_KEYBOARD routine.

keyboard-info-table
OpenVMS usage:unspecified
type:unspecified
access:write only
mechanism:by reference, array reference

Receives the keyboard attributes. The keyboard-info-table argument is the address of a data block into which the keyboard attributes are written.

The KIT is a byte block whose size and field references are described in $SMGDEF. It is the caller's responsibility to allocate the correct size block and to pass its address to this routine.

The values in the keyboard-info-table can be accessed through the following symbolic names:

SMG$L_DEV_CHARDevice characteristics (longword)
SMG$L_DEV_DEPENDSpecific characteristics 1 (longword)
SMG$L_DEV_DEPEND2Specific characteristics 2 (longword)
SMG$L_DEV_DEPEND3Specific characteristics 3 (longword)
SMG$B_DEV_CLASSDevice class (byte)—for example, DC$_TERM
SMG$B_RECALL_NUMSize of recall buffer (byte)*
SMG$B_DEVTYPEPhysical device type (byte)—for example, TT$_VT100
SMG$B_TYPEAHD_CHARFirst character in type-ahead buffer (byte)*
SMG$W_NUM_COLUMNSTerminal width (word)
SMG$W_TYPEAHD_CNTNumber of characters in type-ahead buffer (word)*

Items marked with an asterisk (*) will be zero unless the device is a terminal (DEVCLASS = DC$_TERM).

keyboard-info-table-size
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Size of the keyboard information table. The keyboard-info-table-size argument is the address of an unsigned longword containing the size of the KIT in bytes.

The size you specify must be exact. You can specify this size with the symbolic constant SMG$C_KEYBOARD_INFO_BLOCK.

Description

SMG$GET_KEYBOARD_ATTRIBUTES retrieves information about a virtual keyboard and leaves this information in the KIT.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGKIT is the wrong size.
SMG$_INVKBD_IDInvalid keyboard-id.

Example

10      !+
        !This VAX BASIC program demonstrates the use of
        !SMG$GET_KEYBOARD_ATTRIBUTES.
        !-

        OPTION TYPE = EXPLICIT
        OPTION CONSTANT TYPE = INTEGER

        %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
        %INCLUDE "$SSDEF"  %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

        EXTERNAL LONG FUNCTION LIB$SIGNAL( LONG BY VALUE),              &
                               SMG$CREATE_VIRTUAL_KEYBOARD( LONG ),     &
                               SMG$GET_KEYBOARD_ATTRIBUTES( LONG, ANY, LONG )

        DECLARE SMG$ATTRIBUTE_INFO_BLOCK SMG_INFO
        DECLARE LONG S, KEYBOARD_ID

        S = SMG$CREATE_VIRTUAL_KEYBOARD( KEYBOARD_ID )
        IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL( S ) END IF

        S = SMG$GET_KEYBOARD_ATTRIBUTES( KEYBOARD_ID, &
                                           SMG_INFO,      &
                                           SMG$C_KEYBOARD_INFO_BLOCK )
       IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL( S ) END IF

        PRINT SMG_INFO::SMG$L_DEV_CHAR          ! Device characteristics
        PRINT SMG_INFO::SMG$L_DEV_DEPEND        ! Specific characteristics (1)
        PRINT SMG_INFO::SMG$L_DEV_DEPEND2       ! Specific characteristics (2)
        PRINT SMG_INFO::SMG$B_DEV_CLASS         ! Device class ( DC$_TERM )
        PRINT SMG_INFO::SMG$B_RECALL_NUM        ! Size of SMG recall buffer
        PRINT SMG_INFO::SMG$B_DEV_TYPE          ! Device type ( DT$_VT100 )
        PRINT SMG_INFO::SMG$B_TYPEAHD_CHAR      ! First character in
                                                ! typeahead buffer
        PRINT SMG_INFO::SMG$W_NUM_COLUMNS       ! Terminal width
        PRINT SMG_INFO::SMG$W_TYPEAHD_CNT       ! Number of characters in
                                                ! typeahead buffer
        END

SMG$GET_KEY_DEF

SMG$GET_KEY_DEF — The Get Key Definition routine returns the key definition for a specified key.

Format

SMG$GET_KEY_DEF
   key-table-id ,key-name [,if-state] [,attributes] [,equivalence-string]
   [,state-string]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

key-table-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the key table from which you are extracting a definition. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.

The key table identifier is returned by SMG$CREATE_KEY_TABLE.

key-name
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

Specifies the name of the key associated with the definition. The key-name argument is the address of a descriptor pointing to the key name.

Table 3.1 lists the valid key names.

if-state
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

Specifies the current state name in effect after the key is pressed. The if-state argument is the address of a descriptor pointing to the state name.

See the SMG$ADD_KEY_DEF routine for more information.

attributes
OpenVMS usage:mask_longword
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the attributes bit mask for this key definition. The attributes argument is the address of a longword into which is written the bit mask describing the key's attributes.

Valid values are as follows:

SMG$M_KEY_NOECHOIf set, this bit specifies that equiv_string is not to be echoed when this key is pressed. If clear, equiv_string is echoed. If SMG$M_KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is ignored.
SMG$M_KEY_TERMINATEIf set, this bit specifies that when this key is pressed (as qualified by if-state), the input line is complete and more characters should not be accepted. If clear, more characters may be accepted.
SMG$M_KEY_LOCKSTATEIf set, and if state-string is specified, the state name specified bystate-string remains at the current state until explicitly changed by a subsequent keystroke whose definition includes a state-string. If clear, the state name specified by state-string remains in effect only for the next defined key stroke.
SMG$M_KEY_PROTECTEDIf set, this bit specifies that this key definition cannot be modified or deleted. If clear, the key definition can be modified or deleted.
equivalence-string
OpenVMS usage:char_string
type:character string
access:write only
mechanism:by descriptor

Receives the equivalence string for this key definition. The equivalence-string argument is the address of a descriptor pointing to the string into which is written the equivalence string.

state-string
OpenVMS usage:char_string
type:character string
access:write only
mechanism:by descriptor

Receives the new state name, if any, which is set by this key definition. The state-string argument is the address of a descriptor pointing to the string into which is written the new state string.

Description

SMG$GET_KEY_DEF returns the key definition associated with a specified key-name and if-state. This key definition may be used in calls to SMG$READ_COMPOSED_LINE.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVKEYNAMInvalid key-name.
SMG$_INVKTB_IDInvalid key-table-id.
SMG$_KEYNOTDEFKey not defined.
SMG$_WRONUMARGWrong number of arguments.

Any condition values returned by LIB$SCOPY_DXDX.

SMG$GET_NUMERIC_DATA

SMG$GET_NUMERIC_DATA — The Get Numeric Terminal Data routine accesses TERMTABLE.EXE and returns the value associated with a specified Boolean or numeric capability.

Format

SMG$GET_NUMERIC_DATA termtable-address ,request-code ,buffer-address

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

termtable-address
OpenVMS usage:address
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the address of the TERMTABLE entry for the desired terminal. The termtable-address argument is the address of an unsigned longword that contains the address of the terminal capabilities table (TERMTABLE).

Before calling SMG$GET_NUMERIC_DATA, you must obtain this terminal table address by calling either SMG$INIT_TERM_TABLE or SMG$INIT_TERM_TABLE_BY_TYPE.

request-code
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Request code that specifies the desired capability. The request-code argument is an unsigned longword constant containing this request code. The request code is of the form SMG$K_code, where code corresponds to a keyword in the terminal capabilities table (TERMTABLE), for example, ANSI_CRT. The SMG$K_code constants can be found in the $SMGTRMPTR library.

See Tables 5.1 through 5.4 for valid capability fields.

buffer-address
OpenVMS usage:address
type:longword (unsigned)
access:write only
mechanism:by reference

Address of the first byte of the longword to which SMG$GET_NUMERIC_DATA writes the numeric capability data. The buffer-address argument is an unsigned longword that contains the address of this buffer.

Description

SMG$GET_NUMERIC_DATA extracts the requested numeric information from a specified terminal table. Before calling SMG$GET_NUMERIC_DATA, you must obtain that terminal table address by calling either SMG$INIT_TERM_TABLE or SMG$INIT_TERM_TABLE_BY_TYPE. This routine need only be used if you are doing your own TERMTABLE access, and only when you perform direct (non-SMG$) I/O to terminals.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVREQCODInvalid request code.
SMG$_INVTERTABInvalid terminal table address.

SMG$GET_PASTEBOARD_ATTRIBUTES

SMG$GET_PASTEBOARD_ATTRIBUTES — The Get Pasteboard Attributes routine gets pasteboard attributes and stores them in the pasteboard information table.

Format

SMG$GET_PASTEBOARD_ATTRIBUTES
   pasteboard-id ,pasteboard-info-table ,pasteboard-info-table-size

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard for which information is requested. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

pasteboard-info-table
OpenVMS usage:unspecified
type:unspecified
access:write only
mechanism:by reference, array reference

Receives the pasteboard attributes. The pasteboard-info-table argument is the address of a data structure into which are written the pasteboard attributes.

The values in the pasteboard-info-table can be accessed through the following symbolic names:

SMG$L_DEVCHARDevice characteristics (longword).
SMG$L_DEVDEPENDSpecific characteristics 1 (longword).
SMG$L_DEVDEPEND2Specific characteristics 2 (longword).
SMG$L_DEVDEPEND3Specific characteristics 3 (longword).
SMG$B_DEVCLASSDevice class (byte)—for example, DC$_TERM.
SMG$B_SMG_DEVTYPE
Internal SMG device type (byte). The four possible values for SMG$B_SMG_DEVTYPE are as follows:
  • SMG$K_UNKNOWN
  • SMG$K_VTFOREIGN
  • SMG$K_HARDCOPY
  • SMG$K_VTTERMTABLE
SMG$B_PHY_DEVTYPEPhysical device type (byte)—for example, TT$_VT100. The possible values for SMG$B_PHY_DEVTYPE are defined in $TTDEF in STARLET.
SMG$B_ROWSNumber of rows on pasteboard (byte).
SMG$W_WIDTHPasteboard width (word).
SMG$B_COLORBackground color setting (byte). Valid values for SMG$B_COLOR are as follows:
SMG$C_COLOR_UNKNOWNUnknown background color
SMG$C_COLOR_WHITELight background
SMG$C_COLOR_BLACKDark background
SMG$C_COLOR_BLUEBlue background
SMG$C_COLOR_CYANCyan (green-blue) background
SMG$C_COLOR_GREENGreen background
SMG$C_COLOR_MAGENTAMagenta background
SMG$C_COLOR_REDRed background
SMG$C_COLOR_YELLOWYellow background
SMG$C_COLOR_LIGHTWhite background
SMG$C_COLOR_DARKBlack background
SMG$C_COLOR_USER1User-defined background 1
SMG$C_COLOR_USER2User-defined background 2
SMG$B_PARITYParity attributes (byte)—this field is zero if the pasteboard is not a terminal.
SMG$W_SPEEDTerminal speed (word)—this field is zero if the pasteboard is not a terminal.
SMG$W_FILLFill characteristics (word)—this field is zero if the pasteboard is not a terminal.
SMG$W_PHYS_CURSOR_ROWPasteboard row containing physical cursor (word).
SMG$W_PHYS_CURSOR_COLPasteboard column containing physical cursor (word).
SMG$L_CURSOR_DIDDisplay identifier of topmost display containing physical cursor (longword).
pasteboard-info-table-size
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the number of bytes in the pasteboard information table. The pasteboard-info-table-sizeargument is the address of an unsigned longword that contains the size (in bytes) of the pasteboard information table.

The size you specify must be exact. You can specify this size with the symbolic constant SMG$C_PASTEBOARD_INFO_BLOCK.

Description

SMG$GET_PASTEBOARD_ATTRIBUTES gets pasteboard attributes and stores them in the pasteboard information table.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGIncorrect size specified in pasteboard-info-table-size.
SMG$_WRONUMARGWrong number of arguments.

SMG$GET_PASTING_INFO

SMG$GET_PASTING_INFO — Provided that the specified virtual display is currently pasted, the Return Pasting Information routine returns the row and column of the pasting.

Format

SMG$GET_PASTING_INFO
   display-id ,pasteboard-id ,flags [,pasteboard-row] [,pasteboard-column]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the virtual display to be examined. The display-id argument is the address of an unsigned longword containing the identifier of this virtual display.

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the pasteboard on which the virtual display is pasted. The pasteboard-id argument is the address of an unsigned longword containing the identifier of this pasteboard.

flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:write only
mechanism:by reference

Bit mask indicating the status of the specified virtual display with respect to the specified pasteboard. The flags argument is the address of an unsigned longword that contains the flag. Valid values for flags are as follows:

0The virtual display is not pasted to the specified pasteboard.
SMG$M_DISPLAY_PASTEDThe virtual display specified by display-id is pasted to the pasteboard specified by the pasteboard-id argument.
pasteboard-row
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Row of the pasteboard that contains row 1 of the specified virtual display. The optional pasteboard-row argument is the address of a signed longword containing the number of the pasteboard row that contains the first row of the virtual display.

pasteboard-column
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Column of the pasteboard that contains column 1 of the specified virtual display. The optional pasteboard-column argument is the address of a signed longword containing the number of the pasteboard column that contains the first column of the virtual display.

Description

SMG$GET_PASTING_INFO first checks to see if the virtual display specified by display-id is pasted to the pasteboard specified by pasteboard-id. If this virtual display is pasted to this pasteboard, SMG$GET_PASTING_INFO returns the row and column numbers of the pasteboard that correspond to row 1 and column 1 of the pasted virtual display.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_ILLBATFNCDisplay is batched.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$GET_TERM_DATA

SMG$GET_TERM_DATA — The Get Terminal Data routine accesses TERMTABLE.EXE and returns the character sequence that causes a terminal to perform a specified operation.

Format

SMG$GET_TERM_DATA
   termtable-address ,request-code ,maximum-buffer-length
   ,return-length ,capability-data [,input-argument-vector]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

termtable-address
OpenVMS usage:address
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the address of the TERMTABLE entry for the desired terminal. The termtable-address argument is the address of an unsigned longword that contains the address of the terminal capabilities table (TERMTABLE).

The TERMTABLE address is returned by SMG$INIT_TERM_TABLE or SMG$INIT_TERM_TABLE_BY_TYPE.

request-code
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Longword constant of the form SMG$K_code, where code is the name of the desired capability field. The request-code argument is the address of a signed longword that contains the request code. The SMG$K_code constants can be found in the $SMGTRMPTR library.

See Tables 5.1 through 5.4 for valid capability fields.

maximum-buffer-length
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Maximum length of the buffer into which the requested capability data is written. The maximum-buffer-length argument is the address of a signed longword that contains the maximum number of bytes that can be written into the buffer.

return-length
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Receives the number of bytes actually written into the buffer. The return-length argument is the address of a signed longword into which is written the number of bytes transferred into the buffer.

capability-data
OpenVMS usage:unspecified
type:unspecified
access:by reference, array reference

Address of the first byte of the buffer which is to receive the capability data. The capability-dataargument contains the address of the buffer.

input-argument-vector
OpenVMS usage:vector_longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference, array reference

Address of a list of longwords used for capabilities that require a variable number of arguments, and for those that require substitution or arithmetic operations on an argument. The input-argument-vector argument is the address of an array of unsigned longwords that contains capability arguments. The first longword must contain the number of arguments that follow.

Description

SMG$GET_TERM_DATA should be used only when you perform direct (non-SMG$) I/O to terminals. It accesses the TERMTABLE.EXE entry for the specified type of terminal and returns the character sequence that performs the specified operation. It is up to you to send this character sequence to the terminal.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVREQCODInvalid request code.
SMG$_INVTERTABInvalid terminal table address.

SMG$GET_VIEWPORT_CHAR

SMG$GET_VIEWPORT_CHAR — The Get Characteristics of Display Viewport routine returns the characteristics of the specified viewport.

Format

SMG$GET_VIEWPORT_CHAR
   display-id [,viewport-row-start] [,viewport-column-start]
   [,viewport-number-rows] [,viewport-number-columns]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the virtual display associated with the viewport. The display-id argument is the address of an unsigned longword containing this identifier.

viewport-row-start
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Optional argument that receives the starting row number of the viewport. The viewport-row-startargument is the address of a signed longword that receives this row number.

viewport-column-start
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Optional argument that receives the starting column number of the specified viewport. The viewport-column-start argument is the address of a signed longword that receives this column number.

viewport-number-rows
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Optional argument that receives the number of rows in the specified viewport. The viewport-number-rows argument is the address of a signed longword that receives this number.

viewport-number-columns
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Optional argument that receives the number of columns in the specified viewport. The viewport-number-columns argument is the address of a signed longword that receives this number.

Description

SMG$GET_VIEWPORT_CHAR returns the requested characteristics of the specified viewport.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVDIS_IDInvalid display-id.
SMG$_NO_WINASSOCNo viewport associated with the virtual display.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example demonstrates the use of SMG$GET_VIEWPORT_CHAR.
C The viewport created will start at row 3, column 4. It will consist of
C 7 rows and 29 columns. Note the parameters used in the SMG$CREATE_VIEWPORT
C routine. I request 26 rows and 55 columns, but my viewport is truncated
C to fit.
C-
 IMPLICIT INTEGER (A-Z)
 INCLUDE '($SMGDEF)'

C Create the virtual display. Give it a border.

 ROWS = 4
 COLUMNS = 34

 STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1         ( ROWS, COLUMNS, DISPLAY1,SMG$M_BORDER )
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%val(STATUS))

C Create the pasteboard.

 STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%val(STATUS))

C Put data in the virtual display.

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 1 of 4, you see', 1, 1 )
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 2 of 4, you see', 2, 1 )
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 3 of 4, you see', 3, 1 )
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

 STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1  'This is row number 4 of 4, you see', 4, 1 )
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

C Paste the virtual display.

 STATUS = SMG$COPY_VIRTUAL_DISPLAY(DISPLAY1,DISPLAY2)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$LABEL_BORDER (DISPLAY1, 'Full Display',,,SMG$M_BOLD)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$LABEL_BORDER (DISPLAY2,'Viewport',,,SMG$M_BOLD)
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 2, 2 )
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$CREATE_VIEWPORT ( DISPLAY2, 1, 5, 26, 55 )
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 8, 2 )
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 CALL SMG$SET_PHYSICAL_CURSOR(PASTE1, 16, 1)
 TYPE *, ' '
 TYPE *, LIB$SIGNAL(%VAL(STATUS))

 STATUS = SMG$GET_VIEWPORT_CHAR ( DISPLAY2, A, B, C, D )
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

 TYPE *, ' '
 WRITE(5,7) A,B
7 FORMAT(1X,'Row start = ',I2,8X,'Column start = ',I2)
 TYPE *, ' '
 WRITE(5,8) C,D
8 FORMAT(1X,'Number of rows =',I2,4X,'Number of columns =',I3)

 END
The output for this program is shown in Figure 8.26.
Figure 8.26. Output Generated by SMG$GET_VIEWPORT_CHAR
Output Generated by SMG$GET_VIEWPORT_CHAR

SMG$HOME_CURSOR

SMG$HOME_CURSOR — The Home Cursor routine moves the virtual cursor to the specified corner of a virtual display.

Format

SMG$HOME_CURSOR display-id [,position-code]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display in which the virtual cursor is moved. The display-id argument is the address of a longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

position-code
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the point to which the virtual cursor moves. The position-code argument is the address of a longword that contains the position code.

Valid codes for position-code are as follows:

CodeMeaning
SMG$C_UPPER_LEFTRow 1, column 1 (the upper left corner). This is the default ifposition-code is not specified.
SMG$C_LOWER_LEFTRow n, column 1 (where n is the number of rows in the display). That is, the lower left corner. It is useful to specify this position when accepting input for an upward-scrolling virtual display.
SMG$C_UPPER_RIGHTRow 1, column m (where m is the number of columns in the display). That is, the upper right corner.
SMG$C_LOWER_RIGHTRow n, column m (where n is the number of rows and m is the number of columns in the display). That is, the lower right corner.

Description

SMG$HOME_CURSOR moves the virtual cursor to a corner of the specified virtual display, according to the code specified in the position-code argument. You do not need to know the dimensions of the virtual display, or the virtual cursor location. If you omit the position-code argument, SMG$HOME_CURSOR moves the virtual display cursor to the upper left corner of the virtual display.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGInvalid argument.
SMG$_INVDIS_IDInvalid display-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$INIT_TERM_TABLE

SMG$INIT_TERM_TABLE — The Initialize Terminal Table routine initializes the TERMTABLE database for the terminal named, so that subsequent calls to SMG$GET_TERM_DATA can extract information and command strings for that terminal.

Format

SMG$INIT_TERM_TABLE terminal-name, termtable-address

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

terminal-name
OpenVMS usage:device_name
type:character string
access:read only
mechanism:by descriptor

Specifies the name of the terminal. The terminal-name argument is the address of a descriptor pointing to the terminal name. The name must be an entry in TERMTABLE.EXE.

termtable-address
OpenVMS usage:address
type:longword (unsigned)
access:write only
mechanism:by reference

Address of the entry for a particular type of terminal in TERMTABLE.EXE. The termtable-address argument is the address of an unsigned longword that contains the address of the terminal capabilities table.

You use this address when calling the SMG$GET_TERM_DATA procedure for the specified type of terminal. The TERMTABLE address is also returned by SMG$INIT_TERM_TABLE_BY_TYPE.

Description

SMG$INIT_TERM_TABLE initializes the TERMTABLE database for the terminal named, so that subsequent calls to SMG$GET_TERM_DATA can extract information and command strings for that terminal. This routine should be used only when you perform direct (non-SMG$) I/O to terminals.

SMG$INIT_TERM_TABLE first searches for TERMTABLE.EXE in the area logically named TERM$TABLOC. If TERMTABLE.EXE is not found there, the routine searches the global section SMG$TERMTABLE.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_GBLSECMAPSuccessful completion. The definition was found in the global TERMTABLE.
SMG$_PRISECMAPSuccessful completion. The definition was found in a private TERMTABLE.
SMG$_UNDTERNAMUndefined terminal name.
SMG$_UNDTERNOPUndefined terminal. No definition was found for the terminal and no private TERMTABLE was found.
SMG$_UNDTERNOSUndefined terminal. No definition was found for the terminal and no system TERMTABLE was found.

SMG$INIT_TERM_TABLE_BY_TYPE

SMG$INIT_TERM_TABLE_BY_TYPE — The Initialize TERMTABLE by OpenVMS Terminal Type routine initializes the TERMTABLE database for the terminal named, so that subsequent calls to SMG$GET_TERM_DATA can extract information and command strings for that terminal.

Format

SMG$INIT_TERM_TABLE_BY_TYPE
   terminal-type ,termtable-address [,terminal-name]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

terminal-type
OpenVMS usage:byte_signed
type:byte (signed)
access:read only
mechanism:by reference

The device type of the terminal, as designated by an OpenVMS symbolic terminal type or by another value returned by the $GETDVI system service. The terminal-type argument is the address of a signed byte that contains the terminal type.

termtable-address
OpenVMS usage:address
type:longword (unsigned)
access:write only
mechanism:by reference

Address of the entry for a particular type of terminal in TERMTABLE.EXE. The termtable-addressargument is the address of an unsigned longword into which is written the address of a terminal entry.

Use this address when calling the SMG$GET_TERM_DATA procedure for the specified type of terminal.

terminal-name
OpenVMS usage:device_name
type:character string
access:write only
mechanism:by descriptor

A string into which is written the terminal name associated with the device type. The terminal-name argument is the address of a descriptor pointing to the string into which the terminal name is written.

Description

SMG$INIT_TERM_TABLE_BY_TYPE initializes the TERMTABLE database for the terminal type specified, so that subsequent calls to SMG$GET_TERM_DATA can extract information and command strings for that type of terminal. This routine should be used only when you perform direct (non-SMG$) I/O to terminals.

SMG$INIT_TERM_TABLE_BY_TYPE first searches for TERMTABLE.EXE in the area logically named TERM$TABLOC. If TERMTABLE.EXE is not found there, the routine searches the global section SMG$TERMTABLE.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_GBLSECMAPSuccessful completion. The definition was found in the global TERMTABLE.
SMG$_PRISECMAPSuccessful completion. The definition was found in a private TERMTABLE.
SMG$_UNDTERNAMUndefined terminal name.
SMG$_UNDTERNOPUndefined terminal. No definition was found for the terminal and no private TERMTABLE was found.
SMG$_UNDTERNOSUndefined terminal. No definition was found for the terminal and no system TERMTABLE was found.

SMG$INSERT_CHARS

SMG$INSERT_CHARS — The Insert Characters routine inserts characters into a virtual display.

Format

SMG$INSERT_CHARS
   display-id ,character-string ,start-row ,start-column [,rendition-set]
   [,rendition-complement] [,character-set]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

character-string
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

The character string to be inserted. The character-string argument is the address of a descriptor that points to the string to be inserted.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

The row position at which to begin the insertion. The start-row argument is the address of a signed longword that contains the row number.

start-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

The column position at which to begin the insertion. The start-column argument is the address of a signed longword that contains the column number.

rendition-set
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, whilerendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed byrendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:

SetComplementAction
00Attribute set to default
10Attribute on
01Attribute set to complement of default setting
11Attribute off
character-set
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

Description

SMG$INSERT_CHARS inserts the specified character string at the start-row and start-columnpositions specified. Characters to the right of the insertion are shifted to the right. Any characters that do not fit on the current line are discarded. The virtual cursor remains at the character position following the last character inserted.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGUnrecognized rendition code.
SMG$_INVCOLInvalid column.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row.
SMG$_WILUSERMSPasteboard is not a video terminal.
SMG$_WRONUMARGWrong number of arguments.
LIB$_INVSTRDESInvalid string descriptor.

Example

C+
C This Fortran example program demonstrates the use of SMG$INSERT_CHARS.
C-

        IMPLICIT INTEGER (A-Z)
        INCLUDE '($SMGDEF)'

C+
C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual display
C with a border.
C-

        ROWS = 7
        COLUMNS = 50

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$CREATE_PASTEBOARD to create the pasteboard.
C-

        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Put data in the virtual display by calling SMG$PUT_CHARS.
C-

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1       ' This virtual display has 7 rows and 50 columns.', 2, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1       ' This is a bordered virtual display.', 4, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1       ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$INSERT_CHARS to add a row 1 of text, starting at column 6.
C Underline these characters.
C-

        STATUS = SMG$INSERT_CHARS ( DISPLAY1,
     1          'This is a new row.', 1, 6, SMG$M_UNDERLINE )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Calling SMG$INSERT_CHARS again, add text to row 6.
C Note that there will be some characters that will no
C longer fit on the line. They will be discarded. The
C new text will be bolded.
C-

        STATUS = SMG$INSERT_CHARS ( DISPLAY1,
     1          'to this bordered display.', 6, 28, SMG$M_BOLD )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
The output generated by this Fortran program before the call to SMG$INSERT_CHARS is shown in Figure 8.27.
Figure 8.27. Output Generated by Fortran Program Before the Call to SMG$INSERT_CHARS
Output Generated by Fortran Program Before the Call to SMG$INSERT_CHARS
The output generated by this Fortran program after the call to SMG$INSERT_CHARS is shown in Figure 8.28.
Figure 8.28. Output Generated by Fortran Program After the Call to SMG$INSERT_CHARS
Output Generated by Fortran Program After the Call to SMG$INSERT_CHARS

SMG$INSERT_LINE

SMG$INSERT_LINE — The Insert Line routine inserts a line into a virtual display and scrolls the display.

Format

SMG$INSERT_LINE
   display-id ,start-row [,character-string] [,direction] [,rendition-set]
   [,rendition-complement] [,flags] [,character-set]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row number at which the string is inserted and at which scrolling begins. The start-rowargument is the address of a signed longword that contains the row number.

character-string
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

The character string to be inserted by SMG$INSERT_LINE. The character-string argument is the address of a descriptor pointing to this string.

direction
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the scrolling direction. The direction argument is the address of a longword bit mask that contains the direction code. Valid values are SMG$M_UP and SMG$M_DOWN. SMG$M_UP is the default.

rendition-set
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, whilerendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed byrendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:

SetComplementAction
00Attribute set to default
10Attribute on
01Attribute set to complement of default setting
11Attribute off
flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Optional bit mask that specifies the action to take if the text does not fit on the line. The flagsargument is the address of an unsigned longword that contains the flag. Valid values for flags are as follows:

0Does not wrap (the default)
SMG$M_WRAP_CHARWraps at the last character on the line
SMG$M_WRAP_WORDWraps at the last space on the line
character-set
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

Description

SMG$INSERT_LINE lets you insert a line into a virtual display at a location other than the first or last line. Existing lines are scrolled in the specified direction to create an open space. If you specify acharacter-string argument, that string is written in the space created; otherwise, the new line remains blank. If the string does not span the width of the display, it is padded with blanks.

If the value of flags is SMG$M_WRAP_WORD or SMG$M_WRAP_CHAR and the specified character-string is longer than the width of the virtual display, SMG$INSERT_LINE scrolls another line and writes the excess characters in the created space. If flags is 0, any excess characters are discarded. The virtual cursor remains at the character position following the last character written.

See SMG$PUT_LINE to add lines and scroll at the first or last line in a virtual display.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGInvalid argument. The specified direction is not up or down.
SMG$_INVCOLInvalid column.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row.
SMG$_WILUSERMSPasteboard is not a video terminal.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of SMG$INSERT_LINE.
C
C Include the SMG definitions. In particular, we want SMG$M_BORDER,
C SMG$M_UNDERLINE, and SMG$M_UP.
C-

        IMPLICIT INTEGER (A-Z)
        INCLUDE '($SMGDEF)'

C+
C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual display
C with a border.
C-

        ROWS = 7
        COLUMNS = 50

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$CREATE_PASTEBOARD to create the pasteboard.
C-

        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$PUT_CHARS to put data in the virtual display.
C-

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1        ' This virtual display has 7 rows and 50 columns.', 2, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1        ' This is a bordered virtual display.', 4, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1        ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Paste the virtual display by calling SMG$PASTE_VIRTUAL_DISPLAY.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))


C+
C Call SMG$INSERT_LINE to add a line of text after line 6 and scroll
C the display. Also, underline the new characters.
C-

        STATUS = SMG$INSERT_LINE ( DISPLAY1, 7,
     1          'This is a new line.', SMG$M_UP, SMG$M_UNDERLINE )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
The initial output generated by this Fortran program is shown in Figure 8.29.
Figure 8.29. Output Generated Before the Call to SMG$INSERT_LINE
Output Generated Before the Call to SMG$INSERT_LINE
The output generated after the call to SMG$INSERT_LINE is shown in Figure 8.30.
Figure 8.30. Output Generated After the Call to SMG$INSERT_LINE
Output Generated After the Call to SMG$INSERT_LINE

SMG$INVALIDATE_DISPLAY

SMG$INVALIDATE_DISPLAY — The Mark a Display as Invalid routine marks a display as invalid and causes the entire display to be redrawn.

Format

SMG$INVALIDATE_DISPLAY display-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier.

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Description

SMG$INVALIDATE_DISPLAY marks a display as invalid and redraws the entire display. You would normally use this routine after you determine that output has been written to the display without benefit of the Screen Management Facility.

This routine redraws the virtual display by invalidating the pasteboard contents of the virtual display's "footprint." If the display is occluded, only the occluded portion of the occluding virtual display is redrawn; the entire display is not redrawn.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVDIS_IDInvalid display-id.

SMG$KEYCODE_TO_NAME

SMG$KEYCODE_TO_NAME — The Translate a Key Code into a Key Name routine translates the key code of a key on the keyboard into its associated key name.

Format

SMG$KEYCODE_TO_NAME key-code ,key-name

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

key-code
OpenVMS usage:word_unsigned
type:word (unsigned)
access:read only
mechanism:by reference

Specifies the key code to translate into a key name. The key-code argument is the address of an unsigned word that contains the key code.

The key code is returned by SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY in the word-terminator-code argument.

key-name
OpenVMS usage:char_string
type:character string
access:write only
mechanism:by descriptor

String containing the name of the key into which key-code is to be translated. The key-name argument is the address of a descriptor pointing to the character string containing the key name. Thekey-name argument is simply the name of the key (for example, COMMA, PERIOD, KP4, and so forth).

Description

SMG$KEYCODE_TO_NAME translates the key code of a key on the keyboard into its associated key name. This key code is the same code returned by the SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY routines in the word-terminator-code argument. The form of key-code is SMG$K_TRM_keyname (for example, SMG$K_TRM_DELETE).

For more information on terminator values, see Table 3.1.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVKEYNAMInvalid key-name.

SMG$LABEL_BORDER

SMG$LABEL_BORDER — The Label a Virtual Display Border routine supplies a label for a virtual display's border.

Format

SMG$LABEL_BORDER
   display-id [,text] [,position-code] [,units] [,rendition-set]
   [,rendition-complement] [,character-set]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

text
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

The new label for this display's border. The text argument is the address of a descriptor pointing to the label text. If this string is supplied, it replaces the current label text for this border. If omitted, the display is not labeled.

position-code
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies which of the display's borders contains the label. The position-code argument is the address of an unsigned longword that contains the position code.

Valid positions are as follows:

  • SMG$K_TOP

  • SMG$K_BOTTOM

  • SMG$K_RIGHT

  • SMG$K_LEFT

If this argument is omitted, the label is displayed on the top border.

units
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the character position at which the label begins within the border. The units argument is the address of a signed longword that contains the character position. If omitted, the label is centered in the specified border.

rendition-set
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, whilerendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:

SetComplementAction
00Attribute set to default
10Attribute on
01Attribute set to complement of default setting
11Attribute off
character-set
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

Description

SMG$LABEL_BORDER lets you specify text to label a virtual display. If the specified virtual display does not already have the border display attribute (SMG$M_BORDER), then this attribute is forced. A display border, which includes all four sides of the display, can have only one label. If the label string is supplied, it replaces the current label text for this border. If you supply an empty (null) label string, the border is not labeled. If the label text (as positioned within the border) does not fit within the border, this routine returns SMG$_INVARG.

The position-code and units arguments together specify the starting position of the label text within a border. If position-code is omitted, the default is the top border. If units is omitted, this routine chooses a starting position so as to center the text either horizontally or vertically, depending on the implicit or explicit position argument. If both position-code and units are omitted, the text is centered in the top border.

Note

The label may shift when it is applied to a viewport. This occurs when the label needs to be moved to appear in a sensible location. For example, the default location for a label in a virtual display is at the top of the display and centered. When a viewport is created, that label may shift to remain in the center of the display.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVARGInvalid argument. The combination of position-code, units, and textarguments resulted in a position outside the border area.
SMG$_INVDIS_IDInvalid display-id.
SMG$_WRONUMARGWrong number of arguments.

Example

C+
C This Fortran example program demonstrates the use of SMG$LABEL_BORDER.
C-

C+
C Include the SMG definitions. In particular, we want SMG$M_BORDER,
C SMG$K_TOP, SMG$K_BOTTOM, and SMG$K_RIGHT.
C-

        IMPLICIT INTEGER (A-Z)
        INCLUDE '($SMGDEF)'

C+
C Call SMG$CREATE_VIRTUAL_DISPLAY to create virtual display number 1.
C Give it a border.
C-

        ROWS = 4
        COLUMNS = 30

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$CREATE_VIRTUAL_DISPLAY to create virtual display number 2.
C Give it a border.
C-

        ROWS = 3
        COLUMNS = 30

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY2, SMG$M_BORDER)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Create virtual display number 3. Do NOT give it a border.
C-

        ROWS = 4
        COLUMNS = 35

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1          (ROWS, COLUMNS, DISPLAY3)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Use SMG$CREATE_PASTEBOARD to create the pasteboard.
C-


        STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$PUT_CHARS to put data into the virtual displays.
C-

        STATUS = SMG$PUT_CHARS ( DISPLAY1,
     1          ' A bordered virtual display.', 2, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY2,
     1          ' A bordered virtual display.', 1, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PUT_CHARS ( DISPLAY3,
     1          ' Started as an unbordered display.', 2, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$LABEL_BORDER to label the virtual display borders.
C-

        STATUS = SMG$LABEL_BORDER ( DISPLAY1, 'Side', SMG$K_RIGHT )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$LABEL_BORDER ( DISPLAY2, 'LABEL Bottom',
     1          SMG$K_BOTTOM, 1 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$LABEL_BORDER ( DISPLAY3, 'Forced bordering ',
     1          SMG$K_TOP )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

C+
C Call SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual displays.
C-

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 2, 10 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 2, 45 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY3, PASTE1, 10, 5 )
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END
The output generated by this program is shown in Figure 8.31.
Figure 8.31. Output Generated by Program Calling SMG$LABEL_BORDER
Output Generated by Program Calling SMG$LABEL_BORDER

SMG$LIST_KEY_DEFS

SMG$LIST_KEY_DEFS — The List Key Definitions routine returns, one at a time, the definitions (equivalence strings) associated with specified keys in a specified key definition table.

Format

SMG$LIST_KEY_DEFS
   key-table-id ,context [,key-name] [,if-state] [,attributes]
   [,equivalence-string] [,state-string]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

key-table-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the key definition table from which you are extracting a key definition. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.

The key definition table identifier is returned by SMG$CREATE_KEY_TABLE.

context
OpenVMS usage:context
type:longword (unsigned)
access:modify
mechanism:by reference

Provides a means to extract a series of key definitions from a key definition table. The context argument is the address of an unsigned longword that contains the context variable. For the first call to this routine, you should set the context argument to zero.

The context argument is incremented by the SMG$LIST_KEY_DEFS routine so that the next call returns the next key definition.

key-name
OpenVMS usage:char_string
type:character string
access:modify
mechanism:by descriptor

Identifies the key whose value you are listing. The key-name argument is the address of a descriptor pointing to the key name.

if-state
OpenVMS usage:char_string
type:character string
access:write only
mechanism:by descriptor

Receives the state name which qualifies the next definition in the key definition table. The if-state argument is the address of a descriptor pointing to the string into which the state name is written.

attributes
OpenVMS usage:mask_longword
type:longword (unsigned)
access:write only
mechanism:by reference

Attributes of this key definition. The attributes argument is the address of an unsigned longword into which the key attributes are written.

Possible attributes are as follows:

SMG$M_KEY_NOECHOIf set, this bit specifies that equiv_string is not to be echoed when this key is pressed; if clear, equiv_string is echoed. If SMG$M_KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is ignored.
SMG$M_KEY_TERMINATEIf set, this bit specifies that when this key is pressed (as qualified by if-state), the input line is complete and more characters should not be accepted. If clear, more characters may be accepted.
SMG$M_KEY_LOCKSTATEIf set, and if state-string is specified, the state name specified bystate-string remains at the current state until explicitly changed by a subsequent keystroke whose definition includes a state-string. If clear, the state name specified by state-string remains in effect only for the next defined keystroke.
SMG$M_KEY_PROTECTEDIf set, this bit specifies that this key definition cannot be modified or deleted. If clear, the key definition can be modified or deleted.
equivalence-string
OpenVMS usage:char_string
type:character string
access:write only
mechanism:by descriptor

The character string into which the equivalence string is written for the next key definition. The equivalence-string argument is the address of a descriptor pointing to the string into which equivalence-string is written.

state-string
OpenVMS usage:char_string
type:character string
access:write only
mechanism:by descriptor

A string into which is written the new state name, if any, set by the next key definition. The state-string argument is the address of a descriptor pointing to the string into which the state name is written. If this key definition sets a state, the attributes flag SMG$M_KEY_SETSTATE is also set.

Description

SMG$LIST_KEY_DEFS, when called repeatedly, lets you examine all the definitions in a key definition table. These definitions may be used with the routine SMG$READ_COMPOSED_LINE.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVKEYNAMInvalid key-name.
SMG$_INVKTB_IDInvalid key-table-id.
SMG$_NOMOREKEYSNo more keys in this table.

Any condition value returned by LIB$SCOPY_DXDX.

SMG$LIST_PASTEBOARD_ORDER

SMG$LIST_PASTEBOARD_ORDER — The Return Pasting Information routine returns the pasteboard identifier of the pasteboard to which the specified virtual display is pasted. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual display are also returned.

Format

SMG$LIST_PASTEBOARD_ORDER
   display-id ,context ,pasteboard-id [,pasteboard-row]
   [,pasteboard-column]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Display identifier of the virtual display that is pasted. The display-id argument is the address of an unsigned longword containing the identifier of this display.

context
OpenVMS usage:context
type:longword (unsigned)
access:modify
mechanism:by reference

Context to search. The context argument is the address of an unsigned longword containing this context. On the initial call, you should set context to zero. SMG$LIST_PASTEBOARD_ORDER updates the value of context. The updated value should then be passed on the subsequent calls to obtain the next pasted display identifier.

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:write only
mechanism:by reference

Receives the identifier of the pasteboard on which the virtual display is pasted. The pasteboard-id argument is the address of an unsigned longword containing the identifier of this pasteboard.

pasteboard-row
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Row of the pasteboard that contains row 1 of the specified virtual display. The optional pasteboard-row argument is the address of a signed longword containing the number of the pasteboard row that contains the first row of the virtual display.

pasteboard-column
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Column of the pasteboard that contains column 1 of the specified virtual display. The optional pasteboard-column argument is the address of a signed longword containing the number of the pasteboard column that contains the first column of the virtual display.

Description

SMG$LIST_PASTEBOARD_ORDER returns the pasteboard identifier of the pasteboard to which the specified virtual display is pasted. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual displays are also returned.

SMG$LIST_PASTEBOARD_ORDER returns the identifier of the first (or bottom-most) pasteboard to which the specified virtual display is pasted. Call this routine in a loop, once for each succeeding pasteboard, until SMG$_NOPASTED is returned.

This routine is useful if, for example, you pasted a display to many pasteboards and you no longer know the pasteboard identifier of a pasteboard critical to your application.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVDIS_IDInvalid display-id.
SMG$_NOPASTEDNo more displays are pasted.
SMG$_WRONUMARGWrong number of arguments.

SMG$LIST_PASTING_ORDER

SMG$LIST_PASTING_ORDER — The Return Virtual Display Pasting Information routine returns the identifiers of the virtual displays pasted to a specified pasteboard. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual displays are also returned.

Format

SMG$LIST_PASTING_ORDER
   pasteboard-id ,context ,display-id [,pasteboard-row]
   [,pasteboard-column]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the pasteboard on which the virtual display is pasted. The pasteboard-id argument is the address of an unsigned longword containing the identifier of this pasteboard.

context
OpenVMS usage:context
type:longword (unsigned)
access:modify
mechanism:by reference

Context to search. The context argument is the address of an unsigned longword containing this context. On the initial call, you should set context to zero. SMG$LIST_PASTING_ORDER updates the value of context. The updated value should then be passed on subsequent calls to obtain the next pasted display identifier.

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:write only
mechanism:by reference

Identifier of the virtual display that is pasted. The display-id argument is the address of an unsigned longword containing the identifier of this virtual display.

pasteboard-row
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Row of the pasteboard that contains row 1 of the specified virtual display. The optional pasteboard-row argument is the address of a signed longword containing the number of the pasteboard row that contains the first row of the virtual display.

pasteboard-column
OpenVMS usage:longword_signed
type:longword (signed)
access:write only
mechanism:by reference

Column of the pasteboard that contains column 1 of the specified virtual display. The optional pasteboard-column argument is the address of a signed longword containing the number of the pasteboard column that contains the first column of the virtual display.

Description

SMG$LIST_PASTING_ORDER returns the identifiers of the virtual displays pasted to a specified pasteboard. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual displays are also returned.

SMG$LIST_PASTING_ORDER returns the identifier of the first (or bottommost) virtual display pasted. Call this routine in a loop, once for each succeeding pasted virtual display, until SMG$_NOTPASTED is returned.

This routine is useful if, for example, you created many virtual displays and you no longer know the display identifier of a virtual display critical to your application.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_NOTPASTEDNo more displays are pasted.
SMG$_WRONUMARGWrong number of arguments.

SMG$LOAD_KEY_DEFS

SMG$LOAD_KEY_DEFS — The Load Key Definitions routine loads a file of key definitions (DEFINE/KEY commands) into a specified key table.

Format

SMG$LOAD_KEY_DEFS key-table-id ,filespec [,default-filespec] [,flags]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

key-table-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the key table into which you are loading key definitions. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.

The key table identifier is returned by SMG$CREATE_KEY_TABLE.

filespec
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

String containing the file specification for the file of DEFINE/KEY commands. The filespec argument is the address of a descriptor pointing to the file specification.

default-filespec
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

String containing the default file specification for the file of DEFINE/KEY commands. The default-filespec argument is the address of a descriptor pointing to the default file specification. If omitted, the null string is used.

flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Optional bit mask that specifies whether filespec is to be treated as a logical name. The flags argument is the address of an unsigned longword that contains the flag. If set, flags specifies that filespec should be translated, but if this is not possible, that the null string be used.

Description

SMG$LOAD_KEY_DEFS opens and reads a file containing DEFINE/KEY commands and calls SMG$DEFINE_KEY for each command line in the file. Use of SMG$LOAD_KEY_DEFS requires that the calling program be run under the DCL command language interpreter (CLI). This routine signals any errors encountered while processing command lines. For more information, see SMG$DEFINE_KEY.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_FILTOOLONFile specification is too long (over 255 characters).

Any condition values returned by SMG$DEFINE_KEY or $OPEN.

SMG$LOAD_VIRTUAL_DISPLAY

SMG$LOAD_VIRTUAL_DISPLAY — The Load a Virtual Display from a File routine creates a new virtual display and loads it with a virtual display saved with SMG$SAVE_VIRTUAL_DISPLAY.

Format

SMG$LOAD_VIRTUAL_DISPLAY display-id [,filespec]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:write only
mechanism:by reference

Identifier of the new virtual display to be loaded with the saved virtual display. The display-id argument is the address of an unsigned longword into which is written the new display identifier.

filespec
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

String containing the file specification of the file in which the specified virtual display is saved. The filespec argument is a character string containing the file specification.

If filespec is omitted, SMG$LOAD_VIRTUAL_DISPLAY searches for the default file specification SMGDISPLY.DAT.

Description

SMG$LOAD_VIRTUAL_DISPLAY creates a new virtual display and loads it with a virtual display saved with SMG$SAVE_VIRTUAL_DISPLAY. The new virtual display contains text, renditions, and attributes from the saved virtual display, but does not include menu, viewport, and subprocess context. The new virtual display is not pasted to any pasteboard.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVDIS_IDInvalid display-id.
SMG$_xxxxAny condition value returned by SMG$CREATE_VIRTUAL_DISPLAY.
RMS$_xxxxAny error returned by $OPEN, $CONNECT, $PUT, and $CLOSE.

SMG$MOVE_TEXT

SMG$MOVE_TEXT — The Move Text from One Virtual Display to Another routine moves a rectangle of 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 of the new virtual display.

Format

SMG$MOVE_TEXT
   display-id ,top-left-row ,top-left-column ,bottom-right-row
   ,bottom-right-column ,display-id2 [,top-left-row2] [,top-left-column2]
   [,flags]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display from which text is to be moved. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

top-left-row
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Top left row of the rectangle of text you want to move. The top-left-row argument is the address of an unsigned longword containing the row number.

top-left-column
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Top left column of the rectangle of text you want to move. The top-left-column argument is the address of an unsigned longword containing the column number.

bottom-right-row
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Bottom right row of the rectangle of text you want to move. The bottom-right-row argument is the address of an unsigned longword containing the row number.

bottom-right-column
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Bottom right column of the rectangle of text you want to move. The bottom-right-column argument is the address of an unsigned longword containing the column number.

display-id2
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display to which the text is to be moved. The display-id2 argument is the address of an unsigned longword that contains the display identifier.

The display identifier display-id2 is returned by SMG$CREATE_VIRTUAL_DISPLAY.

top-left-row2
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Top left row of the rectangle that is the destination of the text you want to move. The optional top-left-row2 argument is the address of an unsigned longword containing the row number. If you do not specify a value for top-left-row2, the text is moved to the current virtual cursor row.

top-left-column2
OpenVMS usage:longword_unsigned
type:longword (unsigned)
access:read only
mechanism:by reference

Top left column of the rectangle that is the destination of the text you want to move. The optional top-left-column2 argument is the address of an unsigned longword containing the column number. If you do not specify a value for top-left-column2, the text is moved to the current virtual cursor column.

flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Optional bit mask that specifies the action to take when moving the specified text. The flagsargument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values:

SMG$M_TEXT_SAVEDoes not erase the text after moving.
SMG$M_TEXT_ONLYMoves the text but not the attributes.

Description

SMG$MOVE_TEXT moves a rectangle of text from one virtual display to another virtual display. You specify the rectangle you want to move with the top-left-row, top-left-column, bottom-right-row, and bottom-right-column arguments, as shown in Figure 8.32. The virtual cursor positions are not changed.
Figure 8.32. Arguments for Moving Text
Arguments for Moving Text

The rectangle of text is moved to the current virtual cursor row and column of the destination virtual display. To move the text to a different position, use the optional top-left-row2 and top-left-column2 arguments.

By default, the attributes of the first virtual display are moved and, after the rectangle of text is moved, it is erased from the first virtual display. You can use the flags argument to change those default values.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVCOLInvalid column number.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVROWInvalid row number.
SMG$_WRONUMARGWrong number of arguments.

SMG$MOVE_VIRTUAL_DISPLAY

SMG$MOVE_VIRTUAL_DISPLAY — The Move Virtual Display routine relocates a virtual display on a pasteboard and preserves the pasting order.

Format

SMG$MOVE_VIRTUAL_DISPLAY
   display-id ,pasteboard-id ,pasteboard-row ,pasteboard-column
   [,top-display-id]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display to be moved. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard on which the movement is to take place. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

pasteboard-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row of the pasteboard that is to contain row 1 of the new location of the specified virtual display. The pasteboard-row argument is the address of a signed longword that contains the row number.

pasteboard-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column of the pasteboard that is to contain column 1 of the specified virtual display. The pasteboard-column argument is the address of a signed longword that contains the column number.

top-display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the virtual display under which the moving display-id will be pasted. The top-display-id argument is the address of an unsigned longword containing the specified virtual display identifier. Note that the use of the top-display-id argument is only valid when the virtual display specified by display-id is not currently pasted and the virtual display specified by top-display-id is pasted.

Description

SMG$MOVE_VIRTUAL_DISPLAY moves a virtual display from its current position to the specified position and, if the virtual display is pasted, preserves the pasting order. If the display being moved is not currently pasted, SMG$MOVE_VIRTUAL_DISPLAY presents the user with two options. By default, SMG$MOVE_VIRTUAL_DISPLAY pastes the display at the top of the pasting order in the position specified.

If, however, the optional argument top-display-id is specified, SMG$MOVE_VIRTUAL_DISPLAY pastes the virtual display being moved under the virtual display specified by top-display-id. In this case, the virtual display specified by top-display-id must already be pasted.

Note that a display cannot be moved from one pasteboard to another. However, the pasteboard-id is required because a given virtual display may be pasted to any number of pasteboards.

Do not use this routine if the virtual display is batched.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_ILLBATFNCDisplay is being batched; illegal operation.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

Example

Refer to the Fortran example shown in the SMG$REPASTE_VIRTUAL_DISPLAY routine.

SMG$NAME_TO_KEYCODE

SMG$NAME_TO_KEYCODE — The Translate a Key Name into a Key Code routine translates the key name of a key on the keyboard into its associated key code.

Format

SMG$NAME_TO_KEYCODE key-name ,key-code

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

key-name

OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

String containing the name of the key to be translated into a key code. The key-name argument is the address of a descriptor pointing to the character string containing the key name. The key-name argument is simply the name of the key (for example, COMMA, PERIOD, KP4, and so forth).

key-code

OpenVMS usage:word_unsigned
type:word (unsigned)
access:write only
mechanism:by reference

Specifies the key code into which key-name is to be translated. The key-code argument is the address of an unsigned word that contains the key code.

The key code is returned by SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY in the word-terminator-code argument.

Description

SMG$NAME_TO_KEYCODE translates the key name of a key on the keyboard into its associated key code. This key code is the same code that is returned by the SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY routines in theword-terminator-code argument. The form of the key code returned by this routine is SMG$K_TRM_keyname. For example, if you supply the key name ENTER, the key code returned by this routine is SMG$K_TRM_ENTER.

For more information on terminator codes, see Table 3.1.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVKEYNAMInvalid key-name.

SMG$PASTE_VIRTUAL_DISPLAY

SMG$PASTE_VIRTUAL_DISPLAY — The Paste Virtual Display routine pastes a virtual display to a pasteboard.

Format

SMG$PASTE_VIRTUAL_DISPLAY
   display-id ,pasteboard-id [,pasteboard-row] [,pasteboard-column]
   [,top-display-id]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display to be pasted. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard to which the display is to be pasted. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

pasteboard-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row of the pasteboard that is to contain row 1 of the specified virtual display. The pasteboard-row argument is the address of a signed longword that contains the row number.

If pasteboard-row is omitted, the last row to which the virtual display was pasted (on any pasteboard) is used. If pasteboard-row is omitted and the virtual display was not previously pasted, then row 1 is used.

pasteboard-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column of the pasteboard that is to contain column 1 of the specified virtual display. The pasteboard-column argument is the address of a signed longword that contains the column number.

If pasteboard-column is omitted, the last column to which the virtual display was pasted (on any pasteboard) is used. If pasteboard-column is omitted and the virtual display was not previously pasted, then column 1 is used.

top-display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the virtual display under which to paste display-id. The optional top-display-id argument is the address of an unsigned longword containing this identifier. Note that the virtual display specified by top-display-id must already be pasted.

Description

SMG$PASTE_VIRTUAL_DISPLAY places a display on a pasteboard and makes the display visible, unless the optional argument top-display-id is specified. If top-display-id is specified, SMG$PASTE_VIRTUAL_DISPLAY pastes the virtual display being pasted under the virtual display specified by top-display-id. In this case, the virtual display specified by top-display-id must already be pasted.

Do not use this routine if the virtual display is batched.

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_ILLBATFNCDisplay is being batched; illegal operation.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

For an example of how to call SMG$PASTE_VIRTUAL_DISPLAY, see the Fortran example in the description of the SMG$CREATE_PASTEBOARD routine.

SMG$POP_VIRTUAL_DISPLAY

SMG$POP_VIRTUAL_DISPLAY — The Delete a Series of Virtual Displays routine deletes a specified virtual display and all displays that were pasted on the specified pasteboard on top of the specified virtual display.

Format

SMG$POP_VIRTUAL_DISPLAY display-id ,pasteboard-id

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the lowest (first) virtual display to be deleted. The display-id argument is the address of an unsigned longword that contains the display identifier. All displays that are higher in the pasting order (that is, all displays that were pasted after the specified display) are deleted as well.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the pasteboard on which the display deletions take place. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

Description

SMG$POP_VIRTUAL_DISPLAY deletes (not merely unpastes) one or more displays from the specified pasteboard, starting with the display specified and including all displays that are higher in the pasting order (that is, all displays that were pasted on top of the specified display).

Condition Values Returned

SS$_NORMALNormal successful completion.
SMG$_INVDIS_IDInvalid display-id.
SMG$_INVPAS_IDInvalid pasteboard-id.
SMG$_WRONUMARGWrong number of arguments.

SMG$PRINT_PASTEBOARD

SMG$PRINT_PASTEBOARD — The Print Pasteboard Using a Print Queue routine prints the contents of the specified pasteboard on a line printer.

Format

SMG$PRINT_PASTEBOARD pasteboard-id [,queue-name] [,copies] [,form-name]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

pasteboard-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Identifier of the pasteboard to be printed. The pasteboard-id argument is the address of an unsigned longword containing this identifier.

queue-name
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

Optional queue name. The queue-name argument is the address of a descriptor pointing to the queue name in which to enter the file. The default is SYS$PRINT.

copies
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Optional number of copies to print. The copies argument is the address of a signed longword containing this number. The default and minimum is one copy.

form-name
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

Optional name of the form to use when printing. The form-name argument is the address of a descriptor pointing to the form name. The default is "DEFAULT".

Description

SMG$PRINT_PASTEBOARD creates a file and fills it with the contents of the specified pasteboard. Once the file is filled, SMG$PRINT_PASTEBOARD submits the file to the specified print queue to be printed. If the queue-name argument is omitted, the default is SYS$PRINT. The file is deleted after printing.

Because the Screen Management Facility cannot determine the type of printer being used, it uses terminal-independent characters (plus sign [ + ], vertical bar [ | ], underscore [ _ ], and so forth) for line-drawing characters.

Condition Values Returned

SS$_NORMALNormal successful completion.
SS$_xxxxAny error status originating in the $SNDJBCW system service.
LIB$_xxxxAny condition value returned by LIB$ANALYZE_SDESC.
SMG$_ xxxxAny condition value returned by SMG$PUT_PASTEBOARD.

SMG$PUT_CHARS

SMG$PUT_CHARS — The Write Characters to a Virtual Display routine writes characters in a virtual display with the text you specify.

Format

SMG$PUT_CHARS
   display-id ,text [,start-row] [,start-column] [,flags] [,rendition-set]
   [,rendition-complement] [,character-set]

Returns

OpenVMS usage:cond_value
type:longword (unsigned)
access:write only
mechanism:by value

Arguments

display-id
OpenVMS usage:identifier
type:longword (unsigned)
access:read only
mechanism:by reference

Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

text
OpenVMS usage:char_string
type:character string
access:read only
mechanism:by descriptor

Characters to be written to the virtual display. The text argument is the address of a descriptor pointing to the character string.

start-row
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the row at which output begins. If start-row is omitted, output begins on the current row. The start-row argument is the address of a signed longword that contains the row number.

start-column
OpenVMS usage:longword_signed
type:longword (signed)
access:read only
mechanism:by reference

Specifies the column at which output begins. If start-column is omitted, output begins on the current column. The start-column argument is the address of a signed longword that contains the column number.

flags
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Optional bit mask that specifies the action to take before the specified text is output. The flags argument is the address of an unsigned longword bit mask that contains the flag. The flags argument accepts the following values:

0Does not erase line (the default).
SMG$M_ERASE_TO_EOLErases the remaining part of the line.
SMG$M_ERASE_LINEErases the entire line.
rendition-set
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINKDisplays blinking characters.
SMG$M_BOLDDisplays characters in higher-than-normal intensity.
SMG$M_REVERSEDisplays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINEDisplays underlined characters.
SMG$M_INVISIBLESpecifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement
OpenVMS usage:mask_longword
type:longword (unsigned)
access:read only
mechanism:by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complementargument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complementcomplements these attributes. If the same bit is specified in both the rendition-set and rendition-complementparameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: