Project: A script project is expected to grow to encompass more complex operations in the future so it needs to be written in procedures that are easy to port and test. For this example, we’ll define several routines to perform the steps of the Automated Download example, passing variables or defining local variables where appropriate.

Algorithm: In this example we will break the project down into several parts, each handled by a routine, and define variables to be passed between the routines where appropriate.

Relevant Commands and Functions:

BEGIN — Begins a command block
END — Indicates end of a command block
Labels — * indicates a target or start of a routine in script
ARGUMENTS — Specifies local variables to be created by a child routine
PERFORM — Branches execution to the specified target
RETURN — Resumes script execution past the current PERFORM command
IF …ELSE — Conditionally executes a command block
SWITCH — Branches execution to multiple command blocks
LEAVE — Branches execution from a command block
SHOW — Display each script command as it is executed.

See Also:

EXECUTE — Starts a script and does not return to the calling script
LAUNCH — Starts another application
RESTART — Branches execution to the first line of the executing script
SPAWN — Starts an independent script without interrupting the current script
GOTO — Branches execution to the specified target
WHILE — Conditionally executes a logical command
CONTINUE — Conditionally branches execution from a WHILE loop or SWITCH command
WHEN Commands — Asynchronous branching, as illustrated in Event Monitoring example

A Brief Example

SHOW

$time = "02:00:00 AM"
WAIT UNTIL $time
$Status = "Login Failed"
$SessionName = "unknown"
$Filename = "filename.dat"
PERFORM ConnectSession($Status, $SessionName)
SWITCH $Status
CASE "Ready": PERFORM DownloadFile($Filename)
LEAVE
CASE "Login Failed": PERFORM Message("Login Failed")
LEAVE
SWITCH END
RESTART

*ConnectSession($Status, $SessionName)
; Load and connect $SessionName SES file,
; and report back with a status value in $Status string
$SessionName = "Vax"
connect $SessionName
$Status = "Ready"
RETURN

*DownLoadFile($Filename)
IF EXISTS($Filename)
PERFORM RenameOldFile($Filename)
;Add code here to implement download
RETURN

*RenameOldFile($Filename)
; Add code here to rename the file $Filename
RETURN

*Message
ARGUMENTS ($string)
DIALOG
MESSAGE $string
BUTTON "OK" RESUME
DIALOG END
WAIT RESUME
DIALOG CANCEL
RETURN

This example breaks the project up into a smaller script plus four routines that perform operations for the script. Routines or procedures are defined by a label (starts with an * character) and end with the RETURN command. If any values or variables are to be passed to the routine, these are placed either on the procedure line in parentheses or in an ARGUMENTS command as the first line following the procedure line, as done in the Message routine above. To make use of the procedures, the PERFORM command is issued with the name of the routine and any values or variables to be passed to it. When a variable is passed, as in PERFORM DownLoadFile($filename), it is passed by reference and changes to the variable made in the routine are returned. When a value is passed, as with PERFORM Message("Login Failed"), it is passed by value.

A couple of points to note in this example: The routines/procedures can be before or after the PERFORM command which calls them. In our case, we put them at the bottom of the script, and make sure the CANCEL command is used at the end of the main script block so execution does not continue beyond the main SWITCH block. Script execution always begins with the first line of the script, so there is no need to define any special routine such as *Main. The RETURN command returns execution to the command following the last PERFORM command executed, so subroutines can be implemented as illustrated in the DownLoadFile routine above.

Further Development:

• With the PERFORM, EXECUTE, or SPAWN script commands, calling routines could extend to two or more script files with concurrent execution if desired.

Additional Examples:

Several examples use routines to break up a project into managable parts. See the ADDRBOOK example and DDECLNT for further illustration.