This article is intended to give a description of the features and functions of the Caché TERMINAL as well as offer basic information on its use. It includes the following topics:
General Characteristics
Caché Terminal was designed to work with Caché applications. It emulates many of the functions of a Digital Equipment Corporation VT320 terminal. It can also emulate an ANSI standard terminal and (for input only) a DTM console.
Caché employs a modular design that permits different communications modes to be run through multiple instances simultaneously. Further, new communications modes can be added incrementally without replacing the entire software collection.
Caché uses Winsock as its communications stack. Winsock is a network programming interface for Microsoft Windows which is based on the "socket" paradigm popularized in the Berkeley Software Distribution (BSD). The host entry can be either from the local file, an IP address, or, if the Winsock implementation has access to a name server, a general host name. The hostname may be followed by an optional #nnn to specify a non-standard port number.
Errors reported from this communications mode are the names of the Winsock error codes. For example, "WSAECONNREFUSED" means the connection was refused.
Note:
Large input buffers may defer the action of keys that attempt to stop the input flow such as Ctrl-C or Ctrl-S. This is also dependent on processor and connection speed. A special effort was made to respond to keystrokes BEFORE host input.
When sized, the main window attempts to keep the most current line (from the host) visible on the bottom. Of course, the user may scroll back to previous lines. Whenever active text arrives, Caché Terminal moves the window back to the newly arrived text. This version supports a scroll back buffer of approximately 375 lines in a 24 x 80 configuration.
Caché Terminal Menus
As a Windows application, Caché Terminal has the usual menu items at the top of its windows. They are described here together with their sub-menus.
File Menu
File commands are used to control log files and script files as well as printing text files.
Logging (Alt+L)
This command starts the logging of a session. You specify the name of the file in which you wish to capture the data. Only the output from a connection is logged (independent of the current wrap mode). If a log file is currently active, you are asked if you want to stop logging to the currently active file.
By default, log files are appended to rather than created anew. The user can select to overwrite the log file by clicking on the Overwrite button. The default log file name and location is taken from the registry key:
HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  ComDlg32
                     OpenSaveMRU
                        <xxx>
