Order Number: AA-PXHDB-TE
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/Hanyu Alpha Version 8.2
Hewlett-Packard Company Palo Alto, California
© Copyright 2005 Hewlett-Packard Development Company, L.P.
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 |
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).
This manual is intended for system and application programmers who want to call the Run-Time Library routines.
This manual is organized into two parts as follows:
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:
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.
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:
|
|
.
. . |
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.
Chinese Screen Management Facility supports the following terminals:
Table 1 shows the character set which each terminal supports.
| Character Set | VT382-D |
|---|---|
| ASCII | Yes |
| DEC Hanyu | Yes |
| DEC Special Graphics | Yes |
| DEC Supplemental | Yes |
| ISO Latin-1 | Yes |
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.
| 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 | |
| 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 |
| 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 supports 4-byte input and output in the suppress leading code mode only. The display terminal must be set in the suppress leading code mode to display Chinese characters correctly. Chinese SMG does not automatically set up the display terminal to the suppress leading code mode. Users need to set up the display terminal in the suppress leading code mode by themselves beforehand. As a result of the 4-byte suppress leading code support, the suppress leading code length of a text may be shorter or equal to its physical length. |
The Chinese Screen Management Facility provides two important services.
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. |
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.
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.
| Next | Contents |