Creating and Using Terminal Scripts
This topic discusses how to create and use script files for the Terminal application.
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.
The user environment variables and shared drive letter designations are those defined by the user account in which the InterSystems IRIS® data platform control service runs.
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:
ScriptCommand
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 Learning Mode.
Script Command Summary
The following table gives the list of available script commands, with links to the reference content for more details:
| 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 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.
| 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> |
Sample Script
The following is a sample 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: set $namespace="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
Starting a Script
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 application to a single choice and thus any script file is invoked after the host connection is made.
Pausing a Script
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 a Script
To stop a script, select File > Script or press Alt+S. You are prompted to confirm that you want to stop the current script.
