Session Scripting
The Session Scripting page describes the session scripting language Each command begins with a command verb followed by zero or more arguments and/or modifiers that vary for each command. Any optional modifiers are indicated by square brackets, the actual modifier keywords must be surrounded with periods. All row and column values start with one. The valid scripting commands are listed below.
#
A hash mark ('#') as the first non-blank character of a line causes the remainder of the line to be skipped. Use this to place descriptive comments in the script.
DEBUG
Writes extra diagnostic information to the CCS server log about the processing of a script. Should be commented out when the script is running correctly. There are no parameters to this command.
INCLUDE filename
This command allows scripts to include another script specified by the filename parameter. All commands in the included script are executed before continuing with the next line in the first script. Example:
INCLUDE other.script
EXITIF [.NOT.] text
Causes the script processing to end if text is found (or not found if the .NOT. modifier is used). Examples:
# Stop if the string 'logon' is not on the screen EXITIF .NOT. logon
# Stop if the string 'failed' is on the screen EXITIF failed
PROMPT [location_clause] [.SECONDS. seconds] text
Pause script processing until text appears on the screen. The .SECONDS. option may be used to specify the maximum number of seconds to wait for the text, processing of the script will stop if this time limit is exceeded. location_clause may be used to specify where on the screen text and/or the cursor position must be located:
location_clause = [.AT. [.ROW. row] column] [cursor_clause] cursor_clause = .CURSOR. [.ROW row] column cursor_clause = .CURSOR. .OFFSET. offset
Use .AT. to limit the text location to a specific column and (if .ROW. is used) a specific row. Use either form of cursor_clause if you wish to specify where the cursor must be located. The first form of cursor_clause specifies the cursor location independent of where text is located; the second form of cursor_clause using .OFFSET. specifies that the cursor must located within approximately (plus/minus 4) offset characters following the start of text.
TIMEOUT seconds
Causes script processing to pause for the specified number of seconds. Use to insert forced delays into the script.
TYPE text
Enter text as if typed by a user. The ampersand '@' is a special character used to send a function key indicated by the next character; for example to send an Enter (or Return) use '@E'. Other common 3270 functions include PF1 - PF9 which use '1' -'9' respectively, 'C' for Clear and 'T' for Tab. Use '@@' to send a single ampersand. You must use an '@E' (or for 3270 sessions another AID function key) to actually send the preceding alphanumeric data to the host. If text contains embedded spaces then surround the entire string with double quotes. Examples:
# Send the string 'ISPF' and Enter TYPE ISPF@E
# Send the string 'LOGON TSO' and then Enter TYPE 'LOGON TSO@E'
# Enter 'username', then Tab, then 'password', then Enter TYPE username@T TYPE password@E
Note that you can split text and functions into multiple TYPE commands.
ETYPE text
This is the same as the TYPE command except that the string is stored in an encrypted format. Enter your text in the Encrypt Text
field in the script editor window and click on the Encrypt
button which will insert the desired ETYPE command into the script. Function keys like Enter ('@E') may be included in the encrypted text but since they will be scrambled along with the rest of the string we recommend following the ETYPE command with an ordinary TYPE command to send the data to the host. For example:
# Send the encrypted string 'password' and then Enter ETYPE )='&T=X>P=G1 TYPE @E
WAIT
Checks whether the keyboard is currently locked and if so waits for the host to unlock it before continuing script processing. Applicable only to 3270 sessions.