OpenVMS RTL Screen Management (SMG$) Manual

Updated: 11 December 1998

Order Number: AA--PV6LB--TK

November 1996

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 AXP Version 7.0 and OpenVMS VAX Version 7.0.

Software Version: OpenVMS Alpha Version 7.1 OpenVMS VAX Version 7.1

Digital Equipment Corporation Maynard, Massachusetts

November 1996

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.

Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Digital Equipment Corporation: AXP, Bookreader, DEC, DECdirect, DECnet, DECterm, DECwindows, Digital, Digital Fortran, Digital GKS, FMS, LA50, OpenVMS, OpenVMS Cluster, ReGIS, VAX, VAX Ada, VAX BASIC, VAX BLISS-32, VAX C, VAX COBOL, VAX DIBOL, VAX DOCUMENT, VAX FMS, VAX MACRO, VAX Pascal, VAXcluster, VMS, VMScluster, VT, and the DIGITAL logo.

The following are third-party trademarks:

Adobe, Adobe Illustrator, Display POSTSCRIPT, and POSTSCRIPT are registered trademarks of Adobe Systems Incorporated.

Motif, OSF, OSF/1, OSF/Motif, and Open Software Foundation are registered trademarks of the Open Software Foundation, Inc.

All other trademarks and registered trademarks are the property of their respective holders.

ZK5935

The 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 is covered 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 perform 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 contained in the SMG$ facility of the Run-Time Library. This information is presented using the documentation format described in OpenVMS Programming Interfaces: Calling a System Routine. Routine descriptions appear in alphabetical order by routine name.

Reader's Comments

Digital welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08

Mail OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha.

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also 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 or
GOLD x A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button.
GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.

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

... Horizontal ellipsis points in examples indicate 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.

.
.
. Vertical ellipsis points indicate 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, if you choose more than one option, you must enclose the choices in parentheses.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

{ } In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.

text style This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
This style is also used to show user input in Bookreader versions of the manual.

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 device-name contains up to five alphanumeric characters).

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 type 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 is covered 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 perform 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 performing input directly from a physical keyboard, user programs perform 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 assist you in designing, composing, and keeping 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 these routines are primarily intended for use with video terminals, they can also be used 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 the routines.

Table 1-2 lists the SMG$ input routines; Chapter 3 discusses the routines.

Table 1-3 lists the SMG$ output routines; Chapter 2 discusses the 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-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-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

**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 without concern for the type of terminal being used. 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 being used.

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 Digital GKS or VAX FMS.

Ease of composition
The screen management routines assist you in composing 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 without regard to 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.

Contents

Index

Legal

 
5935PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

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 or GOLD x	A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button. GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.
`[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.)
...	Horizontal ellipsis points in examples indicate 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.
. . .	Vertical ellipsis points indicate 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, if you choose more than one option, you must enclose the choices in parentheses.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
{ }	In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.
text style	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. This style is also used to show user input in Bookreader versions of the manual.
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 device-name contains up to five alphanumeric characters).
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 type	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.