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:
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.
Script Command Summary
The following table gives the list of available script commands:
|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.
|<DCS>||Device control string introducer||<144>|
|<ST>||Stop device control string||<156>|
|<EMU>||Start of extended emulator command||<144>i|
|<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 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:<<< 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