 |
OpenVMS RTL Screen Management (SMG$) Manual
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.
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-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.
|
