|
HP OpenVMS Systems Documentation |
|
OpenVMS/Hanzi RTL Chinese Screen Management (SMG$) Manual
Because string capability fields often include nonprinting characters, the following substitutions are used to make it easy to insert these characters in a capability string. Use the special character to represent the nonprinting character.
Thus to create a capability string that contains an escape character, you simply insert a dollar sign at that position. To create a capability string that contains a control character, prefix the character with a circumflex (^). For example:
If you want to use a character in a capability string and have its normal ASCII value, place an underscore in front of it. (For example, "_$" results in a single dollar sign rather than an underscore followed by an escape character). The following characters must be preceded by an underscore in order to be treated as normal ASCII text:
Note that the Chinese Screen Management Facility automatically invokes the graphics mode needed to display the line-drawing character set (for example, the bottom_t_char, top_t_char, and so on). However, if you call the foreign terminal routines directly, you are responsible for invoking the required graphics mode. Padding (for example, with null characters) must sometimes be added to a terminal command to allow the terminal sufficient time to execute the command. The amount of padding needed depends on the terminal and the baud rate. The pad character capability field is included only for future expansion and has no function in this release; padding is the responsibility of the user.
When the foreign terminal support routines are called directly, many of
the string capability fields use arguments whose values must be
specified at run time. Further, some arguments also require that
arithmetic operations be performed when values are substituted for
arguments. The following sections describe argument substitution and
arithmetic operations.
It is frequently necessary to substitute values in a terminal command string. For example, setting a scrolling region or moving the cursor ten columns to the right requires the run-time substitution of a value; these values cannot be stored in the TERMTABLE terminal definition. TERMTABLE provides for string substitution by accepting !UL, an $FAO style directive. The !UL directive signifies that a value is to be inserted at that point: the TERMTABLE interface routine is to accept an unsigned longword and convert it to ASCII digits before substituting it in the capability field string (and thus in the returned command string). For example:
The string defined for the SET_CURSOR_ABS function must have values
substituted for the two !UL directives; these values specify the row
and column number at which to set the cursor. You specify these
run-time arguments as an optional longword vector argument to the
SMG$GET_TERM_DATA routine. The first entry in the vector contains the
number of arguments that follow. Thus, the first entry is 2, the second
entry is the desired row number, and the third entry is the desired
column number. The SMG$GET_TERM_DATA routine converts the first
optional data item (the second item in the vector) to ASCII digits and
substitutes an ASCII value for the first !UL directive; it converts the
second optional data item and substitutes it for the second !UL
directive, and so on.
In addition to argument substitution, terminal command sequences may also require arithmetic operations. To perform an argument substitution and arithmetic operation, the TERMTABLE entry requires a different scheme than for argument conversion and substitution. To perform both argument substitution and arithmetic operations, you use an opening parenthesis, a percent sign (to indicate the point of substitution), an arithmetic operator, an operand, and a closing parenthesis. For example:
This example shows the string that directly positions the cursor on a VT52, where a bias must be added to the row and column numbers. Values to be substituted in the expression are passed with the SMG$GET_TERM_DATA routine, in the same way as for argument substitution alone. The percent sign is always followed by an integer that indicates the order in which arguments should be substituted. The following table summarizes the characters used in arithmetic operations:
Note that longword integers should be sufficient to express screen coordinates. Expressions are evaluated from left to right; there is no operator precedence.
Spaces between items are not significant; they may be used wherever
desired to improve readability. Capability strings are limited to 128
bytes in length.
The source code for the database is an ASCII file named TERMTABLE.TXT. This file contains an entry for each type of terminal. Each entry lists a terminal's capabilities and other device-specific information, such as initialization sequences and screen size; a TERMTABLE entry can span more than one record in the file. A terminal definition can be added by editing the TERMTABLE.TXT file; TERMTABLE.TXT must then be reprocessed by running SYS$SYSTEM:SMGBLDTRM.EXE. TERMTABLE.TXT can be created with any text editor. A TERMTABLE entry consists of a terminal name, followed by any number of capability fields and their values (see Section 5.2 for more information about capability fields). Although TERMTABLE.TXT must be formatted for compilation, capability names are descriptive and can be easily understood. Terminal names must be unique; for example, if more than one definition is needed for a foreign terminal, then a second name must be used. When a TERMTABLE routine first searches for a terminal entry, it tries to find TERMTABLE.EXE in the area logically named TERM$TABLOC. If the specified terminal entry is not found there, the routine then searches for TERMTABLE.EXE in SYS$SYSTEM. If you want to use a terminal definition that differs from the system definition for that terminal, you can create a private copy of TERMTABLE.TXT and TERMTABLE.EXE. You can then define a single terminal with a definition that is different from the one in SYS$SYSTEM:TERMTABLE.EXE and still use the rest of the standard system definitions. The format of a TERMTABLE entry is as follows:
Note that the TERMTABLE.TXT file allows you to include REQUIRE directives. The REQUIRE directive lets you include separate source files in the TERMTABLE.TXT file. Its format is as follows:
In the above format, "filespec" is a valid OpenVMS file
specification.
For the set cursor sequence listed for a VT300-series (MYVT300), the string returned depends on the values provided in the argument vector supplied with the call to the SMG$GET_TERM_DATA routine. For example, to position the cursor to row 3 and column 12, you supply these longword values as the second and third entries in the vector (the first entry is the number of values that follow). The SMG$GET_TERM_DATA routine converts these longword values into their ASCII values and inserts the converted values into the string returned at the point of the respective !UL directives. For the set cursor sequence listed for a VT52 (MYVT52), the string returned depends not on argument substitution, but on an arithmetic operation (because the VT52 requires biasing). The arithmetic operator is used to add 31(decimal) to the row and column numbers supplied in entries 2 and 3 of the argument vector for the SMG$GET_TERM_DATA routine. The INIT_STRING field in MYVT300 is included to point out that the parenthesis is normally treated as a special character indicating an arithmetic expression. A parenthesis must be preceded by an underscore in order to be interpreted as a normal text character. Thus the string "$_(B" yields ESC(B, a command that designates the ASCII character set into G0. The ERASE_WHOLE_DISPLAY sequence for MYVT52 shows that it may be necessary to combine sequences in order to provide a certain function. The VT52 does not have a command that erases the entire screen. However, you can erase the entire screen by homing the cursor and then using the command that erases from the current position to the end of the screen. The following BASIC example program uses the LIB$GETDVI routine to ascertain the type of terminal associated with SYS$OUTPUT. The program then uses the foreign terminal routines to place the cursor at the twelfth screen line and to erase to the end of the screen. Note that the program detects whether these capabilities are available for the terminal and displays an error message if they are not.
5.5 Creating TERMTABLE.EXEAccessing an ASCII file for each screen program is inefficient because the ASCII text must be processed as binary information before it can be returned as a string ready for the terminal. To avoid paying the price of this processing at the start of every image, TERMTABLE.TXT is "precompiled" into the required binary format. A screen application then gets its terminal sequences from the precompiled binary capabilities file.
You compile TERMTABLE.TXT by running the
The compiled terminal capabilities are stored as a table in a file which is mapped as a permanent global section. Thus, user programs map to the global section rather than having their own copies of the capabilities data. If a user compiles a private TERMTABLE.TXT from his or her own directory, the interface routines access it by mapping it as a temporary section. TERMTABLE interface routines look for a definition in the temporary section before looking in the system's permanent global section. Note that system managers may want to coordinate terminal definitions so that nonstandard definitions are confined to a user's private area. Most users do not have the privilege to create a permanent global section. A short program, SYS$SYSTEM:SMGMAPTRM.EXE, that maps the compiled TERMTABLE as a global section, is part of the standard OpenVMS startup procedure. In order to map an updated TERMTABLE.EXE as the global section, the existing global section must first be deleted. Deleting the global section while the system is active may cause a user's program to fail; therefore the system must be rebooted in order to make an updated TERMTABLE.EXE the default.
To reduce compiling time and the size of the resulting global section,
the terminal definitions in SYS$SYSTEM:TERMTABLE.TXT should be kept to
a minimum. Only the types of terminals that are actually attached to
the computer system should be defined.
The tables in Section 5.2 show whether or not the Chinese Screen Management Facility can request a particular capability string. Some functions, such as wide characters or line drawing, will be requested only if the user calls the Chinese screen management routines which output wide text or draw lines. If all you want to do is write normal text to the screen, only the following set of fields needs to be defined:
SMG operation is more efficient if the following optional capabilities are also provided:
If you do not include ERASE_TO_END_DISPLAY, ERASE_TO_END_LINE, or SET_SCROLLING_REGION, the Chinese Screen Management Facility will insert blanks to perform these functions. However, inserting blanks is a slower operation. Similarly, hardware scrolling also improves output speed; if scrolling is not available, the Chinese Screen Management Facility must rewrite the entire screen. The Chinese Screen Management Facility uses the ASCII character set. If your terminal has a line-drawing character set, you should define the line drawing characters (bottom_t_char, horizontal_bar, and so forth). If line-drawing characters are not defined, SMG uses normal ASCII characters to draw borders. The Chinese Screen Management Facility also relies on the terminal characteristics maintained by the terminal driver. You can change these characteristics with the DCL SET TERMINAL command. For example, if you type SET TERMINAL/NOTAB, then the Chinese Screen Management Facility does not send tabs to the terminal.
|