User Manual

Chapter 8

Scripting

---

PC-Duo includes powerful Scripting facilities, which enable you to automate routinely-performed tasks. To use the Scripting facility, you need to have installed the Scripting component when installing PC-Duo. For more information, see Chapter 2, "Installing PC-Duo". If the Scripting component has been installed, you can use the Script Editor to create new Scripts, and the Scripting Agent to schedule those Scripts.

The PC-Duo Control application does not need to be running to run scheduled Scripts from the Scripting Agent.

If the Control window is running while you are running Scripts using the Script Editor or Scripting Agent, any activities performed using Scripts will not be displayed in the Control window. For example, if you run a Script that connects to a Client, the Control window does not indicate the Client is connected.

PC-Duo also enables you to run and edit Scripts from the Control Application. For more information, see "Running Scripts from the Control".

The Script Editor

The PC-Duo Script Editor enables you to create and edit Scripts that can automate tasks. After creating a Script in Script Editor, use the Scripting Agent to specify when the Script is scheduled to run.

To start the Script Editor, click the Start button in the Taskbar to display the Start menu, then choose the Programs, PC-Duo, Script Editor command.

The Script Editor window is divided into the following areas:

The Command Viewer

is the left pane in the Script Editor window. It looks similar to the Tree View in the PC-Duo Control window.

The folders list all of the functions, variables and constants that are available in the PC-Duo scripting language.

As well as using the contents of the Command Viewer as a useful reference, you can drag commands from the Command Viewer into your Script windows.

Script Windows

enable you to view or create Scripts. (When you first start the Script Editor application, no Script windows are displayed, although space is provided for them on the right of the Script Editor application window.)

Script windows can be minimized, restored and maximized inside the Script Editor window. When the active Script window is maximized, the Script window title bar merges with the Script Editor window's title bar.

The Output Window

is in the bottom pane of the Script Editor window. It displays information about the Scripts in use, such as progress messages and syntax errors.

Using the Script Editor

Use the Script Editor to create and work with script files:

• To create a new Script, choose the File, New menu command or click the New button in the Toolbar.
• To open an existing Script, choose the File, Open command or click the Open button in the Toolbar, then use the Open dialog to open the appropriate script file.
• A list of recently opened Scripts is displayed in the File, Recent Files submenu. You can select a Script from this list to open it in a Script window.
• You can have more than one Script window open at a time, and arrange them using the commands in the Script Editor's Window menu.

Writing and Editing Scripts

View, write and edit PC-Duo Scripts in Script windows:

• You can have several Script windows open at a time, so that you can view different Scripts simultaneously, and copy and paste commands between them.
• You can drag selected text to a different location in the current Script window, or to another Script window.
• To add a command to a Script, type the command, or display the command in the Command Viewer, then drag it into the Script window.
• If you are not sure about the operation of a command listed in the Command Viewer, right-click the command and choose the Display Help On Command from the shortcut menu. A Help window displays information on the selected command.

Checking and Running Scripts

You can check your Scripts for errors and run them from within the Script Editor application:

• To check your Scripts for syntax errors, choose the Run, Check Syntax menu command, or click the Check Syntax button in the Toolbar. The Script Editor checks your Script for errors, and displays the results in the Output window at the bottom of the Script Editor window.
• To run your Script in the Script Editor application, choose the Run, Execute menu command, or click the Execute button in the Toolbar. The progress and results of the Script are displayed in the Output window.

Saving Scripts

The Script Editor automatically saves the current Script when you run it.

• To save a Script, choose the File, Save command or click the Save button in the Toolbar. If this is the first time you have saved the Script, you are prompted for a file name for the Script
• To save a Script under a different file name, use the File, Save As command.
• When you save a Script under a different file name, the original Script file remains unchanged. This command is useful for creating a new Script based on an existing Script.

The Scripting Language

The PC-Duo scripting language is a powerful interpreted language similar to VBScript. It enables you to automate tasks you need to perform regularly.

The scripting language offers:

• Easy to understand, structured syntax.
• A wide-range of text manipulation functions.
• The ability to work with multiple connected Clients.
• Support for local and remote operations.
• Full logging of activities.
• The ability to supplement the system log with your own log messages.
• All of the security features associated with the Control application.
• Scripts that can contain encrypted passwords (using the Script Editor's Edit, Insert Password menu command).

An important point to remember when working with Scripts is that a PC-Duo Script needs to be self-contained; each Script acts as an individual PC-Duo Control.

For example, if you connect to a Client at the start of a Script, you must disconnect from it later in the same Script. (If you try to use a second Script to disconnect from the same Client, it would not regard that Client as being connected.)

Working with Variables

Three variable types are available for use in the scripting language:

Integer

An unsigned numeric variable

String

A series of characters

List

A series of strings in a list. A range of functions is supplied for populating, managing and searching Lists. These functions are listed in the Script Editor's Command Viewer, under Functions, List.

You must define variables before using them. You must assign a value to Integer and String variables before using them in conditional statements.

Assigning a value to a variable for the first time forces the Script interpreter to create this variable, and the variable is then available for the rest of your Script. If you try to use a variable that has not been defined, an error is generated.

When you need to assign a value to a variable, the = symbol is used:

Assignment	Description
A = 10	Assigns an integer value to the variable A
A = B	Assigns the value of another integer variable to A
Firstname = "Nick"	Assigns the string "Nick" to the variable firstname
Firstname = A	Converts the numeric value of A to its string representation and assigns it to firstname
Name = "Nick " + lastname	Creates a string variable from two strings which are concatenated using the + symbol

Using Logic Operators

Use logic operators to test whether a result is TRUE or FALSE:

Operator	Description
= =	Equal to
=	Equal to-this is only valid in conditional statements, otherwise it means assign
!=	Not equal to
<	Less than
>	Greater than
AND	The result is TRUE if both operands are TRUE
OR	The result is TRUE if either operand is TRUE

When these operations are used to form a conditional statement, the result is either TRUE or FALSE. This result is used by all conditional structures within the scripting language.

Using Other Operators

You can use the following operators to modify the result of a calculation:

Operator	Description
*	Multiplies the left operand by the right operand
/	Divides the left operand by the right operand
+	Adds the right operand to the left operand
-	Subtracts the right operand from the left operand
( )	Returns the result of the arithmetic operations inside the parentheses. These can contain other parentheses as well as functions
&	Bitwise AND compares each bit of the first operand to the corresponding bit of its second operand. If both bits are 1, the result is set to 1. Otherwise, the Result is set to 0
|	Bitwise OR Compares each bit of its first operand to the corresponding bit of its second operand. If either bit is 1, the result bit is set to 1. Otherwise, the result is set to 0

Using Loops

There are four different types of conditional loop available within the Scripting language. Each of the loops does something until a condition is met:

Do While... Loop

Performs a set of instructions whilst a supplied expression is TRUE

Do Until... Loop

Performs a set of instructions until a specified expression is TRUE

For... Next

Used to execute a group of statements a specified number of times, until the upper limit of the loop is reached, or there are no more strings in a list.

For Each... Next

Executes a set of functions once for every item in a string list. These loops can be nested inside one another.

Syntax examples for each of these statements are available in the online Help.

Using Condition Statements

You can conditionally execute a group of statements depending on the result of an expression. To do this, use the If... Else... Endif statements.

 For example: If connectedclients () = FALSE then Print "We are not currently connected to any Clients!" Else Print "We are connected to Clients." Endif

Using Comments

You can use comments in your PC-Duo Scripts to improve the readability of your Scripts. The scripting language uses the C style of single line comments, which consists of two forward slash
( // ) characters. These can be placed anywhere on a line in your script. Anything on this line following the two forward slash characters is interpreted as a comment.

Some Useful PC-Duo Scripting Functions

The real benefits of using PC-Duo Scripting are the built-in functions, which enable you to connect to, perform operations on and retrieve information from Client PCs.

To help you get started, some examples of useful functions are described here:

SetTransport

Sets a new default network transport protocol to be used by all following Client operations.

Example: SetTransport (T_TCPIP)

Connect

Connects to the specified Client.

Example: If Connect ("TEST1") = TRUE then Print "Connected to test1"

You can specify the name or IP address of the Client you want to connect to. If you specify the Client name, the Control must have previously connected to the Client.

If you specify the Client's IP address, it must be preceded with the > character. For example:" >nnn.nnn.nnn.nnn".

The optional <Transport> parameter enables you to specify the transport with which you want to connect to the specified Client. You can specify IPX, TCP or NBn, using the numbered stack n from 0-7.

ConnectedClients

Returns the number of Clients you are currently connected to.

Example: Print "You are connected to ", ConnectedClients ( ), " Clients."

Mkdir

Creates a directory on the specified PC.

Example: Mkdir ("TEST1>C:\SALES\UPDATE")

Copy

Copies files to and from Control and Client.

Example: Copy ("C:\SALES\INFO\*.DOC", "test1>C:\SALES\UPDATE")

Control, Watch and Share

These functions enable you to start a remote control session from a Script. They are used in conjunction with the WaitEndView function, which waits for the View window to close before proceeding with the Script.

Example: Nowviewing = Share ( )

LoadFields

Populates a List with a series of entries from a text file.

Example: LoadFields("D:\Support\clientproperties.txt", ClientName)

Disconnect

Disconnects from the Client.

Example: Disconnect ("TEST1")

Creating User Functions

You can create your own functions in the PC-Duo scripting language. This enables you to create your own blocks of code that can be called repeatedly from another part of a Script.

For example, you can create a function that connects to a Client and retrieves information from it. You can then call the same function several times for different Clients.

When working with your own functions in a Script, use the following guidelines:

• You must create a function called Main in your Script. This main function can be placed anywhere in a Script, but is the first part of the Script to be run.
• When a Script features user functions, all statements in a Script must be inside a function block.
• The variables created inside a function are only available to the function in which they were created.
• Function declarations must be followed by parentheses.
• Any function arguments must go inside the parentheses that follow a function.
• You can have up to ten arguments in a function.
• Function arguments are only available from within the function and should be regarded as being read-only within the function to which the arguments are being passed.
• You do not need to specify a function's argument types.
• Use $INCLUDED to call functions defined in other Script files. For an example of its use, see ADDTOLOG.SCP in the sample scripts included with PC-Duo.

Use the following format when creating the Main function:

 Function Main () ... End Function 

Use the following format when creating your own functions:

 Function myfunction () ... End Function

Use the following format when creating a function that requires arguments to be passed to it:

 Function myfunction (argument1, argument2) ... End Function

Use the following format to call a function:

 Returnvalue = myfunction (10, 20)

Accessing Databases from Scripts

PC-Duo enables you to access ODBC-compliant databases from Scripts. Before connecting to a database using a Script, you must create a Data Source Name (DSN) for the database you want to access.

A Data Source is a collection of information used to connect an application to a database. It enables you to refer to a Data Source Name, rather than an explicit path to a database file.

The following instructions explain how to create a DSN for a Microsoft Access database. Note that the manner in which a DSN is created varies slightly for other database formats.

To Set up a DSN for an Access Database:

1. Display the Windows Control panel, then double-click the ODBC Data Sources icon. The ODBC Data Source Administrator dialog is displayed.

   In Windows 2000 and XP, the ODBC Data Source Administrator dialog is accessed from Control Panel, Administrative Tools, Data Sources (ODBC).

2. Select the System DSN tab.
3. Click the Add button. The Create New Data Source dialog is displayed.
4. Select the appropriate driver for your database, then click the Finish button.
5. The ODBC Microsoft Access Setup dialog is displayed. Enter a Data Source Name, then click the Select button.
6. Use the Select Database dialog to browse to the location of your Database. After selecting the Database, click OK to return to the ODBC Microsoft Access Setup dialog.
7. Click OK to return to the ODBC Data Source Administrator dialog, then click OK again. You have now created a DSN for your Database.

   DSNs are PC-specific. If you want to share your data-driven scripts with other users, they must also create a DSN for their database.
   Depending on your Database format and security, you may need to define additional user name and password access permissions for a DSN.

Using Database Functions in Scripts

Once you have configured a DSN for a database, you can access that database from PC-Duo Scripting using dedicated Database functions. These functions are listed in the Script Editor's Command Viewer under Functions, Database.

The major database functions are described here. Use caution when running functions designed to modify or delete data from a Database. We recommend you test functions on a copy of your database before running them on a live database.

Several example scripts, some of which use database functions, are supplied with PC-Duo.

Opening Databases

To retrieve and manipulate data from a Script, you must first open the database. The dbOpen function opens the database referred to by a specified DSN:

 dbOpen("mydata")

You can also supply a user name and password as well, as shown here:

 dbOpen("mydata", "NH", "KLDGWD")

Closing the Current Database

The dbClose function closes the currently open DSN:

 dbClose()

Returning Available Database Drivers and DSNs

The dbDrivers and dbDataSources functions return all drivers and data sources on a system.

 dim mydrivers as list dim mydsns as list dbDrivers(mydrivers) dbDataSources(mydsns) print "ODBC Drivers:" For each buffer in mydrivers
 print " ", buffer
 next print "Data Sources:" for each buffer in mydsns
 print " ", buffer
 next

Executing SQL Statements

The dbExecute command enables you to run SQL commands:

 dbExecute "SELECT ClientName from tblClients"

Your SQL statements are not limited to SELECT statements. Using the dbExecute function, you can also perform UPDATE queries and other powerful SQL operations. For more information, see "Creating SQL Statements".

Listing the Columns in a Table

The dbColumns function enables you to retrieve column names (field names) in a specified table. dbColumns takes two parameters: the name of the table, and the name of the list variable you want to populate with the column names:

 dbColumns("tblclients",columnlist) for each column in columnlist
 print column
 next

Retrieving Data to a List

The dbFetchList function retrieves data from an open database and puts it into a list variable:

 dbFetchList h, 2, iplist, 1, namelist, 3, plist, 4, idlist

Returning the Number of Records Matching a Criteria

The dbFind function returns the number of records that meet a specified (SQL) criterion:

 numMatches = dbFind "tblClients", "ClientName LIKE 'NH'" Print numMatches

You can pass multiple conditions to the dbFind function, with the conditions being separated by commas.

Returning the Data from a Table Column

The dbGetData function returns the data for a column:

 dbGetData ("h","clients")

Adding Entries to a Table

The dbInsert function adds an entry into a specified table and field:

 dbInsert "tblClients","ClientName","NH"

Releasing the Handle to the Current Database

The dbRelease function frees up the handle to the current database:

 dbRelease(h)

Listing the Tables in a Database

The dbTables function takes a list variable as a parameter, and populates it with the available tables in the database:

 dim tablelist as list dbOpen("Scriptingdbase") dbTables(tablelist) For each table in tablelist
 Print table
 Next dbClose()

Selecting and Sorting Records

The dbSelect function selects and sorts records that match a specified criteria. The following example selects all the Client names from the Client table and orders them by Client name:

 dbSelect("tblClients", "ClientName","","ClientName")

Deleting Records from a Table

The dbDelete function deletes the specified Client from the Clients table:

 dbDelete("tblClients", "ClientName='TEST1'")

For more information on using database scripting functions, refer to the online Help.

Creating SQL Statements

Some of Scripting's database functions enable you to use SQL (Structured Query Language) to retrieve and modify data stored in a database.

Constructing Basic SQL Statements

Most SQL statements contain three parts:

The action stage

Specifies the operation you want to perform on the data. For example, "SELECT"

The target stage

Selects the database fields and tables on which the action is performed. For example, "* FROM tblClients" (all records from the table called tblClients).

The criteria stage

Specifies which records from the selection are to be included or excluded in the action. For example, "WHERE ClientName LIKE'VEC%'"

For example:

 SELECT * FROM tblClients WHERE ClientName LIKE 'VEC%'

This SQL statement selects all the records from the tblClients table, where the ClientName field starts with the letters 'VEC'.

In addition to using SELECT statements to retrieve data, PC-Duo enables you to use UPDATE statements and DELETE statements to modify the data in your database.

Operator	Description
=	Equal to
<>	Not equal to
<	Less than
>	Greater than
<=	Less than or equal to
>=	Greater than or equal to
LIKE	A more flexible version of "equal to"

Using Wildcards in SQL Statements

The percent symbol ( % ) can represent any character (number, letter, or punctuation), or set of characters in a string.

Logical and Compound SQL Operators

You can use the following logical and compound Operators to create SQL Statements:

Operator	Description
AND	Joins two or more conditions, and displays a row only if that row's data satisfies ALL conditions listed.
OR	Joins two or more conditions, and returns a row if any of the conditions listed hold true.
IN	Simplifies creating compound statements by enabling you to create a list of possible matches.
BETWEEN	Specifies the outer values of a range.
NOT	Usually positioned before Operators such as IN, BETWEEN or LIKE, NOT is used to exclude criteria.

AND and OR operators can be combined in a single SQL statement. In such cases, SQL evaluates all of the conditions, then evaluates the ANDs, and then evaluates the ORs (where both operators evaluate left to right).

Power Management Scripts

You can make use of PC-Duo's Power Management features from scripts.

Waking up Clients from a Script

To wake up a remote PC using its Client name, use the following function. You must substitute the Client PC name in place of nameofclient:

 WakeUpClient(nameofclient, WU_CLIENTNAME) 

Alternatively, you can wake a remote PC using its MAC address. For example:

 WakeUpClient ("0080c7046819",WU_MAC_ADDRESS)

Switching off Clients from a Script

There are several options available for shutting down PCs from a Script. When studying the examples below, replace nameofclient with the name of the remote PC you want to switch off.

To reboot a remote PC:

 Reboot(nameofclient, RB_REBOOT)

To log off a remote Windows NT4, 2000, XP or 2003 system:

 Reboot(nameofclient, RB_LOGOFF)

To shut down Windows on a remote PC:

 Reboot(nameofclient, RB_SHUTDOWN)

To switch off a remote PC (without shutting down Windows):

 Reboot(nameofclient, RB_POWEROFF)

To switch off or power down the currently connected Client in a Script, omit the Client name parameter, for example:

 Reboot(RB_RB_REBOOT) Reboot(RB_LOGOFF) Reboot(RB_SHUTDOWN) Reboot(RB_POWEROFF)

Exiting The Script Editor

You can exit the Script Editor using the File, Exit menu command, or by clicking on the close button in the top right corner of the Script Editor application window.

The Scripting Agent

Scripting in PC-Duo offers many advantages over manually performing tasks. As well as freeing up the Control user, the ability to schedule when Scripts run enables you to perform tasks overnight when your network or the Client PCs may not be in use.

The PC-Duo Scripting Agent enables you to schedule the Scripts created in the Script Editor. To start the Scripting Agent, click the Start button in the Taskbar to display the Start menu, then choose the Programs, PC-Duo, Script Agent command.

If the Script Editor application is displayed, you can start the Scripting Agent by choosing the Options, Run Scripting Agent menu command.

The Scripting Agent window displays all the Scripts Schedules managed by the Scripting Agent.

Additional details are displayed alongside each Script Description in the Script List:

• The file and path of the Script file.
• The date and time the Script is next scheduled to run.
• The date and time the Script was last run.
• The Result produced by the Script the last time it was run.
• Any error generated by the Script the last time it was run. (If an error was generated, a small red symbol is displayed to the left of the Script Schedule).

Adding a New Script Schedule

You can add new Script Schedules using the Add Schedule dialog. This dialog contains four tabs:

General

enables you to specify a Script file and give the Script a description.

Which Days?

specifies the dates when a Script is to be run.

What Time

specifies the times when a Script is to be run on the specified date(s).

Advanced

gives you the option of running an application after the Script has finished.

To Add a New Script Schedule:

1. Display the Scripting Agent window, then choose the Script, Add command, or click the Add button in the Toolbar.
2. In the Add Schedule dialog, ensure the General tab is displayed.
3. Enter a description for the Script Schedule (not the Script itself) in the Description text box.
4. Enter the file name of the Script in the Script text box. If you are not sure of the exact file name, click the Browse button (on the right of the text box), and select the file name from the Open dialog.
5. Click the Which Days? tab, then use the options to specify when you want to run the Script you selected in the General tab.
6. Click the What Time? tab and use the options to specify the times on which you want to run the Script.
7. If you want to run a specific application after the Script has finished, click the Advanced tab, then select the Run Application on Successful completion check box, and enter the name of the Application in the Application box. (Use the ellipsis (...) button to browse for the application file name.)
8. When you have finished specifying the schedule information, click the OK button to return to the Scripting Agent window. The Script Schedule is displayed in the Script List.

Viewing Script Schedule Properties

You can view and amend Script Schedules using the Properties for Schedule dialog. Its options are identical to those in the Add Schedule dialog.

To View Script Schedule Properties:

1. In the Scripting Agent window, choose the Script, Properties command, or click the Properties button in the Toolbar.
2. In the Properties for Schedule dialog, use the General tab to view or change the Script Schedule's Description, and the Script file on which the Schedule is based.
3. Use the Which Days? And What Time? tabs to view or change the Script Schedule.
4. Use the Advanced tab to specify an application to be run after the Script has finished.

Deleting Script Schedules

When you delete a Script Schedule, you are not deleting the Script file on which the Schedule is based.

To Delete a Script Schedule:

1. In the Script List in the Scripting Agent window, select the Script Schedule you want to delete.
2. Choose the Script, Delete command, or click the Remove button in the Toolbar.
3. In the confirmation dialog, click the Yes button to delete the schedule.

Viewing Log Files

The Scripting Agent stores two types of log files:

Scripting Agent Log File

records events relating to the Script Agent application, such as when the application has been started and closed, and which Scripts were run.

Individual Script Log Files

record whether the Script ran successfully and any error messages. These files are created when each Script is run.

You can view both types of Log File from the Scripting Agent application.

Viewing Scripting Agent Log Files

The Scripting Agent records when it was started and closed, which Scripts were run, whether the Scripts ran successfully and any error messages that were generated. To view the Scripting Agent's log file, choose the Options, View Log File command.

Viewing Script Log Files

You can use the Scripting Agent to display a Script's own, individual log file. To view a Script's log file, select the Script in the Script List, then click the View Log button in the Toolbar.

You can also view a Script's log file by right-clicking on the Script in the Script List, then choosing View Log from the shortcut menu.

Minimizing And Exiting the Scripting Agent

You can exit the Scripting Agent using the Script, Exit menu command, or by clicking the close button in the top right corner of the Script Agent application window. However, you must leave the Scripting Agent application running for it to perform its scheduled tasks.

Use the Options, Hide when minimized command to display Script Agent as a small icon in the Taskbar's system tray. When the Scripting Agent is minimized, there is less chance of the Script Agent being closed accidentally.

If you want to maximize the Scripting Agent application when it is minimized, double-click the Scripting Agent icon in the Taskbar's system tray.

Running Scripts from the Control

You can run Scripts directly from the Control application in two ways:

• By selecting the Scripting folder in the Control window's Tree View, and double-clicking on a Script in the List View.
• By selecting a Script in the List View, and choosing the Tools, Scripting, Run Script menu command.

To add more Scripts to the Scripting folder, use the Script Object Wizard. To start the Wizard, choose the Tools, Scripting, Add Script Object menu command. You can then name and locate a Script to add to the Scripting folder.

If you want to amend the Script Object settings, use the Tools, Scripting, Script Properties menu command. You can also launch the Script Editor to edit your Scripts by choosing the Tools, Scripting, Edit Script menu command.

Vector Networks http://www.vector-networks.com Voice: +44 (0) 1827 67333 Fax: +44 (0) 1827 67068 info@vector-networks.co.uk