TOC -Previous - Next

Chapter 5: Scripts

PowerTerm enables you to create scripts for automating tasks. Power Script Language (PSL) is PowerTerm's own programming language.

This chapter provides an overview of script commands and programming conventions used in PSL.

This chapter also describes how to create, edit, run, save and activate scripts in PowerTerm.

Each PSL command is described in PowerTerm's online help, which can be accessed by selecting Contents from the Help menu.

Script Overview.

Power Script Language (PSL).

Using PowerTerm Scripts.

Script Overview

You can use scripts to automate PowerTerm tasks. Scripts are written in Power Script Language (PSL) and are saved with a .PSL extension.

For example, you can create a script to login to PowerTerm, execute a file, display a message and so on. Scripts can be run upon startup or during a PowerTerm session.

PSL Types

    • PowerTerm commands can be grouped into six categories, which are described below:

Simulation transmission to host commands: Enable you to communicate with the host. For example, the <send> command sends data to the host.

Standard programming commands: Enable you to use standard programming commands. For example, the <exec> command opens a program.

File handling commands: Enable you to work with files. For example, the <read> command reads from a file.

DDE commands: Enable you to use standard Microsoft Windows DDE mechanisms to communicate with other Windows applications.

PowerTerm-specific commands: Enable you to activate specific PowerTerm features. For example, the <map> command enables you to map a PC key to a host key.

Desktop interface commands: Enable you to manipulate components in the PowerTerm window. For example, the <menu hide> command hides the PowerTerm menu.

Power Script Language (PSL)

Power Script Language (PSL) is a special feature of PowerTerm which provides commands for creating scripts. These scripts can be used to automate tasks. For example, you can create a script to login to PowerTerm automatically. PSL is intended for users with programming skills.

PowerTerm Sample Scripts, page , describes the standard scripts used in PowerTerm.

PSL Syntax, page , describes the syntax used to create PowerTerm script.

PSL Data Types, page , describes common formats for data strings.

Variable Assignment, page , describes the syntax used to assign variables.

Activating Script Files from the Host, page , describes commands to activate a script file or script commands via special escape sequences.

DDE Commands, page , describes the function of DDE commands for both client and server application.

PowerTerm Sample Scripts

PowerTerm provides several sample scripts designed for frequent tasks. The following table lists the sample scripts and their parameters:

Script

Parameters

Parameter Values

COMM.PSL

Port number

1 . 32.

 

Baud rate

All.

 

Protocol type

none, xonxoff, hardware.

TELNET.PSL

Host name

Specify the name of the host.

LAT.PSL

Service name

Specify the name of the service.

CTERM.PSL

Node name

Specify the name of the CTERM node.

All parameters must be typed in lowercase letters.

Additional sample scripts are also included as part of PowerTerm.

PSL Syntax

A command consists of one or more fields separated by spaces or tabs. The first field is the name of a command, which may be either a built-in command or a procedure consisting of a sequence of PSL commands. Newline characters are used as command separators, and semicolons may be used to separate commands on the same line. Each PSL command returns either a string result, or an empty string.

PSL has four additional syntactic constructs:

    • Curly braces{}
    • Square brackets[]
    • Dollar sign?
    • Backslash\

PSL commands must be entered in lower case.

Curly Braces

Curly braces are used to group complex arguments. They act as nestable quote characters. If the first character of an argument is an open brace, then the argument is not terminated by white space. Instead, it is terminated by the matching close brace. The argument passed to the command consists of everything between the braces, with the enclosing braces stripped off.

For example:

host = {vms unix {aix hp sun} aos}

The variable host will receive one argument:

"vms unix {aix hp sun} aos".

This particular command will set the variable host to the specified string.

If an argument is enclosed in braces, then none of the other substitutions described below is made on the argument. One of the most common uses of braces is to specify a PSL sub-program as an argument to a PSL command.

Square Brackets

Square brackets are used to invoke command substitution. If an open bracket appears in an argument, then everything from the open bracket up to the matching close bracket is treated as a command and executed recursively by PSL. The result of the command is then substituted into the argument in place of the bracketed string.

For example, the format command:

msg = [format {Data is %s bytes long} 99]

does print-like formatting (from the C language) and returns the string "Data is 99 bytes long", which is then assigned to the variable msg.

Dollar Sign

The dollar sign is used for variable substitution. If the dollar sign appears in an argument, then the following characters are treated as a variable name; and the contents of the variable are substituted into the argument in place of the dollar sign and name.

For example:

num = 99

msg = [format {Data is %s bytes long} $num]

