Chapter 10 - Managing Script Files
Script files enable you to automate certain or all portions of a terminal emulation session that are routine. Using a previously built script, you can help less experienced users to perform complex tasks or hide complex host login procedures from users. Scripts also allow you to change communications or other settings.
Generally, scripting commands enable you to control how a user interacts with a host computer.
The commands make up a programming language with limited capability. They include such features as branching, if-tests, and the use of variables. Some commands change communication and terminal settings, using the same values as the keywords in parameter files and the settings on the ATE menus.
The scripting commands are compatible with those in Crosstalk XVI Version 3.6. Scripts written for this version of Crosstalk can run unmodified in the Banyan environment.
There are Crosstalk commands that are either not applicable or currently not supported in the Banyan environment. A list of these commands is provided in "List of Unsupported Commands" later in this chapter.
Creating and Editing Script Files
ATE script files are ASCII text files in DOS format. To generate scripts, you can use any workstation text editor that produces such files. You can retain and use any of your existing Crosstalk scripts.
"Sample Script File" later in this chapter shows the format of a script file. Follow that format when you create your own files.
Providing User Access to Script Files
You can provide several ways for users to access script files, as follows:
|
Direct users to use configured connections, and associate the script files with those connections. |
|
|
Include the appropriate scripts in the directory specified with the /PATH switch on the SETASYNCH command in the user profile. Create script files with the same file name as the parameter file you wish the user to use. Give the script file the extension .ATS. The script file executes automatically whenever the user enters emulation by using the parameter file, either through the ATE menus or at the DOS prompt. |
|
|
Provide more advanced users with information on how to create their own script files, and tell them about any other script files that are available. Users can run any script from the SETASYNCH /PATH directory, or their current directory, at any time. |
Unless otherwise noted, commands are interactive, meaning that users can enter them from a special command line while in emulation. When the user presses the ATTENTION key (initially set to SHIFT-TAB), the command line appears on the bottom line of the emulation screen. The user can then enter a command.
All of the commands listed in this section can be issued both interactively and from a script file, unless they are marked "Script only."
The commands are presented in alphabetical order, with explanations following each command and examples where appropriate. The format of the command list is as follows:
|
|
The underlined portion of each command indicates the allowed abbreviation. |
|
|
Command parameters in lower case in <angle brackets> indicate that you must supply an appropriate value. |
|
|
Parameters in UPPER CASE must be specified as shown. |
|
|
Parameters enclosed in [square brackets] are optional. |
|
|
A <key> can be a hexadecimal value (such as 1B), an ASCII mnemonic (such as EOT), or a workstation keyboard key (such as PgDn). If <key> is optional and is not specified, the user is prompted to press the appropriate key. Note that the numbers 0 through 9 and the letters A through Z cannot be selected. |
|
|
When <string> is specified as a parameter,
the following characters have special meaning: | (vertical bar) indicates a carriage return. ~ (tilde) indicates a two-second delay. To include unprintable ASCII characters in the <string>, use the control sequences shown in Table 10-8. <fkey> specifies an unshifted, regular function key, SHIFT-function key, CTRL-function key, or ALT-function key. You describe the function key with a digit from 1 to 0, using 0 to substitute for 10. The FKEYS command sets the contents of <fkey>. An at-sign (@) symbol in front of <fkey> can be used wherever a <filename> parameter is specified. This will result in the execution of the command, using the contents of the <fkey> as the file name. <toggle> can have the values shown in Table 10-1. |
When you include the commands in a script file or a parameter file, use the format shown in this section. As in a parameter file, you can use semicolons to introduce lines that contain comments.
If you use any of these commands in a parameter file, they must make sense at the time you issue them. For example, script commands should appear after keywords that make the connection to the host.
Note: Scripting commands that change communications settings, such as SPEED and DUPLEX, may not work properly with X.29 connections.
Terminates processing of the current script file. Normally used when an error has been detected and the remainder of the script file should not be processed. Script only.
Sends one of four alarm tones (1 through 4) to the workstation.
Prompts the user of the script for information. The reply can be a single character or a string. The single character reply can be tested by a subsequent IF command allowing decisions to be made within the script file. The string reply can be assigned to a function key. The string subsequently can be sent to the host either by the user pressing the function key or by using the REPLY command. If <prompt> is omitted, a question mark is printed as the prompt.
Selects the key to be used for the ATTENTION key, which displays the Cmd> prompt on the 25th line. This key can't be sent to the remote computer, since typing it causes the program to immediately enter the command mode. The default key used for attention is SHIFT-TAB. You must select another key for the Attention key if you need to send SHIFT-TAB to the host.
If AUTOLF is toggled on, a line feed is added automatically after each received carriage return. Similarly, a carriage return is added after each received line feed. This is useful when communicating with hosts that send carriage returns but no line feeds, or vice versa. Note that this command has the same effect as an LFAUTO command.
If AUTOWRAP is toggled on, the cursor wraps to column 1 of the next line when the end of the current line is reached. Otherwise, the cursor remains at the end of the current line.
Indicates the default character is sent to the host when the BACKSPACE key is pressed. For VT100 emulation, the default is DEL. For all other terminal types, the default is BS.
BLANKEX <toggle>, or BLANKCOMPRESS <toggle>
Indicates how blank lines should be handled when sending text files to another computer. If this setting is toggled on, blank lines are converted into lines consisting of one space. The ON setting is useful when sending prepared text containing empty lines to a host computer system that assumes a blank line means the end of text.
Selects the key to be used for sending an ASCII BREAK character. The default key assignment is CTRL-END.
Hangs up the phone line, and disconnects the current call. This command can be used to hang up and make another call without exiting from emulation.
Captures data from the host directly to disk. If the file already exists, captured data is appended to it.
Ends data capture.
Toggles the data capture state.
Changes the current DOS directory. The command CD with no pathname shows the name of the current directory.
Indicates whether a delay should be introduced between characters when transmitting data to the host. This command is similar to the CWAIT command.
Indicates the character set to be used. US indicates United States character set. UK indicates United Kingdom character set.
Selects the number of data bits (7 or 8). Equivalent to the DATA command.
Clears the screen. Script only.
Sets the connection name to be used for making the connection.
Indicates whether line feeds should be filtered out when transferring data to the host. Equivalent to the OUTFILTER command.
Sets the shape of the cursor during emulation to either a block shape or an underscore.
Indicates how long to wait between characters when transmitting files. This command should be used for sending data to a computer system that cannot accept data at full speed.
The CWAIT command has several options. Table 10-2 illustrates the effect of each option.
Selects the number of data bits. The default is 8. The ATE service automatically switches to 8 bits whenever a protocol transfer is performed, even if 7 bits was selected previously.
Shows the current workstation disk directory, much like the DOS DIR command.
Toggles control character filtering for data from the host. With the value YES, all characters are passed through as is. Equivalent to the INFILTER command.
Begins or continues execution of the commands contained in a script file. The three forms of the DO command are shown in Table 10-3.
Entering DRIVE alone shows the amount of space remaining on all of the workstation drives in the system. Entering DRIVE followed by a drive designator (such as B:) changes the default drive to the specified drive.
Sets duplex to full (local echo OFF) or half (local echo ON).
Lets the user invoke a DOS text editor during emulation. The emulation software stays resident. After exiting the text editor, the user returns automatically to emulation. Prior to the EDIT command, specify the EPATH command to indicate the location of the text editor program.
Sets the type of terminal to emulate. In the Banyan environment, x can be v, i, 5 or g for VT100, IBM3101, VT52, and TTY, respectively. Any other specification is considered an error, and the terminal type is set to TTY.
Sets the terminal type to emulate. Available types are VT100, VT52, IBM3101, and TTY.
Specifies the name and location of the DOS text editor to be invoked by the EDIT command. For example, if the EDLIN editor is to be invoked from a subdirectory called bin, the user would specify the following pathname:
epathc:\bin\edlin.com
Erases a file. The user is always asked to confirm an erase before the operation takes place.
Sets and displays the contents of the function keys F1 through F10.
FK shows the settings of the unshifted, unaltered, uncontrolled function keys. FK S shows the contents of those keys when shifted. FK A shows the contents of the ALT-function keys. FK C shows the contents of the CTRL- function keys.
To set a function key, enter FK <n> <string> (FK <An> <string> for ALT-keys, FK <Sn> <string> for shifted keys, and so on). N is the number of the key to be set, and string is the string of text assigned to that key.
Any key string that begins with an at-sign (@) is processed as a command. For example, the command FK C1 @PR / sets CTRL-F1 to enter the command @ PR /. When CTRL-F1 is pressed, print capture is toggled on or off.
To include unprintable characters in the <string>, use the control codes in Table 10-8.
You cannot specify values for function keys that are used in other ways by ATE. For example, F1 (unshifted in any way) is used for PF1 in VT100 emulation and cannot be reassigned by the FKEYS command. Chapter 7 lists all such keys.
Indicates the flow control to be used when communicating with the host computer, where a indicates the character to make either the ATE or the host stop sending, and b indicates the character to make either the ATE software or the host start sending. The variables ab represent any two characters you want to use to signify starting or stopping flow control.
For example, FL ^X^Y uses CTRL-X to stop sending, and CTRL-Y to start sending.
The default setting is ^S^Q, meaning that the host system stops sending on receipt of a CTRL-S, and restarts after receiving a CTRL-Q.
Disables flow control entirely.
Gets a file from a remote Kermit server.
Dials a number and establishes a connection. Specify R n to cause an automatic redial every n seconds. The number of times to redial is set by the RDIALS command.
Presents help for a particular command. If you do not provide a command, it displays information about HELP.
Lets you test the last single character reply to the ASK command. You can test it for being equal, or not equal, to a single character or any one of a list of single characters. Use a minus sign (-) to denote inequality. You can test if the user is online by specifying the special condition $ (dollar sign). The following examples illustrate the syntax and results of some IF tests:
ASK Do you wish to clear the screen (Y or N)?
IF Y clear
Clears the screen if the user types Y.
ASK Do you wish to clear the screen (Y or N)?
IF -N clear
Clears the screen if the user types anything but N.
ASK Do you wish to exit this session?
IF XEY quit
Exits from emulation if the user types X, E, or Y.
IF $ ALARM
Sounds the alarm only if a connection is active.
Controls filtering of incoming control characters in emulation mode. INFILTER also strips the top bit off of 8-bit characters.
Directs the flow of the script to a specified label in the script file. The label can contain an at-sign (@). In such a case, the @ symbol is replaced with the answer from the most recent ASK command.
The following example illustrates how to use this feature:
LABEL askuser
ASK Enter A, B, or C:
IF -ABC RWIND
JUMP DO-@
LABEL DO-A
<commands>
LABEL DO-B
<commands>
LABEL DO-C <commands>
Controls Kermit file transfers. The supported KERMIT commands are shown in Table 10-4.
Marks a location in the script file that can then be used by other commands.
When LFAUTO is on, a line feed is automatically added after each received carriage return. This method is useful when communicating with systems that do not send line feeds. When LFAUTO is on, a carriage return is added automatically after each received line feed. This method is useful when communicating with systems that send line feeds without carriage returns.
If on, a delay is introduced at the end of every line while sending text files to the host. Same as the LWAIT command.
Loads script files. The search path is searched to find the file. If an extension is not provided, a default extension of .ATP is used. When the file is found, it is executed.
Indicates how to wait between lines when transmitting text files with the SEND command. There are several options to the LWAIT command. Table 10-5 describes these options.
Sets the default timeout interval. See also the WAIT command.
Displays a message on the screen. The command must be followed by a line containing a single period (.) to mark the end of the message.
Sets the phone number to be dialed. The number can be up to 40 characters long. Some special characters provide dialing control functions when used in a phone number, depending on the modem being used.
Filters line feeds when sending text files. If OUTFILTER is ON, line feed characters are discarded.
Sets the parity bit to the appropriate value (NONE, EVEN, or ODD).
Allows the user to save a character image of the screen into a file.
Echoes displayed data on the LPT1, LPT2, or LPT3 printer port.
Controls echoing screen data to the printer last specified by port name. ON echoes displayed data on the printer. OFF stops echoing. A slash (/) toggles the printer to the opposite state of its current setting.
Disconnects immediately from the host and returns the user's workstation to DOS.
Sets the number of times to dial a phone number before abandoning the call. The normal (and maximum) value is 10. If RDIALS is set to 0 (zero), then no attempt is made to redial a call if the call fails to connect on the first try.
Sends a string of text to the host. Alternatively, the contents of a function key can also be sent. To include unprintable characters in the <string>, use the control codes in Table 10-8. The REPLY <string> script command can send a string containing the at sign (@) to the host. For example, REPLY @@1234 sends the string @1234 to the host.
Runs other programs from terminal emulation. Control goes to the other program by executing a second copy of COMMAND.COM. Control returns to the emulation program after the second program finishes. If the program-name is omitted, the user goes to a DOS shell; control is returned by entering EXIT at the DOS prompt.
Restarts the script from the beginning.
Saves all the current settings and function key definitions into a named script file for future use. The file will have an extension of .ATP unless explicitly overridden by the user. This command does not save or edit the entire script file.
Sends a BREAK signal from within a script file. Similar to pressing the BREAK key.
Sends a text file to the host, with no error checking. For information on all of the commands affecting the operation of the SEND command, see also the LWAIT, CWAIT, BLANKEX, and OUTFILTER commands.
Skips n number of lines in the script file; n cannot be zero or negative. You cannot skip past the last line of the file.
Indicates whether a status line should be displayed on the 25th line of the display.
Selects the speed, in baud, at which your computer communicates with the host. Two digits or the word ANY represent the desired speed. Table 10-6 shows the speeds for two-digit values.
The word ANY means that the software chooses a valid speed based on service and line configurations.
Sets the number of stop bits used to make up the data word.
Selects the key that suspends terminal emulation and returns to DOS. By default, the SUSPEND key is not assigned to any key. The SUSPEND feature can only be used if the terminal emulation software is made resident by the RASYNCH command. You can resume the suspended session simply by entering ASYNCH at the DOS prompt. Note that when a session is suspended at a workstation, the user cannot start a new one. Instead, the suspended session is restarted.
Selects the key that switches between the emulation screen and the Action Menu. This key is normally HOME (CTRL-HOME when in IBM 3101 emulation), but can be changed to another key if desired.
Sets the phone number to be dialed. The number can be up to 40 characters long. Some special characters provide dialing control functions when used in a phone number, depending on the modem being used.
TABEX <toggle>, or TABEXPAND <toggle>
Turns tab expansion on and off. When TABEX is on, transmitted tab characters are sent as spaces to the next tab position. This feature is useful when sending files to systems that do not interpret tabs.
Note that this command only affects the SEND command. It has no effect on normal terminal emulation.
Sets tab stops at the specified columns.
Turns service data trace on or off. Data to or from the host is logged by the ATE service into a logfile on the server. You can extract or view the file from the server console. Only one session can be traced at any time.
Indicates a character to be sent when ENTER is pressed, or when a vertical bar appears in a <string> sent by REPLY or a function key. Some computer systems use a key other than ENTER to mean an end of line.
TYPE [#] [start-line] <filename>
Displays the contents of a specified disk file on the screen. Line numbers can be added to each line by specifying the # symbol. TYPE can also be started at a particular line number. When typing a file, the display can be paused by typing CTRL-S, or canceled by typing CTRL-C.
Sets upper-case mode on and off. When UCONLY is on, all lower-case letters encountered during a SEND are converted to upper case. Received characters are not affected. Note that this command does not have any effect on normal terminal mode operation.
Suspends the execution of a script file until a certain condition is met. If the condition is not met within the time set by the MAXTIMEOUT command, the script flows to the optional label if you specify one. The options available with the WAIT command are listed and described in Table 10-7.
Allows a command or series of commands to be performed in a script when a particular string arrives from the host, as shown in the following example:
WHEN "Password:" REPLY BERT | : DO
WAIT MANUAL
WHEN sets the condition to watch for, and script processing continues. WAIT MANUAL suspends script processing. When the host sends the string "Password:" to prompt for the password, it activates the WHEN condition.
The commands specified on the WHEN condition send the string "BERT" to the host, then resume script processing with the DO command.
WHEN stays active until it is explicitly deactivated by WHEN -. Blanks and case are ignored during the checking of a WHEN condition. If a WHEN condition occurs and a script file containing a WAIT statement is waiting for a particular character or string of characters, the WHEN condition prevails. After the WHEN condition is met, and the WHEN commands are executed, the program resumes script file execution at the next line after the WAIT command.
Exits to DOS without breaking the connection. Can be used only if terminal emulation software is made resident with the RASYNCH command. When the user returns to emulation later, the connection is intact.
Transmits files to a remote Kermit server. Wildcard file names are not allowed. The remote host must be in Kermit server mode.
Indicates whether XON/XOFF flow control should be used. Similar to the FLOW command.
The commands in Figure 10-1 from Crosstalk XVI Version 3.6 are not supported in the Banyan environment. When a script file issues them during emulation, they are ignored and a warning appears on the screen.
The following text shows the contents of a sample script file. The file assumes that a connection name is used to begin a session with the host. Then, the script file automatically logs the user in and reads any new mail on the host system.
Sending Unprintable Characters
Table 10-8 shows the control codes used to send unprintable characters in a script command string. A control code consists of a caret (^) followed immediately by a single character, as in ^C. For example, to send a backspace character, include ^H in the string.
