[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

OpenVMS/Hanzi RTL Chinese Screen Management (SMG$) Manual

Order Number: BA322-90017

May 2005

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

Revision/Update Information: This document supersedes the VMS RTL Chinese SMG$ Manual Version 5.5.

Software Version: OpenVMS/Hanzi Version 8.2 I64 OpenVMS/Hanzi Version 7.3-2 Alpha

Hewlett-Packard Company Palo Alto, California

Confidential computer software. Valid license from HP 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.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Printed in Singapore.

ZK5935

Contents

Preface

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

Intended Audience

This manual is intended for system and application programmers who want to call the Run-Time Library routines.

Document Structure

This manual is organized into two parts as follows:

The introductory chapters provide guidelines and reference material on specific types of Chinese 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 Chinese Screen Management Facility.
Chapter 3 describes Chinese screen management routines used to perform input from a virtual keyboard.
Chapter 4 discusses the Chinese Screen Management Facility's advanced features.
Chapter 5 discusses a method of supporting foreign terminals.
Chapter 6 discusses some recommended methods for using the Chinese Screen Management Facility for developing new programs.
Chapter 7 contains examples demonstrating how to call some SMG$ routines from major OpenVMS languages.
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.

Associated Documents

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

DPML, Digital Portable Mathematics Library
OpenVMS RTL DECtalk (DTK$) Manual
OpenVMS RTL Library (LIB$) Manual
OpenVMS RTL Mathematics (MTH$) Manual
OpenVMS RTL General Purpose (OTS$) Manual
OpenVMS RTL Parallel Processing (PPL$) Manual
OpenVMS RTL Screen Management (SMG$) Manual
OpenVMS RTL String Manipulation (STR$) Manual

Guide to DECthreads contains guidelines and reference information for DECthreads, Digital's Multithreading Run-Time Library.

Application programmers using any programming language can refer to 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. Additional information may also be found 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 Overview of OpenVMS Documentation.

Conventions

In this manual, "OpenVMS I64" means the HP OpenVMS I64 operating system, "OpenVMS Alpha" means the HP OpenVMS Alpha operating system, "OpenVMS VAX" means the HP OpenVMS VAX operating system, and "OpenVMS" means the HP OpenVMS I64 operating system, the HP OpenVMS Alpha operating system and the HP OpenVMS VAX operating system.

The following conventions are used to identify information specific to OpenVMS Alpha or to OpenVMS VAX:
The Alpha icon denotes the beginning of information specific to OpenVMS Alpha.

The VAX icon denotes the beginning of information specific to OpenVMS VAX.

The diamond symbol denotes the end of a section of information specific to OpenVMS Alpha or to OpenVMS VAX.

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 indicates that you must first press and release the key labeled PF1, then press and release another key or a pointing device button.
GOLD x	A sequence such as GOLD x indicates that you must first press and release the key defined GOLD, then press and release another key. 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.)
...	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 format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.
[]	In 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 format descriptions, braces surround a required choice of options; you must choose one of the options listed.
boldface text	Boldface text represents the introduction of a new term or the name of an argument, an attribute, or a reason. Boldface text is also used to show user input in Bookreader versions of the manual.
italic text	Italic text emphasizes important information, indicates variables, and indicates complete titles of manuals. Italic text also represents information that can vary in system messages (for example, Internal error number), command lines (for example, /PRODUCER= name), and command parameters in text.
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, the name of a file protection code, or the abbreviation for a system privilege.
-	A hyphen in code examples indicates that additional arguments to the request are provided on the line that follows.
numbers	All numbers in the text are assumed to be decimal, unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Other conventions used in the documentation of Run-Time Library routines are described in the OpenVMS Programming Interfaces: Calling a System Routine.

Hardware

Chinese Screen Management Facility supports the following terminals:

VT82
VT382-C

Table 1 shows the character set which each terminal supports.

**Table 1 Character set supported by Chinese terminal**
Character Set	VT82	VT382-C
ASCII	Yes	Yes
DEC Hanzi	Yes	Yes
DEC Special Graphics	Yes	Yes
DEC Supplemental	No	Yes
ISO Latin-1	No	Yes

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

This manual discusses the Run-Time Library routines that perform terminal-independent functions. The most important aspect of the Chinese Screen Management Facility is that user programs are entirely separated 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. The following lists contain all the Chinese 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**
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**
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_STRING
SMG$REPLACE_INPUT_LINE	SMG$RETURN_INPUT_LINE
SMG$SET_DEFAULT_STATE	SMG$SET_KEYPAD_MODE

**Table 1-3 Output Routines**
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$GET_BROADCAST_MESSAGE
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$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_STATUS_LINE
SMG$READ_FROM_DISPLAY	SMG$REMOVE_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$UNPASTE_VIRTUAL_DISPLAY

The Chinese Screen Management Facility provides two important services.

Terminal Independence
The Chinese 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 Chinese screen management routines accomplish the action by emulating it in software. Similarly, the Chinese 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 Chinese 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 DEC GKS or VAX FMS.

Ease of Composition
The Chinese 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 Chinese 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.

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, but a pasteboard may be larger or smaller than the physical screen. There can be only one pasteboard for each output device.

Note

The Chinese Screen Management Facility does not support an RMS file and a printer for the output device.

You create a pasteboard by calling the SMG$CREATE_PASTEBOARD routine and specifying as an argument the physical device to be associated with the pasteboard. 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, you use the pasteboard-id to specify the physical terminal screen on which to paste a virtual display. SMG$CREATE_PASTEBOARD also returns as output arguments the numbers of rows and columns available on the associated device. You can use this information to create a virtual display of the size of the physical screen. (Virtual displays are discussed in the next section.)

It is useful to 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

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