Script Command Reference
This chapter provides reference information for the Terminal script commands.
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.
break
Sends a break for those communications nodes that support a break. Otherwise, it does nothing. It has no arguments. Usage example:
break
call script
Starts running a script. If a script is executing when this command is executed, the Terminal 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.
case match
Enables or disables exact case matching in the wait for command. Usage example:
case match: off
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.
closelog
Closes the currently open log file, if any. Usage example:
logfile: mydirect.log
send: dir *.*/FULL<CR>
wait for: <NL>$
closelog
connect
Opens a dialog box to initiate a connection to a remote host. Usage example:
connect
debug
Enables debug mode, which traps invalid script commands, which the Terminal 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:
debug: on
disconnect
Disconnects from the host. If the Terminal is not connected, the command does nothing. Usage example:
disconnect
display
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.
echo
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.
execute
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:
logfile: mydat.lst
echo: off
send: dir *.dat/full
wait for: <NL>$
closelog
echo: on
execute: notepad mydat.lst
No test is made to see if the program actually starts and no wait is done for its completion.
exit
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
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
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
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
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 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.
key_starttime
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:
key_starttime: 0
To stop timing, use the key_stoptime command.
key_stoptime
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
Starts or stops the data collection of key timing information. Alternatively, you can start or stop the timer with 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’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.
logfile
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 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.
multiwait for
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:
USER>
***ERROR,
DONE
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>
notify
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.
on error
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.
pause
Pauses a running script for a number of tenths of seconds. Usage example:
pause: 30
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.
return
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.
send
Simulates typed data (such as Caché syntax) that is sent to the currently connected host. Usage example:
send: zn "DOCBOOK" <CR>
This line changes the namespace to DOCBOOK. The <CR> at the end is necessary because the send command does not implicitly add a carriage return.
Another usage example is as follows:
send: 1<cr>2<cr>A1234<F10><32>
This command is equivalent to typing the following, in sequence:
-
The character 1
-
The carriage-return key
-
The character 2
-
The carriage-return key
-
The string of characters A1234
-
The F10 key
-
A single space character
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. The Terminal script mechanism sends commands one-after-the-next without regard to the input returning from Caché 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.
subroutine
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
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
The subroutine stack holds 16 addresses. If you try to nest subroutine invocations deeper than that, the script fails.
terminate
Tells the Terminal to exit back to Windows. Any open files are closed, extra windows are removed, and the connections are closed. Usage example:
terminate
test
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.
timer
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.
Usage example:
timer: 100
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:
timer: 0
title
Sets the Terminal window title to the specified string. Usage example:
title: This is my window
You can also set the title remotely via the extended emulator commands.
wait for
Synchronizes the script file with data that arrives from the host. Usage example:
wait for: USER>
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 when in the USER namespace. This means that you can use this command to wait until the Terminal 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:
echo: off
on error: $Failed Login
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
$Failed Login:
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 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.