The result is the same as the single command in the previous example.

The following are examples of common functions for the dollar sign in Power Script Language:

    • $P1 represents the variable of the parameter if P1 is the parameter.
    • $PC counts the number of parameters in the command line.

Backslash

The backslash character may be used to insert special characters into arguments, such as curly braces or nonprinting characters.

Such special characters include the following:

[ ] { } $ t b r m

\xFF will send the hex code FF (where F can be any hex character: 0-9, A-F).

For example:

send \x1B\[m

This command will send the three characters: escape, [ and m.

PSL Data Types

PSL uses only one type of data: strings. All commands, arguments to commands, results returned by commands and variable values are ASCII strings.

Although everything in PSL is a string, many commands expect their string arguments to have particular formats. There are three particularly common formats for strings:

    • Lists
    • Expressions
    • Commands

A list is just a string containing one or more fields separated by white space, similar to a command. Curly braces may be used to enclose complex list elements. These complex list elements are often lists in their own right.

For example:

{vms unix {aix hp sun} aos}

This is a list with four elements, the third of which is a list with three elements.

PSL provides commands for a number of list-manipulation operations, such as creating lists, extracting elements and computing list lengths.

The second common form for a string is a numeric expression. PSL expressions have the same operators and rules of precedence as expressions in the C language.

The expr PSL command evaluates a string as an expression and returns the result (as a string, of course).

For example:

expr {($x < $y) || ($z != 0)}

Returns "1'' if the numeric value of variable x is less than that of variable y, or if variable z is not zero; otherwise it returns "0''. Several other commands, such as if and for, expect one or more of their arguments to be expressions.

The third common interpretation of strings is as commands (or sequences of commands). Arguments of this form are used in PSL commands that implement control structures.

For example:

if {$x < $y} {

swap = $x

x = $y

y = $swap

}

The if command receives two arguments here, each of which is delimited by curly braces. if is a built-in command that evaluates its first argument as an expression; if the result is non-zero, it executes its second argument as a PSL command. This particular command swaps the values of the variables x and y if x is less than y.

PSL also allows users to define command procedures written in the PSL language. The proc built-in command is used to create a PSL procedures (PSLproc).

For example:

proc factorial x {

if {$x == 1} {return 1}

return [expr {$x * [factorial [expr $x - 1]]}]

}

This PSL command defines a recursive factorial procedure. The proc command takes three arguments: a name for the new PSLproc, a list of variable names (in this case the list has only a single element, x), and a PSL command that comprises the body of the PSLproc. After this proc command has been executed, factorial may be invoked just like any other PSL command.

For example:

factorial 4

returns the string "24''.

In addition to the commands already mentioned, PSL provides commands for manipulating strings (comparison, matching and printf/scanf-like C language operations), commands for manipulating files and file names. The built-in PSL commands provide a simple but complete programming language.

Variable Assignment

Syntax

varName = value

varName[index] = value

Variable assignment is as follows: the variable varName is on the left side of the expression and the value you want to assign to the variable is on the right.

For example: B = 200

Two types of variables: Scalar and Array

A variable containing a single value is a scalar variable and the majority of the time fits ones needs. Other times, it's convenient to assign more than one related value to a single variable. Then you can create an array variable that can contain a series of values. Array variables and scalar variables are declared in the same way, except that the declaration of an array variable uses parentheses [ ] following the variable name.

A variable. s scope is determined by where it is declared. When you declare a variable within a procedure, only code within that procedure can access or modify the value of that variable. It has local scope and is called a local variable. Differently a global variable declared outside a procedure is recognizable to all the procedures in your script. An exception to the rule governing local variables is when the global command has been invoked to declare varName to be global.

Activating Script Files from the Host

A host application may activate a script file or script commands via special escape sequences.

Escape Sequences for VT

Activating a script file called Script-Name:

ESCP$sScript-NameESC \

An example activating the message.psl script:

ESCP$smessage.pslESC\

ESC is the ASCII 27 code.

Activating script commands called Script-Commands:

ESCP$tScript-CommandsESC \

An example activating the "message testing ; send end" commands:

ESCP$tmessage testing ; send endESC\

Escape Sequences for DG

Activating a script file called Script-Name:

ESCWsScript-Name000

ESC is the ASCII 30 code, 000 is the ASCII 0 code.

Activating script commands called Script-Commands:

ESCWtScript-Commands000

DDE Commands

PowerTerm enables you to use the standard Microsoft DDE mechanism to communicate with other Windows applications. PowerTerm can be a DDE client application or a DDE server application.

The DDE server application waits for requests from DDE clients, and allows them to supply it with information or receive information.

For example:

A spreadsheet DDE server will let clients get data from cells and put data into cells of a file.

As a DDE server, PowerTerm uses the server name PTW with topic PSL. Any application can request it to execute commands and return the related return data.

A client application can access PowerTerm with the dde execute command or the dde request command and an item that is any valid PSL commands separated with ";".

The single DDE server PSL command is:

dde return value

After a dde request command is executed, the PowerTerm DDE server sends the value from the last dde return command executed in this request. If no dde return command executed, it returns an empty answer.

Examples for PowerTerm as a DDE server might be:

    • Sending information to the host.
    • Reading information from the emulation screen.

As a DDE client, PowerTerm performs one of several dde operations, depending on the option. The legal options are:

dde initiate applicationName topicName

Connects to the applicationName DDE server with topicName. Returns a conversation id for use with successive dde commands.

dde execute convId command

Executes a server command. Returns an empty string.

dde request convId item

Returns an item from the server.

dde poke convId item value

Changes an item of the server to the new value. Returns an empty string.

dde terminate convId

Terminates a DDE conversation with the server.

dde returns

Returns a value according to the option.

Examples

1 Assigns three numbers on the emulation screen to array "cel"

for {i = 1} {$i < 4} {incr i} {

row = [expr $i + 3]

cel($i) = [screen-rect $row 10 $row 15]}

Initiates a DDE conversation with MicroSoft Excel file TEST.XLS.

conv = [dde initiate EXCEL TEST.XLS]

Pokes the three numbers to three cels in TEST.XLS.

for {i = 1} {$i < 4} {incr i} {dde poke $conv R1C$i $cel($i)}

Requests the sum of those numbers from a result cel in TEST.XLS.

sum = [dde request $conv "R2C1"]

Terminates the DDE conversation.

dde terminate $conv

Sends the result to the host application.

send $sum

2 Initiates a DDE conversation with another PowerTerm which is connected to another computer. Reads information from the screen (of the other host) and sends it to its own host.

conv = [dde initiate PTW PSL-B]

data = [dde request $conv {

dde return [screen 10 1 15 80]}]

dde execute $conv{send joe}

For an explanation of each DDE command, see PowerTerm's online help. To access the online help for DDE commands, select Contents from the Help menu and click the Index tab. Type dde and click Display.

Using PowerTerm Scripts

    • PowerTerm provides the following script options:

Creating a Script, describes how to create a PowerTerm script.

Editing a Script, describes how to edit an existing script.

Recording a Script, describes how to record a script in PowerTerm.

Running PowerTerm Scripts, describes the various ways that a script can be launched.

Running a Specific Script, describes how to run a recorded script in PowerTerm to automate tasks.

Running a Script upon Startup, describes how to activate a script upon starting PowerTerm.

Running Individual Script Commands, describes how to run a specific script command.

Activating a Recorded Script , describes how to activate a script recorded in memory.

Saving a Recorded Script , describes how to save a script from memory to a specific file.

Creating a Script

PowerTerm enables you to create a script to run upon startup or at any time during a PowerTerm session.

Specify the PowerTerm folder (Ptw16 or Ttw32) in the Look in box in which to store the new script.

Type a name for the new script file in the File name box. You can type any name and extension that comply with DOS file-naming conventions.

It is recommended that you use a .PSL extension, because PowerTerm automatically recognizes that the .PSL extension indicates a script file.

    • Click Open. If the file exists, it opens ready for editing. If it does not exist, a message box displays, asking whether to create a new file.
    • Click Yes. Notepad opens to enable you to enter the new script:

Scripts can be written in any standard text editor.

Editing a Script

PowerTerm enables you to edit an existing script (.PSL) file.

From the Script menu, select Edit Script. The Edit Script dialog box is displayed:

Select the required script file by double-clicking the file in the files list. This opens Notepad and displays the selected script.

Edit the script as required.

From the File menu in Notepad, select Save to save your new script file.

    • Exit from Notepad.

Scripts can be written in any standard text editor.

Recording a Script

PowerTerm enables you to create a script by recording all the actions that you perform in the PowerTerm window. Actions can include selecting a menu option, typing an entry on the screen, making selections in a dialog box and so on.

From the Script menu, select Start Script Recording or click on the audio tape icon . The Start Script Recording option changes to Stop Script Recording while the audio tape icon appears pressed down .

Perform the manual operations that you want to record. For example, select a menu option, enter parameters in a dialog box or type a password.

If you do not want to record certain operations, click Pause Script Recording on the Script menu which changes to Continue Script Recording . This will pause the script recording process. You can then perform operations that will not be included in the recording.

To resume script recording, click Continue Script Recording from the Script menu .

When you have performed all the operations to be stored in the script, select Stop Script Recording from the Script menu.

You can also save the script file that you created, so that you can run it at any time to repeat the operations. For more information see  Saving a Recorded Script.

Running PowerTerm Scripts

PowerTerm enables you to run scripts, upon startup or during a PowerTerm session, to automate specific tasks.

Upon Startup

PowerTerm enables you to run a script from startup by creating a Windows shortcut to PowerTerm and a specific script file. This option can be used to connect to a host using a specific script. For more information, see Running a Script upon Startup.

During a PowerTerm Session

Using Soft Buttons

Soft buttons are named by default from F1 to F12. If you have assigned a script to F1, left-clicking on the F1 button is equivalent to sending the script to the host.

Using the Power Pad

Power Pad buttons are named by default from F1, F2, F3 and so on with a few default function names, such as Clear, Enter and Insert.
If you have assigned a script to the F1 button, left-clicking on the F1 button is equivalent to sending the script to the host. For more information, see the section Programming the Power Pad.

Using the Run Script Command

The Run Script command is a menu option which enables you to run a script created to automate tasks. For more information, see Running a Specific Script.

Upon Connecting to a Host

PowerTerm enables you to specify the name of a script to be run after communication is established. The name of the script file needs to be specified in the Script File text box in the Connect Dialog box. For more information, see the section Step 6: Connecting to a Host.

To browse for the specific name of a PSL Script, press on the button with three dots to the right of the Script File text box.

Running a Specific Script

PowerTerm enables you to run a script (.PSL) file to automate tasks. For example, you can create a script to login to PowerTerm automatically.

From the Script menu, select Run Script. The Run Script dialog box is displayed. It lists all the files in the PowerTerm directory that carry the .PSL extension.

Double-click the script file that you want to run.

You can run a script as you start PowerTerm. To achieve this, you should add the script name to the PowerTerm shortcut or command line. For more information, see Running a Script upon Startup.

Click Open. The selected script file is executed. For more information on running scripts, see Running PowerTerm Scripts.

Running a Script upon Startup

PowerTerm enables you to run a script upon startup by creating a Windows shortcut to PowerTerm and the specific script file. This option enables you to automatically connect to a host using a PSL script. For more information, see Step 6: Connecting to a Host, page 84.

The following procedure describes one way to create a shortcut. Consult your Windows 3.x documentation for a description of other available options.

Click the PowerTerm icon in the PowerTerm group.

From the File menu, select the Properties option.

In the Command Line area, position your cursor after the .exe file name, type a space and then type the name of the script (.PSL) file and required parameters.

Click OK.

Or

The following procedure describes one way to create a shortcut. Consult your Windows 95 documentation for a description of other available options.

Right-click the Start button on your Windows 95 desktop.

Click the Open menu option. The Start Menu window is displayed:

Select Programs from the Start Menu window. The Programs window is displayed.

Right-click the PowerTerm icon. Select Properties from the popup menu. The PowerTerm Properties window is displayed. Select the Shortcut tab.

In the Target area, position your cursor after the .EXE file name, add a space and then type the name of the required script (.PSL) file.

You can also add parameters to the script file. These determine communication parameters. For example, the name of the host to which you want to connect, or the Port number.

In the Target area, position your cursor after the PSL script name, add a space and type the required parameters. Parameters should be separated by a space.

Example:

\PTW32\PTW32.EXE COMM.PSL 1 9600 xonxoff

PowerTerm recognizes Windows 95 file naming conventions, including spaces in a file name. If you have a setup file with a space in the name, PowerTerm ignores the space and looks directly for the .PSL extension.

Click OK. When you start PowerTerm, the script file is automatically executed and you are connected to the host that you specified in your setup file.

Repeat the process described above for each host.

Running Individual Script Commands

PowerTerm enables you to run individual script commands which you have created.

From the Script menu, click Script Command. The Script Command dialog box is displayed:

Type the name of the script command you want to run.

Click OK. The specified script command is executed.

Activating a Recorded Script

Once you have recorded a script in memory, you can run it.

Saving a Recorded Script

PowerTerm enables you to save a script from memory to a specific file.

From the Script menu, click Save Recorded Script. The Record Script dialog box is displayed:

Select the directory in which you want to save the file.

Enter a file name. The file extension .psl is automatically added to the file name.

Click Save. The file is saved with the specific file name.

TOC -Previous - Next