Script Command Reference
This topic provides reference information for the script commands available for the Terminal application, for use when you create Terminal scripts.
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.
Sends a break for those communications nodes that support a break. Otherwise, it does nothing. It has no arguments. Usage example:
Starts running a script. If a script is executing when this command is executed, the Terminal application terminates that script before starting the new script. Usage example:
call script: login fred <p3>
This example stops the current script (if one is running) and starts another called login.scr. The first parameter in the sample script (login.scr) is fred. The second parameter is whatever is in the third parameter of the current script file (the one making the call). The default file extension is assumed to be .scr. The current working directory is searched first for an instance of login.scr.
Enables or disables exact case matching in the wait for command. Usage example:
By disabling exact case matching, you can match strings even if the individual characters differ from one another in case. The default for this switch is on.
Closes the currently open log file, if any. Usage example:
send: dir *.*/FULL<CR>
wait for: <NL>$
Opens a dialog box to initiate a connection to a remote host. Usage example:
Enables debug mode, which traps invalid script commands, which the Terminal application usually ignores. When you enable the debug mode, the first part of an invalid command appears in a message box requiring operator attention. Usage example:
Disconnects from the host. If the Terminal application is not connected, the command does nothing. Usage example:
Writes 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 example is executed, it moves the cursor to the home position, clears the window, advances by one line, and writes the text Here are the choices for today: and leaves the cursor after the end of the text.
Enables or disables displayed output to the window and log file. This is useful if you need to hide output (because it is uninformative to the user, for example). For an example, see wait for.
Launches a Windows program with a SHOW attribute for its window. Usage example:
execute: notepad.exe myfile.not
This example executes the Windows Notepad program and opens the file myfile.not inside that application. Notice that you could do the following:
send: dir *.dat/full
wait for: <NL>$
execute: notepad mydat.lst
No test is made to see if the program actually starts and no wait is done for its completion.
Exits the script. A script normally exits when it reaches the end of its last line, but you may wish to exit if some event (say a login) does not occur. Usage example:
on error: $byebye
wait for: event:
goto: $Got event
notify: Did not find event prompt, exiting script
; more commands
Transfers control to another place in the script file. This is useful for managing control flow for looping, and in response to timeout branching. Usage example:
on error: $Not There
wait for: abc<CR>
goto: $Got It
;failed to see it, send Ctrl+C
;turn timer off because we got abc<CR>
;more commands ...
Causes a branch to the given label if the last test command found an empty string. Usage example:
if empty: $No First Arg
The first command determines if the first parameter provided in the command line is missing or empty. The second command branches to the label $No First Arg if this is the case.
Starts the timing of a key sequence. It takes a single numeric argument. If the argument is zero, the statistics are accumulated when you press Enter. Otherwise, statistics are accumulated when you press F10. Usage example:
To stop timing, use the key_stoptime command.
Stops a timing and accumulates statistics, if timing is currently active. Usage example:
wait for: <esc>[14;22H
Starts or stops the data collection of key timing information. Alternatively, you can start or stop the timer with Alt+Shift+T. Usage example:
; rest of your script commands
A file (KEYTIMER.LOG) is constructed in the system manager’s directory that contains a histogram of key timings. You can use only one such timing sequence because it does not append to the current statistics file but overwrites it.
To drive timings exclusively from a script file, you must use <CR> and <F10> in place of <13> and <27>[21-, respectively.
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:
send: dir *.*/FULL<CR>
wait for: <NL>$
The default directory is the directory in which the script resides. It can be changed by supplying a full pathname.
Log files are normally opened for overwrite; that is, if they already exist, new data replaces what is already there.
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 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 equals sign) is treated as the delimiter that breaks up the argument into substrings. So this command causes the example script to wait until one of the following sequences arrives:
You can use a timer to break out of this command.
See the case match command to turn exact case matching on or off.
Because a case match command may have only a single substring argument, the following two script commands are identical in function:
multiwait for: =USER>
wait for: USER>
Displays a Windows message box and waits until the user presses OK. You can use this for messages to the user who runs the script. Usage example:
notify: Ready to send commands...
send: copy *.lst backup:*.lst<CR>
send: delete *.lst;*
This box is modal and cannot be interrupted except by the user.
Establishes the target label for the implied goto that is executed if a timer expires (normally while waiting for text to arrive). To be strictly correct, you should use this command before using timer, although in practice the order might not matter.
For examples, see wait for, exit, goto, and subroutine.
Also see the timer command.
Pauses a running script for a number of tenths of seconds. Usage example:
This example pauses execution of the script for three seconds. If the argument is 0, that is equivalent to an indefinite pause; to resume from an indefinite pause, use Alt+P.
Used with the subroutine command to return to the place in the script from which the subroutine was called. See the subroutine command for an example.
Simulates typed data that is sent to the currently connected host. Usage example:
send: set $namespace="%SYS"<CR>
This line changes the namespace to %SYS. The <CR> at the end is necessary because the send command does not implicitly add a carriage return.
Another usage example is as follows:
This command is equivalent to typing the following, in sequence:
Notice that <32> is the only way to send a leading or trailing space. Those characters are removed by the command interpreter if typed normally.
It is best practice to include the wait for command after each send command. The wait for command provides the ability to synchronize later commands in the script with input from the Terminal application. The Terminal script mechanism sends commands one-after-the-next without regard to the input returning from InterSystems IRIS® data platform except when a wait for command is encountered.
If you do not include the wait for command after each send command, and you are generating a log file, the log file will not include information for the later send commands.
Useful if repetitive commands are used in a script. It saves both memory and the possible need to invent many different labels. Use this command with a return command. Usage example:
subroutine: $Send It Again
; some other processing
$Send It Again:
on error: $skip
wait for: [22;5H
; note on error still set to $skip
wait for: function:
The subroutine stack holds 16 addresses. If you try to nest subroutine invocations deeper than that, the script fails.
Tells the Terminal application to exit back to Windows. Any open files are closed, extra windows are removed, and the connections are closed. Usage example:
Tests if a parameter or window property is non-empty. The command is used in conjunction with the if empty command. See the if empty command for an example.
Sets a timer to use with the wait for command. The timer command performs a Windows SetTimer() command. When the timer fires, the script processor goes to the label specified by on error (if any). The script exits immediately if no label has been specified by on error.
The 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.
To switch off a timer, use the following:
For an example of timer in context, see wait for.
Sets the Terminal application window title to the specified string. Usage example:
You can also set the title remotely via the extended emulator commands.
Synchronizes the script file with data that arrives from the host. Usage example:
This 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 the Terminal application when in the USER namespace. This means that you can use this command to wait until the Terminal application is ready for more input.
You can use timer to break out of a 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. When you use timer, you can specify a label to receive the flow if the timer expires; see on error. If wait for finds the text it is seeking, it kills the timer and clears any label set by on error. Usage example:
on error: $Failed Login
wait for: Name:
wait for: Password:
wait for: <NL>$
Notify: Login is complete
notify: Login failed.
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 you select OK.
The wait for command may or may not consider the case of the text, depending on whether and how you have used the case match command.