Document revision date: 30 March 2001

Order Number: AA--PV6LD--TK

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

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$) Manual¹
• OpenVMS RTL Library (LIB$) Manual
• OpenVMS VAX RTL Mathematics (MTH$) Manual
• OpenVMS RTL General Purpose (OTS$) Manual
• OpenVMS RTL Parallel Processing (PPL$) Manual¹
• OpenVMS RTL String Manipulation (STR$) Manual

The Guide to the POSIX Threads Library contains guidelines and reference information for Compaq POSIX Threads², 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/

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.

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

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.

	privacy and legal statement
5935PRO.HTML