Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Order Number: AA--PV6LD--TK

## April 2001

This manual documents the screen management routines contained in the SMG$ facility of the OpenVMS Run-Time Library.

Revision/Update Information: This manual supersedes the OpenVMS RTL Screen Management (SMG$) Manual, OpenVMS Alpha Version 7.1 and OpenVMS VAX Version 7.1.

Software Version: OpenVMS Alpha Version 7.3 OpenVMS VAX Version 7.3

Compaq Computer Corporation
Houston, Texas

© 2001 Compaq Computer Corporation

Compaq, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.

Compaq Ada, DECnet, DECwindows, OpenVMS, and VT are trademarks of Compaq Information Technologies Group, L.P. in the United States and other countries.

Motif, OSF, OSF/1, OSF/Motif, and Open Software Foundation are registered trademarks of The Open Group.

All other product names mentioned herein may be trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK5935

The Compaq OpenVMS documentation set is available on CD-ROM.

Contents | Index

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

## Intended Audience

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

## Document Structure

This manual is organized into two parts as follows:

- The first part of the book contains introductory chapters that provide guidelines and reference material on specific types of screen management routines. The material covered is 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.
- The SMG$ Reference Section (Part 2) provides detailed reference information on each routine in the SMG$ facility of the Run-Time Library. This information uses the documentation format described in OpenVMS Programming Concepts Manual. Routine descriptions appear in alphabetical order by routine name.

## 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 OpenVMS Programming Concepts Manual. Descriptions of other RTL facilities and their corresponding routines and usages are discussed in the following books:

- Compaq Portable Mathematics Library
- OpenVMS RTL DECtalk (DTK$) Manual1
- OpenVMS RTL Library (LIB$) Manual
- OpenVMS VAX RTL Mathematics (MTH$) Manual
- OpenVMS RTL General Purpose (OTS$) Manual
- OpenVMS RTL Parallel Processing (PPL$) Manual1
- OpenVMS RTL String Manipulation (STR$) Manual

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

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

The 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 a complete list and description of the manuals in the OpenVMS documentation set, see the OpenVMS Version 7.3 New Features and Documentation Overview Manual.

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

    http://www.openvms.compaq.com/

Note ##### 1 This manual has been archived but is available on the OpenVMS Documentation CD-ROM. ##### 2 Compaq POSIX Threads was formerly called DECthreads.

## Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet | openvmsdoc@compaq.com
Mail | Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

## How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

     http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

## Conventions

The following conventions are used in this manual:

Ctrl/ x | A 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 x | A sequence such as PF1 x x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
`[Return]` | In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
... | 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 OpenVMS directory specifications and for a substring specification in an assignment statement.
{ } | 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 text | This typeface represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
italic text | Italic text 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 TEXT | Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
    Monospace text
| Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
- | 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.
numbers | All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

## Part 1
SMG$ Tutorial Section

This part of the OpenVMS RTL Screen Management (SMG$) Manual contains introductory chapters that provide guidelines and reference material on specific types of screen management routines. The material covered is 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 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_TABLE | SMG$GET_NUMERIC_DATA
SMG$GET_TERM_DATA | SMG$INIT_TERM_TABLE
SMG$INIT_TERM_TABLE_BY_TYPE |

Table 1-2 Input Routines
SMG$ADD_KEY_DEF | SMG$CANCEL_INPUT
SMG$CREATE_KEY_TABLE | SMG$CREATE_VIRTUAL_KEYBOARD
SMG$DEFINE_KEY | SMG$DELETE_KEY_DEF
SMG$DELETE_VIRTUAL_KEYBOARD | SMG$GET_KEY_DEF
SMG$GET_KEYBOARD_ATTRIBUTES | SMG$KEYCODE_TO_NAME
SMG$LIST_KEY_DEFS | SMG$LOAD_KEY_DEFS
SMG$NAME_TO_KEYCODE | SMG$READ_COMPOSED_LINE
SMG$READ_KEYSTROKE | SMG$READ_LOCATOR
SMG$READ_STRING | SMG$READ_VERIFY
SMG$REPLACE_INPUT_LINE | SMG$RETURN_INPUT_LINE
SMG$SET_DEFAULT_STATE | SMG$SET_KEYPAD_MODE

