Skip to main content
Previous sectionNext section

Script Command Reference

This chapter provides reference information for the Terminal script commands.

Note:

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
Copy code to clipboard

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>
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

connect

Opens a dialog box to initiate a connection to a remote host. Usage example:

    connect
Copy code to clipboard

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
Copy code to clipboard

disconnect

Disconnects from the host. If the Terminal is not connected, the command does nothing. Usage example:

    disconnect
Copy code to clipboard

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:
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard
Note:

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
Copy code to clipboard

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 ...
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

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.

Note:

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
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

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>
Copy code to clipboard

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;*
Copy code to clipboard
Note:

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
Copy code to clipboard

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 that is sent to the currently connected host. Usage example:

    send: set $namespace="%SYS"<CR>
Copy code to clipboard

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:

    send: 1<cr>2<cr>A1234<F10><32>
Copy code to clipboard

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.

Important:

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 InterSystems IRIS 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
Copy code to clipboard
Note:

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
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

For an example of timer in context, see wait for.

title

Sets the Terminal window title to the specified string. Usage example:

    title: This is my window
Copy code to clipboard

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>
Copy code to clipboard

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
Copy code to clipboard

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.