where <xxx> is log unless you are learning a script; in that case, the information will be taken from scr.
Script (Alt+S)
This command starts the execution of a script file. If a script file is currently running, use this command to stop it. See the description of script commands for more information on script files.
Print Log
This command prints log files from the working directory, but will also print any ASCII file. It does no special processing except to try to be reasonable in processing formfeed characters. While printing, mouse and keyboard input is locked out of the main window and a cancel dialog box appears. Printing is done in draft mode.
Printer Setup
This command permits the selection and setup of a printer for Caché Terminal.
Print Screen
This command send the contents of the Caché Terminal screen to the default printer.
Exit
This command causes this copy of Caché Terminal to exit, closing any open files. It can also be done with Alt+F4. If this copy of Caché Terminal is a "clone", then it will exit on its own when the communications channel is closed.
Edit Menu
Edit commands support Clipboard control, re-initialization of the window display, as well as selection of items customized by the individual user.
Copy (Ctrl+Ins)
This command copies selected text to the Windows Clipboard according to the standard Windows paradigm.
If copied text includes a line boundary, it is saved on the clipboard as a carriage return and a linefeed. You may not want to paste linefeeds. See the Edit User Settings commands.
If the host has a mouse request outstanding and you wish to do a local cut and paste, depress the Control key while selecting the region, the mouse action will not be reported to the host.
Paste (Shift+Ins)
This command transmits the current text from the clipboard to the host. The text will become visible in the Terminal window unless echoing has been disabled. When you press the right mouse button, a menu appears with the following options for paste:
Caché Terminal can often paste data faster than a host can accept it. See the Edit User Settings for settings to control the speed of pasting. Also, linefeeds can be discarded during a paste command.
Reset
This command resets the margins, scroll region and other processing on the current page and causes Caché Terminal to repaint the window. It is not normally needed.
Erase (Ctrl+Del)
This command re-initializes the Caché Terminal window, erasing all data, and resetting the scroll-back region to zero.
Font
This command permits the user to select a font style appropriate to their monitor and resolution. Whenever Caché Terminal is switched to a different size screen, it will attempt to use the preselected font.
Note:
If you choose a setting for font size that would expand the window beyond the borders of your screen, Terminal will automatically resize both screen and font to the largest size available.
Colors
This command permits selection of default foreground and background colors for Caché Terminal. Selecting "Apply" changes ONLY the current copy. "Save" does not change the current copy but saves the color information for new instances of Caché Terminal.
Adjusting the colors allows changes of any color from the expected ANSI-named colors to whatever the display board will deliver. These colors will be saved along with the foreground and background choices. The default colors can be selected with the "Default" button.
User Keys
User Keys are selected via Alt+Shift+F1 through Alt+Shift+F10. Selecting "Ok+Save" updates the current instance and saves the key sequences for future instances of Caché Terminal.
You may include non-printable characters via <nnn>, where nnn is the decimal equivalent of the character. You may also use one of <CR>, <F10>, <F7>, <DO>, <TAB>, <LF>, <ESC>, <CSI>, <NL> (= <CR><LF>).
Further, <P1>, <P2>, etc. name command line parameters.
Note:
There are known problems with the User Keys facility in this version of Caché. For more complete, up-to-date information, please contact the InterSystems Worldwide Response Center.
User Settings
User Settings control both the current setup and initial values of various parameters used by Caché Terminal. The simple settings are:
Setting Description
Wrap Automatic wrapping at right hand column
<- Key Set to have <X> key send Ctrl+H rather than Delete
Application Enable Application Mode keypad
Force Numeric Pad Force standard PC keypad
Disable Special Ident Do not send special Terminal ID
Disable Mouse Report Do not sent mouse reports
Enable Fast Paint Enable fast paint mode
Paste LF Set to send LF from clipboard (along with CR)
Paste Size Number of bytes to send from clipboard at once
Paste Wait Number of milliseconds to wait between bursts
Pass Xoff Through Let remote host handle XOFF/XON.
Pass 8-bit Characters Correctly display 8-bit characters.
Some systems cannot accept data as fast as Caché Terminal can send it. Thus, the Paste Burst Size (in bytes): determines how much to send at once and the Paste Pause Time (in msec): determines the pause time between transmissions. If Paste Burst Size or Paste Pause Time is less than 1, the entire clipboard is sent at once.
Window Size
The window size can be selected. The maximum number of columns is 132 and the maximum number of rows is 64. There are buttons to rapidly select commonly-used sizes for both rows and columns.
As changes are made, the number of scrollback lines and "pages" available are instantly updated. Selecting "Apply" updates the current instance and "Save" saves the values for future instances of Caché Terminal.
Changing the window causes an erasure of all current data in both the current display page and all back pages. Further, if there is a font selected for that size, it will also be selected.
Connect Menu
Connect commands support the operation of the Telnet modules.
Note:
If Terminal is started with the /console= control argument, this menu item does not appear.
Host (Alt+O)
This command permits the connection of Caché Terminal to a remote host. Selecting this item brings up a dialog box to obtain the address of the desired host.
Send Break (Alt+B)
This command will send a break over the communications channel.
Disconnect
If the Terminal has been previously connected to a host, selecting this item disconnects the terminal from the host. If an attempt to connect to a remote host is underway but has not completed, this item terminates the attempt.
List of available hosts
Below the Disconnect menu choice is a numbered list of known hosts for convenience.
Help
Help allows selection of various types of help (including this help).
Help Menu
Selecting this menu item displays this material.
About Caché Terminal
This command displays the version number of this copy of Caché Terminal.
Script Files
Script files are useful for replacing tedious typing tasks. Through the use of scripts, significant control over Caché Terminal is possible.
Starting Script Files
Script files (with default extension .SCR) are normally found in the working directory but could be located anywhere.
Scripts are invoked either as the first argument of the command line or via the menu function File/Script... (which can also be started by the hotkey Alt+S). A standard Windows file lookup box is presented and the selection of a script is made.
If a script is given as an argument on a command line, it will be started immediately if there is no switch locking the command mode, or deferred until after a host connection is made if there is a switch.
Note:
Editing the communications choices to a single mode is equivalent to locking Caché Terminal to a single choice and thus any script file is invoked after the host connection is made.
Stopping Script Files
To stop a script, simply select the File/Script... entry once again and a question will be asked if you wish to stop the current script. Answer "Yes" and then Cancel the new script selection.
Script File Format
Script files are line oriented; there is no line-continuation convention. Each line is separate from any other. Lines beginning with a semi-colon are considered comments. Blank lines may be liberally used to improve readability. Normally, invalid lines are ignored. Script commands may be preceded by spaces and/or tabs.
The general format for a line containing a script command is:
<ScriptCommand>: <ScriptArguments>
that is, the ScriptCommand is separated from its ScriptArguments by a colon. Arguments to script commands are strings or numbers. If the command has no arguments, the colon that would separate the command from its arguments must be omitted.
Labels are used to define points of control transfer. They begin with a dollar-sign ($), are not case-sensitive, and can have embedded spaces. Labels must appear by themselves on a line.
Note:
If a <ScriptCommand> consists of two or more words, the words of the command must be separated from each other by a single space.
If the colon is present after a <ScriptCommand>, it must immediately follow the last word of the command.
Script Command Table
The following table gives the list of available script commands:
Command Action
break Transmit a break for those communications devices that support it
call script Exit the current script and start another
case match Indicate if "wait for" string must match in case
closelog Close a log file
connect Force a host connection if not connected
debug Enable/disable debugging for scripts
disconnect Force a disconnect if connected
display Send text to the display
echo Turn on/off echo of incoming characters
execute Execute a windows program
exit Exit the script
goto Transfer control to another place in the script
if empty Transfer control if last test string was empty
key_starttime Simulate Key timing start
key_stoptime Simulate Key timing stop
key_timer Turn Key Timing on and off
logfile Start a log file
multiwait for Wait for any of several strings from the communications device
notify Display a dialog box and wait for user response
on error Indicate label to branch to if timer fires
pause Pause the script
return Return from a subroutine in the script file
send Send text to the comm device
subroutine Call a subroutine in the script file
terminate Exit the emulator entirely
test Build a string to be tested
timer Control the timer for "wait for"
title Set the window title
wait for Wait for a particular string from the communications device
Script Command Arguments
Script commands accept string or numeric arguments depending on the command. All spaces and tabs at the beginning and end of arguments are ignored.
All numeric arguments are integer valued. A required numeric argument will default to 0 if not provided. Additionally, OFF is equivalent to 0 and ON is equivalent to 1.
Strings are simply the concatenation of all data on a line after the command (with the exception of the leading and trailing white space). Quotation marks are not needed. Additionally, parameter substitution is accomplished with the use of one of the following:
<P1>, <P2>, ..., <Pn>
will substitute the n-th command line parameter in place of <Pn>.
To ease operation, certain ASCII characters have equivalent shortcut representations as shown in the following table.
Note:
Any ASCII (extended) character except NUL (000) can be produced via <ddd> where ddd is the decimal value of the character.
Character(s) Interpretation Transmitted Sequence
<CR> Carriage Return <13>
<F10> F10 key <27>[21-
<F7> F7 key <27>[18-
<DO> Do key <27>[29-
<TAB> Tab key <9>
<LF> Line Feed <10>
<ESC> Escape key <27>
<DCS> Device Control String Introducer <144>
<ST> Stop Device Control String <156>
<EMU> Start of Extended Emulator command <144>i
<NL> Newline <CR><LF>
<CSI> Control String Introducer <155>
Individual Script Command Descriptions
This section contains a list of the individual script commands and their use.
Break
This command sends a "break" for those communications nodes that support a break. Otherwise, it acts as a "no-op." It takes no arguments.
Usage example:
    break
Call Script
The call script command starts running a script. If a script is executing when this command is executed, the running script is terminated before starting the new script.
Usage example:
    call script: login fred <p3>
This command will stop the current script (if one is running) and start another called login.scr. The first parameter in login will be "fred", and the second will be whatever is in the third parameter of the current script file (the one making the call). The default extension is assumed to be ".SCR". The current working directory is searched first for an instance of login.scr.
Case Match
The case match command enables/disables exact case matching in the wait for command.
Usage example:
    case match: off
This permits matching of strings even if the individual characters differ from one another in case. The default for this switch is on.
Closelog
This command closes a currently open log file. If no log file has been opened, this command has no effect.
Usage example:
    logfile: mydirect.log
    send: dir *.*/FULL<CR>
    wait for: <NL>$
    closelog
Connect
This command will open a dialog box to initiate a connection to a remote host.
Usage example:
    connect
Debug
The debug command is useful for catching invalid script commands. Normally, Caché Terminal ignores invalid script commands. By enabling the debug mode, the first part of an invalid command will appear in a message box requiring operator attention.
Usage example:
    debug: on
Disconnect
This command is the equivalent of the Disconnect choice on the Connect/Host menu, if Caché Terminal is currently connected to a host. If it is not connected, the command does nothing.
Usage example:
    disconnect
Display
The display command outputs data to your screen. It is not sent to the communications device.
Usage example:
    display: <CSI>H<CSI>J<LF>Here are the choices for today:
When this command is executed, it will home the cursor, clear the window, advance a line and write the text "Here are the choices for today:", leaving the cursor after the end of the text.
Echo
The echo command enables/disables displayed output to the window and logfile. This is useful if work is to be done and it is desirable that it not appear on the screen or in the logfile.
Usage example:
    echo: off
    on error: $Login Failed
    timer: 50
    wait for: Name:
    send: <p1><CR>
    wait for: Password:
    send: <p2><CR>
    wait for: <NL>$
    echo: on
    Notify: Login is complete
    display: <CSI>H<CSI>J
    send: <CR>
    goto $Process

$Login Failed
    echo: on
    notify: Login failed.
    exit

$Process
    ;processing begins
This example hides the login sequence using a name and password supplied as the first two script parameters, respectively. If the login succeeds, processing begins at the indicated label. If it fails, the script displays a dialog box indicating the failure and then exits when the user clicks "Ok".
Execute
This command launches a Windows program with a SHOW attribute for its window.
Usage example:
    execute: notepad.exe myfile.not
The command will execute the windows notepad program and open the file, myfile.not, inside the application. Notice that you could do the following:
    logfile: mydat.lst
    echo: off
    send: dir *.dat/full
    wait for: <NL>$
    closelog
    echo: on
    execute: notepad mydat.lst
Note:
No test is made to see if the program actually starts and no wait is done for its completion.
Exit
The exit command is used to exit the script. A script will normally exit if it "runs off the bottom", but you may wish to exit if some event (say a login) does not occur.
Usage example:
    on error: $byebye
    timer: 40
    wait for: event:
    goto: $Got event

$byebye:
    notify: Did not find event prompt, exiting script
    exit

$Got event:
    timer: 0
    ; more commands
GoTo
The goto command is used to transfer control to another place in the script file. This is useful for managing control flow for looping, and in response to time-out branching.
Usage example:
    on error: $Not There
    timer: 30
    wait for: abc<CR>
    goto: $Got It

$Not There:
    ;failed to see it, send Ctrl+C
    send: <3>
    goto: $bad

$Got It:
    ;turn timer off because we got abc<CR>
    timer: 0

    ;more commands ...
If Empty
The if empty command causes a branch to the given label if the last test command found an empty string.
Usage example:
    test: <p1>
    if empty: $No First Arg
The first of these two commands determines if the first parameter provided in the command line is missing or empty. The second branches to the label "$No First Arg" if this is the case.
Key_Starttime
This command is used to start the timing of a "key" sequence. It takes a single numeric argument. If the argument is zero, the statistics are accumulated when ENTER is typed. Otherwise, it is accumulated when F10 is pressed.
Usage example:
    key_starttime: 0
Timing can be stopped with the key_stoptime command.
Key_Stoptime
This command stops a timing and accumulates statistics, if timing is currently active.
Usage example:
    key_starttime: 0
    wait for: <esc>[14;22H
    key_stoptime
Key_Timer
The key_timer command starts/stops the data collection of key timing information. Alternatively, the timer can be started/stopped with the special key, Alt+Shift+T.
Usage example:
    key_timer: on
    ; rest of your script commands
    key_timer: off
A file, KEYTIMER.LOG is constructed in the system manager directory that contains a histogram of key timings. Only one such timing sequence can be used since it does not append to the current statistics file but overwrites it.
Note:
If timings are to be driven exclusively from script files, you must use <CR> and <F10> in place of <13> and “<27>[21-”, respectively.
Logfile
This command starts the collection of received data in the log file specified. If there is currently a log file active, it is quietly stopped. Use the closelog command to stop the logging.
Usage example:
    logfile: mydirect.log
    send: dir *.*/FULL<CR>
    wait for: <NL>$
    closelog
The default directory is the system manager directory.
Log files are normally opened for append; that is, if they already exist, new data will be added on the end.
MultiWait For
The multiwait for command synchronizes the script file with the host. Processing is suspended until the data that arrives from the host matches one of several strings given in the argument.
Usage example:
    multiwait for:  =USER>=***ERROR,=DONE
This command example causes the script file to wait (maybe forever!) until any one of three strings of characters arrives. The first non-blank character of the argument (in this instance, the equal sign) is treated as the “separator” character which breaks up the argument into substrings. So this command causes the example script to wait until one of the sequences “USER>”, “***ERROR” or “DONE” arrives.
A timer can be used to break out of a multiwait for command.
See the case match command to turn exact case matching on or off.
Because a case match command may have only a single sub-string argument, the following two script commands are identical in function:
    multiwait for:  =USER>
    wait for: USER>
Notify
The notify command presents a Windows message box to the user and waits until the "OK" button is depressed before continuing. It can be used to inform the user of important events.
Usage example:
    notify: Ready to send commands...
    send: copy *.lst backup:*.lst<CR>
    send: delete *.lst;*
Note:
This box is "modal", that is, cannot be interrupted except by the user.
On Error
The on error command provides a means to specify the label for script commands to be executed if the timer expires (normally while waiting for text to arrive).
Usage example:
Pause
This command is used to pause a running script for a number of tenths of seconds.
Usage example:
    pause: 30
The example pauses execution of the script for three seconds. A pause with 0 is equivalent to and indefinite pause which will require another Alt+P to resume the script processing.
Return
The return command is used with the subroutine command to return to the place in the script from which the subroutine was called.
Usage example:
Send
The send command simulates typed data that is sent to the current connected host.
Usage example:
    send:   1<cr>2<cr>A1234<F10><32>
This command is equivalent to typing:
Notice the <32> is the only way to send a leading or trailing space since they are removed by the command interpreter.
Subroutine
A subroutine is useful if repetitive commands are used in a script. It saves both memory and the possible need to invent many different labels. This command should be used with a return command.
Usage example:
    subroutine: $Send It Again
    ; some other processing
    exit

$Send It Again:
    send: <F7>Q
    on error: $skip
    timer: 30
    wait for: [22;5H
    timer: 0
    return

$skip:
    send: <3>
    ; note on error still set to $skip
    timer: 30
    wait for: function:
    timer: 0
    send: <CR>
    exit
Note:
The subroutine stack holds 16 addresses. An attempt to nest subroutine invocations deeper than that will result in the failure of the script.
Terminate
This command tells Caché Terminal to exit back to Windows. Any open files are closed, extra windows are removed, and the connections are closed.
Usage example:
    terminate
Test
The test command is used to see if a parameter or window property is non-empty. The command is used in conjunction with the if empty command.
Usage example:
Timer
The timer command sets a timer to be used in conjunction with the wait for command. If the text being looked for is never received, or is missed due to timing or case match issues, timer is the only way to interrupt a wait for and continue execution of the script.
Usage example:
    timer 100
Its argument is the number of tenths of a second to wait. The example sets a timer for ten seconds. See the example in the goto command for another example.
Title
The title command is used to change the window title to whatever string is required.
Usage example:
    title: This is my window
This can also be done remotely via the extended emulator commands.
Wait For
The wait for command synchronizes the script file with data that arrives from the host.
Usage example:
    wait for:  USER>
This command example causes the script file to wait (maybe forever!) until the precise string of characters "USER>" arrives. This particular sequence is the default prompt from Caché Terminal when in the USER namespace. So this command can be used to wait until Caché Terminal is ready for more input.
A timer can be used to break out of a wait for command.
See the case match command to turn exact case matching on or off.
Extended Keyboard Features
Key Mappings
Caché Terminal supports application keyboard mode for the extended keyboard as follows:
Key Mapped Value
Num Lock PF1
Keypad-divide PF2
Keypad-times PF3
Keypad-minus PF4
Keypad-plus Keypad-comma
Shift+Keypad-plus Keypad-minus
F1, F2, F3, F4 PF1, PF2, PF3, PF4 (respectively)
Shift+F1 ... Shift+F10 F11 ... F20 (respectively)
The keypad cluster of the extended keyboard is mapped this way:
Key Mapped Value
Insert Insert Here
Home Find
Page Up Prev Screen
Delete Remove
End Select
Page Down Next Screen
The Pause key acts as a single XON/XOFF toggle key.
Keyboard Functions
To speed the use of Caché Terminal, several "Hot Keys" have been defined to permit quick access to features normally accessible through menus. See the individual Menu Commands for information on these keys.
Topic Summary
Key Timing This is useful for determination of performance of a host system under various load conditions. The key timing is enabled/disabled via Alt+Shift+T. The output of a timing "run" is a file called KEYTIMER.LOG which can be found in the System manager directory.
Learn Mode Learn mode is a feature that permits rapid prototyping of script files. Learn mode is enabled/disabled via Alt+Shift+L. When enabled, and logging is active, rather than simply capturing all incoming characters, the "log" file becomes a sequence of script wait for and send commands. This file can "almost" be played back. The wait for commands show up to 16 characters preceding the "sent" data.
Spy Mode Spy mode is useful for DLL applications that are utilizing the communications capabilities of Caché Terminal. It is enabled/disabled via Alt+Shift+S and is mentioned here only as information should that key be typed. It is not for general use.
Pause Mode Pause mode is used to pause a script file manually. It is enabled/disabled via Alt+P. It can also be activated with the pause command with a argument of 0.
PC Bridge & Troll The simple transfer protocols Bridge & Troll are supported by Caché Terminal. When the application requests, enter Alt+Shift+F and select either Bridge (to download) or Troll (to upload).
DDE Overview
DDE is an acronym for Dynamic Data Exchange, an interprocess communication (IPC) system built into the Macintosh, Windows, and other operating systems. DDE enables two running applications to share the same data. For example, DDE makes it possible to insert a spreadsheet chart into a document created with a word processor. Whenever the spreadsheet data changes, the chart in the document changes accordingly. Although the DDE mechanism is still used by many applications, it is being supplanted by OLE (Object Linking and Embedding, a compound document standard developed by Microsoft Corporation), which provides greater control over shared data.
Caché Terminal supports DDE (Dynamic Data Exchange) links to permit other applications to utilize its communications ability to talk to a remote host.
There are three (non-System) topics supported by Caché Terminal. The discussion of each topic assumes that the user has knowledge of how to use DDE. The topics are:
Note:
A windows task has no way to discriminate between multiple instances of Caché Terminal when it comes to using DDE! It is most useful when only one copy of Caché Terminal is running.
DDE Layout Connections
Caché Terminal supports DDE requests for what could be considered as static information through the Layout topic.
Item Meaning of returned value
Column The number of columns of the window.
Row The number of rows of the window.
hWnd The decimal equivalent of the main window handle.
Connected A null string if there is no connection, otherwise the equivalent of the title string "mode: node"
Read A 1 if the last received character was a CTRL/A. This can be enabled for every read with "set terminal/script" on VMS systems. Its use is detection of the end of screen painting.
Script A 1 if a script is currently running, otherwise 0.
Title The title of the window.
DDE Screen Connections
Caché Terminal supports DDE requests for screen data through the Screen topic. Currently, one POKE command is available to select which part of a screen line is desired.
Item Meaning of returned value
Cursor The current cursor position in the form row;col.
Line The current line (without a CR LF).
LeftLine The left part of the current line up to but not including the character under the cursor.
RightLine The right part of the current line including the character under the cursor.
All The entire screen, each line is delimited by CR LF.
Piece The currently selected piece of a screen line (without a CR LF).
Note:
The item "Piece" can be POKEd with a string of the form "RnnCmmLpp" to cause the Piece request to retrieve (at most) pp characters on the screen line nn beginning with column mm. The top left corner of the screen is row 1, column 1.
DDE Message Connections
Caché Terminal supports DDE requests for data communications through the Message topic. These are implemented with DDE POKE commands.
Item Meaning of returned value
Send The DDE message value is sent to the host if a connection is active.
Display The DDE message value is sent to the "screen" as if it were received from the host.
An Example Script
This section gives an example of a script session run on the local machine and invoked via the “batch” facility of Windows 2000.
Note:
The various versions of Microsoft Windows interpret the characters caret (^) and percent (%) differently from one another. A specific line of text may also be interpreted differently depending on whether it is typed by the user into a “batch” window (DOS prompt) or read as input in a batch script.
The following table gives the different input sequences required to represent the line
    cterm /console=cn_ap:cache[USER] ^%D
on the various operating systems.
OS Environment Rule Input Sequence
Windows NT
Windows 2000
Windows XP
DOS prompt Double caret (^) characters cterm /console=cn_ap:cache[USER] ^^%D
Windows NT
Windows 2000
Windows XP
Batch file
Double caret (^) characters
Double percent (%) characters
cterm /console=cn_ap:cache[USER] ^^%%D
Windows 9x
Windows ME
DOS prompt
or
Batch file
Double percent (%) characters cterm /console=cn_ap:cache[USER] ^%%D
The Batch Command Line
The Terminal application can be invoked through a “DOS” command line using the Windows 2000 program, cmd.exe. The general form of the command line is:
    cterm <Arg1> <Arg2> ... <ArgN> <ScriptFilePath>
where:
Item Meaning
cterm The invocation of the Terminal application. If the Windows environment variable, PATH, has been set to include the location of the Caché binaries, then the command name may be given “cterm” or “cterm.exe”. Otherwise, a full or partial pathname must be used. For a default installation of Caché, it can be found in the directory, C:\CacheSys\Bin.
<ArgM> One of the control arguments for Terminal (described separately).
<ScriptFilePath> The location of the script file to be interpreted by the Terminal application.
Control Arguments
There are several arguments that modify the starting environment for the Terminal session. Some of these are reserved for internal use and/or debugging; they will not be described here. The ones useful to most invocations are:
/console=<ConnectString>
This argument is required. It specifies both the type of connection and the additional data needed to make the connection. There are two types of interest: TELNET connections and local console applications.
/console=cn_iptcp:<HostAddr>
This specifies the target system that the terminal is to interact with over a TELNET connection. One of the more common uses is to run a script on the local machine. In this case, you specify the local machine IP address and port as HostAddr. For example,
    cterm /console=cn_iptcp:127.0.0.1[23]
/console=cn_ap:<Configuration>[<NameSpace>]:<Routine>
User applications may be run in the terminal by specifying the configuration for the application. Assuming that the following appears as a line in a batch (.BAT) file executed by a Windows 2000 system,
    cterm /console=cn_ap:cache[USER]:^^%%D
starts a terminal session and, if needed, a version of Caché from the “cache” configuration in the USER namespace. When this has been done successfully, the terminal runs the ^%D routine which prints out the current date. When ^%D returns, the terminal session is closed.
Configurations correspond to the names of the Caché parameter files in the System Manager directory without their suffix. The default parameter file is cache.cpf.
The namespace name is optional. If it is not supplied, the default namespace (%SYS) is used.
The colon after “cn_ap” and the brackets enclosing the namespace name are required. The colon after the “]” is required only if a routine name is given; otherwise, it is ommitted.
/size=RowsxCols
This argument gives the initial size of the Terminal “screen” in terms of rows and columns. Each of Rows and Cols must be an unsigned integer. The “x” which separates them is required as shown. No spaces are permitted in the control argument.
The allowed ranges for Rows and Cols are:
/pos=(X,Y)
This argument gives the initial origin of the Terminal “screen” in the display device window in terms of device pixels. Both X and Y must be unsigned integers. The parentheses around the pair and the comma separator are required. No spaces are permitted in the control argument.
Note:
It is possible to place a window outside the displayed area by choices for X and Y that are larger than the size of the display device.
/ppos=(Xpct,Ypct)
This argument gives the initial origin of the Terminal “screen” in the display device window in terms of a percentage of the display area. Both Xpct and Ypct must be unsigned integers. The parentheses around the pair and the comma separator are required. No spaces are permitted in the control argument.
The allowed ranges for Xpct and Ypct are:
That is, the window origin is not allowed to be placed above and to the left of the device origin, or more than 40% down or across the display device.
Script #1 - Get Process Info (Batch)
This is an example of using the basic debugging routine, ^%STACK, to display information about the current user and Terminal process. Assuming that the script commands are stored in C:\TestScript.scr, the user runs the example by typing into a DOS command window:
C:\CacheSys\Bin\cterm.exe /console=cn_iptcp:127.0.0.1[23] C:\TestScript.scr
The script itself looks like this:
;;;
;;; Script for Cache Terminal Example
;;; 
; initialization
; turn match off to make comparisons more lenient
case match: off

; wait for the terminal to initialize 
; and ask for our identification
echo: off
wait for:Username
send: SYS<CR>
wait for:Password
send: XXX<CR>
title: Terminal Example
echo: on

; log everything in a log
logfile: C:\TermExample.log
; wait a second
pause:10

; display a header to let the user know we are ready
; you need <CR><LF> because "display" does not 
; have a prompt to advance to another line
display:<CR><LF>
display:------------------------------<CR><LF>
display:<<< Cache Terminal Example >>><CR><LF>
display:------------------------------<CR><LF>
; wait a second
pause:10

; switch to the USER namespace
send: znspace "USER"<CR>
wait for:USER>

; display some basic information about the system
; Use the debugging routine to do so
send: Do ^%STACK<CR>
wait for: action:

; have it outline our options
send: ?<CR>
wait for: action:

; wait 5 seconds for user to absorb
pause: 50

; ask for the basic process info
send: *s
pause: 50
send: <CR>
wait for: action:

; wait another 10 seconds
pause: 100

; finish the session
send: <CR>

; close the log file
closelog

; finished
terminate
Example #2 - Get Process Info (Interactive)
The same routine, ^%STACK, as in the previous example can be invoked in a terminal session via the Windows 2000 DOS command:
    C:\CacheSys\Bin\cterm.exe /console=cn_ap:cache[USER]:^^%STACK
The user can manually provide the responses that the script supplied in that example. The terminal window will be closed when the user replies to the prompt, “Stack Display Action:” by pressing the ENTER key.
Example #3 - Manually Connecting To A Host
This example starts an instance of Terminal and then manually connects it to the TELNET port on the local host to enable a console session. The example assumes that the default userid and password are available.
Start Terminal from a DOS Window (Windows 2000 assumed).
    C:\CacheSys\Bin\cterm.exe
Then do the following:
If everything is in order, you will then see the prompt, “%SYS>” indicating that you are connected and have been placed in the %SYS namespace. You can replicate what you did in Example 2 by issuing the command,
    DO ^%STACK
in response to the prompt, and then responding with “*S” to the request for a display action. Exit the ^%STACK routine by pressing ENTER in response to its prompt.
You may terminate the session by select Disconnect from the Connect menu. If you wish to terminate this instance of Terminal, select the Close box for the window.