Table 1-3 Output Routines
SMG$BEGIN_DISPLAY_UPDATE | SMG$BEGIN_PASTEBOARD_UPDATE
SMG$CHANGE_PBD_CHARACTERISTICS | SMG$CHANGE_RENDITION
SMG$CHANGE_VIEWPORT | SMG$CHANGE_VIRTUAL_DISPLAY
SMG$CHECK_FOR_OCCLUSION | SMG$CONTROL_MODE
SMG$COPY_VIRTUAL_DISPLAY | SMG$CREATE_MENU
SMG$CREATE_PASTEBOARD | SMG$CREATE_SUBPROCESS
SMG$CREATE_VIEWPORT | SMG$CREATE_VIRTUAL_DISPLAY
SMG$CURSOR_COLUMN | SMG$CURSOR_ROW
SMG$DELETE_CHARS | SMG$DELETE_LINE
SMG$DELETE_MENU | SMG$DELETE_PASTEBOARD
SMG$DELETE_SUBPROCESS | SMG$DELETE_VIEWPORT
SMG$DELETE_VIRTUAL_DISPLAY | SMG$DISABLE_BROADCAST_TRAPPING
SMG$DISABLE_UNSOLICITED_INPUT | SMG$DRAW_CHAR
SMG$DRAW_LINE | SMG$DRAW_RECTANGLE
SMG$ENABLE_UNSOLICITED_INPUT | SMG$END_DISPLAY_UPDATE
SMG$END_PASTEBOARD_UPDATE | SMG$ERASE_CHARS
SMG$ERASE_COLUMN | SMG$ERASE_DISPLAY
SMG$ERASE_LINE | SMG$ERASE_PASTEBOARD
SMG$EXECUTE_COMMAND | SMG$FIND_CURSOR_DISPLAY
SMG$FLUSH_BUFFER | SMG$FLUSH_DISPLAY_UPDATE
SMG$GET_BROADCAST_MESSAGE | SMG$GET_CHAR_AT_PHYSICAL_CURSOR
SMG$GET_DISPLAY_ATTR | SMG$GET_PASTEBOARD_ATTRIBUTES
SMG$GET_PASTING_INFO | SMG$GET_VIEWPORT_CHAR
SMG$HOME_CURSOR | SMG$INSERT_CHARS
SMG$INSERT_LINE | SMG$INVALIDATE_DISPLAY
SMG$LABEL_BORDER | SMG$LIST_PASTEBOARD_ORDER
SMG$LIST_PASTING_ORDER | SMG$LOAD_VIRTUAL_DISPLAY
SMG$MOVE_TEXT | SMG$MOVE_VIRTUAL_DISPLAY
SMG$PASTE_VIRTUAL_DISPLAY | SMG$POP_VIRTUAL_DISPLAY
SMG$PRINT_PASTEBOARD | SMG$PUT_CHARS
SMG$PUT_CHARS_HIGHWIDE | SMG$PUT_CHARS_MULTI
SMG$PUT_CHARS_WIDE | SMG$PUT_HELP_TEXT
SMG$PUT_LINE | SMG$PUT_LINE_HIGHWIDE
SMG$PUT_LINE_MULTI | SMG$PUT_LINE_WIDE
SMG$PUT_PASTEBOARD | SMG$PUT_STATUS_LINE
SMG$READ_FROM_DISPLAY | SMG$REMOVE_LINE
SMG$REPAINT_LINE | SMG$REPAINT_SCREEN
SMG$REPASTE_VIRTUAL_DISPLAY | SMG$RESTORE_PHYSICAL_SCREEN
SMG$RETURN_CURSOR_POS | SMG$RING_BELL
SMG$SAVE_PHYSICAL_SCREEN | SMG$SAVE_VIRTUAL_DISPLAY
SMG$SCROLL_DISPLAY_AREA | SMG$SCROLL_VIEWPORT
SMG$SELECT_FROM_MENU | SMG$SET_BROADCAST_TRAPPING
SMG$SET_CURSOR_ABS | SMG$SET_CURSOR_MODE
SMG$SET_CURSOR_REL | SMG$SET_DISPLAY_SCROLL_REGION
SMG$SET_OUT_OF_BAND_ASTS | SMG$SET_PHYSICAL_CURSOR
SMG$SET_TERM_CHARACTERISTICS | SMG$SNAPSHOT
SMG$SNAPSHOT_TO_PRINTER | SMG$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 Compaq GKS or Compaq 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.

Next | Contents | Index

| privacy and legal statement |
5935PRO.HTML