Caché MultiValue Terminal Independence
Terminal Definition
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

The TERMDEFS File
Each account (namespace) in MultiValue will have an F pointer in the VOC called TERMDEFS which points to a database-wide file, ^%MV.TERMDEFS. Each entry in this global contains a simple text file which defines the characteristics of a terminal (both output and input characteristics). The global node name should be uppercase.
The layout of these text files is one or more lines, delimited by CR, CR/LF or @AM ($C(254)). The lines have the same attributes as that presented by the "terminfo" command available on most UNIX® systems. Indeed many of the supplied terminal definitions come from UNIX® declarations. For example, the global ^%MV.TERMDEFS("VT100") might look like this:
#
vt100|vt100-s|dec vt100 (w/advanced video),
am, msgr, xenl, xon,
cols#80, it#8, lines#24, vt#3,
acsc=``aaffggjjkkllmmnnooppqqrrssttuuvvwwxxyyzz{{||}}~~,
bel=^G, blink=\E[5m$<2>, bold=\E[1m$<2>,
clear=\E[H\E[J$<50>, cr=^M, csr=\E[%i%p1%d;%p2%dr,
cub=\E[%p1%dD, cub1=^H, cud=\E[%p1%dB, cud1=^J,
cuf=\E[%p1%dC, cuf1=\E[C$<2>,
cup=\E[%i%p1%d;%p2%dH$<5>, cuu=\E[%p1%dA,
cuu1=\E[A$<2>, ed=\E[J$<50>, el=\E[K$<3>, el1=\E[1K$<3>,
enacs=\E(B\E)0, home=\E[H, ht=^I, hts=\EH, ind=^J, ka1=\EOq,
ka3=\EOs, kb2=\EOr, kbs=^H, kc1=\EOp, kc3=\EOn, kcub1=\EOD,
kcud1=\EOB, kcuf1=\EOC, kcuu1=\EOA, kent=\EOM, kf0=\EOy,
kf1=\EOP, kf10=\EOx, kf2=\EOQ, kf3=\EOR, kf4=\EOS, kf5=\EOt,
kf6=\EOu, kf7=\EOv, kf8=\EOl, kf9=\EOw, rc=\E8,
mc4=\E[4i,mc5=\E[5i,
rev=\E[7m$<2>, ri=\EM$<5>, rmacs=^O, rmam=\E[?7l,
rmkx=\E[?1l\E>, rmso=\E[m$<2>, rmul=\E[m$<2>,
rs2=\E>\E[?3l\E[?4l\E[?5l\E[?7h\E[?8h, sc=\E7,
sgr=\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p1%p3%|%t;7%;%?%p4%t;5%;m%?%p9%t\016%e\017%;$<2>,
sgr0=\E[m\017$<2>, smacs=^N, smam=\E[?7h, smkx=\E[?1h\E=,
smso=\E[7m$<2>, smul=\E[4m$<2>, tbc=\E[3g,
This example was taken from a UNIX® definition of a vt100 terminal. It shows all the characteristics of the terminal. Not all of these are needed by Caché, and those that are not relevant are ignored. This makes importing terminal definitions relatively painless, since no editing is required.
The pad characters, denoted by $<nn>, are for really really old terminals and hark from the days before flow control to serial devices. This information is ignored.
In the above example, \E denotes the escape character $c(27), non-displayable characters denoted by ^A through ^Z being $c(1) through $c(26). If a string is not a constant and requires parameters to determine the eventual string (for example moving the cursor to a particular row and column) these are denoted by %, as described in the terminfo manual pages on a UNIX® system.
The first line shown in the example is a comment. The second line is set of fields delimited by the | character, the last field simply being a description, the other fields being the name of the terminals this defines. This allows synonym terminals to be defined by the same source. Hence a single source in the TERMDEFS file may create one or more compiled entries in the TERMCMP file.
Note:
If you upgrade your Caché installation, the TERMDEFS and the TERMCAP files are overwritten. Be sure to keep backups of these files.
Adding a New Terminal Definition
Create the source definition for the terminal. Caché uses a standard source as output by the "infocmp" command on UNIX® systems. Therefore, the usual way of adding a new terminal definition, assuming it already works on a UNIX® system, is as follows:
Note:
The item id of the item in the TERMDEFS file is uppercase and is the name of the terminal type. The name MUST be uppercase, although when you refer to the terminal type with the TERM command it is not case-sensitive.
Modifying an Existing Terminal Definition
A developer may use the ED command to edit an existing entry in the TERMDEFS file and then run the COMPILE.TERM command.
Note:
You should save copies of any changes to TERMDEFS because they will be undone any time you upgrade your Caché version.
Deleting a Terminal Definition
COMPILE.TERM compiles the specified TERMDEFS and adds them to the existing TERMCMP file so they are available for use, but it does not clear prior TERMCMP entries. If you delete entries from TERMDEFS and don't want the terminal definitions to be available, particularly if you don't want to have them listed in CHOOSE.TERM, you must delete the specific terminal definitions that you don't want from TERMCMP after you have compiled TERMDEFS and know you have the working definitions available.
You can directly delete entries from TERMCMP. Individual TERMDEFS entries can generate multiple TERMCMP entries. For example, the second line of 'wy150' is: wy120|wyse120|wy150|wyse150|WY120|WYSE120|WY150|WYSE150|Wyse 120 and 150, This is a '|' delimited list of TERMCMP names to generate from this definition, except the last item, which is the Terminal Description shown by CHOOSE.TERM.
Some TERMDEFS contain an entry at the bottom. For example, 'wy60' line 36 is: .termtype=w. The 'w' is up-cased and becomes the Short Name option in CHOOSE.TERM.
The COMPILE.TERM Command
The data for terminal definitions exists in two globals. The %MV.TERMDEFS global contains the source for the definition. The %MV.TERMCMP global contains the compiled definition used by the runtime. To compile the sources from %MV.TERMDEFS to the compiled version in %MV.TERMCMP issue the COMPILE.TERM command. COMPILE.TERM no arguments compiles all the definitions in the %MV.TERMDEFS file. For example,
USER: COMPILE.TERM
123 terminal definitions compiled
USER:
The Default Terminal Type
By default, the type of a terminal is CACHE. Users can change current terminal type using the TERM command, for example,
USER: TERM vt100
USER: ; PRINT SYSTEM(7)
vt100
USER: TERM VT100
USER: ; PRINT SYSTEM(7)
VT100
The TERM Environment Variable
The TERM command also sets the TERM environment variable. When MV starts, if the terminal specified cannot be loaded, the MultiValue shell will
  1. Display an error message to that effect;
  2. Attempt to load the terminal type, CACHE;
  3. If successful, display a message that the terminal type is set to CACHE. If unsuccessful (because, for example, it has been removed from the TERMDEFS file), the terminal type will be set to UNKNOWN and an error message indicating this will be displayed instead.
Supported TERMINFO Manipulation Codes
Cursor addressing and other strings requiring parameters are described by a parameterized string capability. For example, to address the cursor, the “cup” capability is supported. It expects using two parameters: the row and column to move the cursor to. (For more info, see the UNIX terminfo(5) man page.
This parameter mechanism uses a stack and special % codes to manipulate it. Typically, a sequence may push one or more parameters onto the stack and manipulate them in some way. The Caché termdefs file supports the following subset of the UNIX capability:
Code Description
One or more digits Push the integer onto the stack
%% Add “%” to the output string
%p[1-9] Push the designated parameter onto the stack
%c Pop an integer from the stack and append it to the output string as a character
%d Pop an integer from the stack and print its decimal value to the output string
%i Add 1 to the first two parameters (p1 and p2). This is used for cursor positioning; it allows for some terminals that start their definitions for column and row with position 0, and other terminals that start with position 1.
\E Append the ESCape character ($CHAR(27)) to the output string
%F Caché extension: equivalent to “%p1%d”
%G Caché extension: equivalent to “%p2%d”
%H Caché extension: equivalent to “%p1%d;%p2%d”
%I Caché extension: equivalent to “"%p1%{64}%+%c”
%J Caché extension: equivalent to “"%p2%{10}%/%{6}%*%p2%+%c”
\| Append the newline character ($CHAR(10)) to the output string
\'x' Push the character represented by the escape sequence onto the stack (the representation is given in octal)
%+, %-, %/ , %* , %m Arithmetic operations on the top two positions of the stack: addition, subtraction, division, multiplication, and modulo, respectively.
%&, %|, %^ Bitwise operations: AND, OR, and negation, respectively
%=, %>, %< Comparison operations: equal to, greater than, and less than, respectively
%A, %O Logical operations: AND and OR
%? … %t … %e … Conditional: If … then … else …
Let us assume we want to move the cursor to column 3, row 6 (column and row numbers start at 0, so column 3 is actually the 4th column and row 6 is the 7th row). The cursor function will be called with two parameters, 3 and 6, and the string
cup=\E[%i%p2%d;%p1%dH$<5>
is interpreted as follows:
Code Interpretation
\E Append the ESCape character ($CHAR(27)) to the output string
[ Append the character, “[”, to the output string
%i Add 1 to the first two parameters; 3 and 6 become 4 and 7, respectively
%p2 Push parameter 2 (a 7) onto the stack
%d Print the top of the stack (the integer 7) to the output string
; Append the character, “;”, to the output string
%p1 Push parameter 1 (a 4) onto the stack
%d Print the top of the stack (the integer 4) to the output string
H Append the character, “H”, to the output string
$<5> Add 5 units of pad character. Caché ignores this sequence. It was used for very old character-oriented terminals running over an asynchronous link without flow control.
So the resulting control sequence sent to the terminal to move the cursor to column 3, row 6 (zero-based) consists of the ESCape character followed by the characters “[7;4H”.