Skip to main content

Using Terminal Scripts

This chapter discusses how to create and use script files for the Terminal.

Also see the next chapter, “Script Command Reference” and see the section “Learning Mode” in the chapter “Advanced Topics.”


Terminal scripts are useful on occasion, but it is usually much easier to write and use a routine, because each of the routine programming languages provides a much richer set of options.

Environment variables in processes running the local Terminal connection are available as follows:

  • Before Windows Vista, the Caché process runs as the user that is logged in to Windows and is running the Terminal program (cterm.exe).

    In these cases, all environment variables and shared drive letter designations are those defined by that user.

  • Beginning with Windows Vista, and including Windows Vista, Windows Server 2008, Windows 7, and all anticipated subsequent releases of Windows, the Caché process that serves the Terminal connection runs in the context of the user account in which the Caché control service runs.

    In these cases, the user environment variables and shared drive letter designations are those defined by the user account in which the Caché control service runs.

Starting Script Execution

Script files (with default extension .scr) are normally found in the working directory but could be anywhere.

To run a script, select File > Script or press 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 is started immediately if no switch is locking the command mode, or deferred until after a host connection is made if there is a switch.


If you edit the communications choices to a single mode, that is equivalent to locking the Terminal to a single choice and thus any script file is invoked after the host connection is made.

Pausing Script Execution

To pause the execution of a script, select File > Pause or press Alt+P. You are prompted to confirm that you want to pause the current script.

Stopping Script Execution

To stop a script, select File > Script or press Alt+S. You are prompted to confirm that you want to stop the current script.

Contents of a Script File

Script files are line oriented; there is no line-continuation convention. Each line is separate from any other. Lines beginning with a semicolon are considered comments. You can use blank lines liberally to improve readability. Normally, invalid lines are ignored. Script commands may be preceded by spaces and/or tabs.

The format for a line that contains a script command is as follows. Note that arguments are interpreted as strings or numbers:

ScriptCommand: ScriptArguments

Here ScriptCommand is one of the Terminal script commands and ScriptArguments is the argument list for that command (see details for the specific commands). Note that if script command consists of two or more words, the words of the command must be separated from each other by a single space. Also note that there is no space between the command and the colon.

Or, for a command that has no arguments:


You can use labels to define points of control transfer. A label begins with a dollar sign ($), is not case-sensitive, and can have embedded spaces. A label must appear by itself on a line.

Also see the section “Learning Mode” in the chapter “Advanced Topics.”

Script Command Summary

The following table gives the list of available script commands:

Terminal 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 the "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 communications 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

For reference information on these commands, see the later section “Script Command Reference.”

Script Command Arguments

All spaces and tabs at the beginning and end of arguments are ignored.

All numeric arguments are integers. A required numeric argument defaults 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>

This substitutes 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.


Any ASCII (extended) character except NUL (000) can be produced via <ddd> where ddd is the decimal value of the character.

Special Characters
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>

A Sample Script

The following is a sample Terminal script:

; 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

; 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:<<< Terminal Example >>><CR><LF>
; wait a second

; 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

; finished

FeedbackOpens in a new tab