Client script - cl. variables and functions

 Top  Previous  Next

Below is a list of CatTools client 'cl.' variables, functions and sub routines, with some examples of how to implement them in your custom activity client script files.   This is not a full set of all the internal client variables and functions used within the CatTools application, however it contains details of those from within the client script template files, plus a few additional ones which may be useful when creating your custom activity client scripts.

 

 

 

VARIABLES

 

cl.AppPath

The application path (install directory) of the CatTools program

cl.ScheduleNumber

The current schedule number

cl.DeviceName

The name of the device currently connected to

cl.TelnetConnectionStatus

The connection status for the instance of the (protocol engine control) client thread.

 

Example:  Test current client connection status and exit function if status is not 'OK'.

 

If StrComp(cl.TelnetConnectionStatus, "OK", vbTextCompare) <> 0 Then Exit Function

 

cl.QuitNow

A variable that is checked in a number of places within an activity to stop it running.

It is set to 1 (for example) when the 'STOP' button is pressed while an activity is running.

This variable can only be referenced from within activity Client Scripts.

Use the ct.QuitNow variable to reference within Main Scripts

 

 

 

FUNCTIONS & SUB ROUTINES - Summary list

 

 

 

General & file

 

 

 

cl.Log

Sends a line of text to the Infolog.txt file and Info Log pane

cl.LogToFile

Writes data to a file

cl.FileExists

Checks for the existence of a file

cl.CreateFile

Create a new file using a given filename and path

cl.DeleteFile

Delete a file using a given filename and path

cl.ReadFromFile

Read in contents of a given file

cl.ReplaceClientFilenameVariables

Replace filename variables in client report filenames or meta variables with real text values

cl.SaveResults

Save results to a temporary .txt file within the \ClientTemp folder

 

 

Activity

 

cl.DBCheckScheduleOption

Determine whether a particular option has been selected within a given activity

cl.DBScheduleGetField

Get activity field value from the CatTools database

 

 

Device

 

cl.DisconnectHost

Disconnect instance of the (protocol engine control) client thread from the end device

 

 

         

FUNCTIONS & SUB ROUTINES - Details and examples

 

The functions and sub routines listed in the above table are further detailed below with their input parameters, etc. and (in some cases) examples of their usage are provided.

 

 

cl.Log (iPriority, sMessage)

This sub routine sends a line of text to the Infolog.txt file and Info Log pane.

 

It has two input parameters:

 

iPriority

Integer range 1 to 4 representing the logging 'level' for the line being sent. 1=Error, 2=Warning, 3=Information, 4=Debug

sMessage

Message text of the line being sent

 

Example:  log a level 3 (info) message if the 'Use alternate command' field in the activity Options tab is empty.

 

Dim sAltCommand

 

sAltCommand = cl.DBScheduleGetField(cl.ScheduleNumber, "OptionsString1")        

If Len(Trim(sAltCommand)) = 0 Then

cl.Log 3, "No alternate command specified"

End if

 

 

 

cl.LogToFile (sFilename, sData, bAppend)

This sub routine writes data to a given file.

 

It has three input parameters:

 

sFileName

String of the filename and path of the file to write data to

sData

String of data to write

bAppend

Boolean value. If bAppend is NOT 0 (i.e. not False), then the file will be appended to

 

Example:  log a level 2 (warning) message to the Info Log and write a line to a text file in the Reports folder if the 'Use alternate command' field in the activity Options tab is empty.

 

Dim sLogResultsFile

Dim sAltCommand

 

sLogResultsFile = cl.AppPath & "Reports\" & cl.UniqueFileID & ".txt"

sAltCommand = cl.DBScheduleGetField(cl.ScheduleNumber, "OptionsString1")

 

If Len(Trim(sAltCommand)) = 0 Then

cl.Log 2, "No alternative command specified"

Call cl.LogToFile(sLogResultsFile, "No alternative command specified in activity Options tab", 1)

End if

 

 

 

cl.FileExists(sFileName) As Boolean

This function checks for the existence of a given file.  The function returns True if the file was found, False if not.

 

It has one input parameter:

 

sFileName

String of the filename and path of the file that existence is being tested for

 

 

 

cl.CreateFile(sFileName) As Boolean

This function is used to create a new file using the given filename and path.  The function returns True if the file already exists, or the file creation was successful, else it returns False.

 

It has one input parameter:

 

sFileName

String of the filename and path of the file to create

 

 

 

cl.DeleteFile(sFileName) As Boolean

This function is used to delete a file using the given filename and path.  The function returns True if the file has been deleted successfully, else it returns False.

 

It has one input parameter:

 

sFileName

String of the filename and path of the file to delete

 

 

 

cl.ReadFromFile(sFileName) As String

This function is used to read in the contents of a given file.  The function returns a string of the file data.

It performs the same operation as the CatTools function ct.ReadFromFile, but can only be called from within an activity Client Script.

 

It has one input parameter:

 

sFileName

String of the filename and path of the file to read in the contents of

 

Example:  read in the contents of a given file (in this case a list of CLI commands).

 

Dim sFileName

Dim sCommandList          

 

If cl.DBCheckScheduleOption(cl.ScheduleNumber, 1) = 0 Then

' Option selected to load CLI commands to send to device from a file

sFileName = cl.DBScheduleGetField(cl.ScheduleNumber, "OptionsString2")

sCommandList = cl.ReadFromFile(sFileName)

End If

 

 

 

cl.ReplaceClientFilenameVariables(sData) As String

This function is used to replace any filename variables in the client report filenames or meta variables in the commands to be sent to the device, with the actual text values. It returns the modified string with the variables replaced.

 

It has one input parameter:

 

sData

String of the filename and path of the file; or command list being checked

 

Example:  replace any filename variables of a given file, then read in its contents (in this case a list of CLI commands).  Next, replace and meta variables within the command list.

 

Dim sFileName

Dim sCommandList          

 

If cl.DBCheckScheduleOption(cl.ScheduleNumber, 1) = 0 Then

         

' Option selected to load CLI commands to send to device from a file

sFileName = cl.DBScheduleGetField(cl.ScheduleNumber, "OptionsString2")

         

' Replace any filename variables

sFileName = cl.ReplaceClientFilenameVariables(sFileName)

         

' Read in the file contents

sCommandList = cl.ReadFromFile(sFileName)

                 

' Replace meta (command) variables with values

sCommandList = cl.ReplaceClientFilenameVariables(sCommandList)

 

End If

 

 

 

cl.SaveResults(sData, bAppend)

This sub routine saves the results to a temporary .txt file within the \ClientTemp folder

 

It has two input parameters:

 

sData

String of data to write

bAppend

Boolean value. If bAppend is 0 (False), then the file will be overwritten, otherwise it is appended to

 

Example:  save current device response (sResults) to a temporary .txt file overwriting any existing data.

 

Call cl.SaveResults(sResults, 0)

 

 

 

cl.DBCheckScheduleOption(lScheduleNumber, lOptionNumber) As Long

This function is used to determine whether particular options have been selected within a given activity.

 

It has two input parameters:

 

lScheduleNumber

The current schedule number as a Long

lOptionNumber

The option item within the activity we are checking as a Long.

lOptionNumber must be between 1 and 10 (inclusive)

 

Example:  check an activity (in this instance a Device.CLI.Send commands activity) to see if the output of the command(s) should be emailed.

 

lRetVal = cl.DBCheckScheduleOption(cl.ScheduleNumber, 8)

If lRetVal = 1 then

' code to email commands goes here...

End if

 

 

 

cl.DBScheduleGetField(lScheduleNumber, sFieldName)

This function is used to get a field value from the CatTools database for a given activity.

It performs the same operation as the CatTools function ct.DBScheduleGetField, but can only be called from within an activity Client Script.

 

It has two input parameters:

 

lScheduleNumber

The current schedule number as a Long

sFieldName

The field name in the database we want to get the value of as a String

 

Example:  (used in conjunction with the cl.DBCheckScheduleOption function above) check an activity to see if the 'Use alternate command' check-box is selected in the activity Options tab.  If it is, it gets the value from the database for the alternate command we want to send.

 

' Check the option 1 check-box to see if selected - i.e. set to 1

If cl.DBCheckScheduleOption(cl.ScheduleNumber, 1) = 1 Then

' Get value from database for associated string field (being field "OptionsString1" in the database) to set a variable value

sAltCommand = cl.DBScheduleGetField(cl.ScheduleNumber, "OptionsString1")

End If

 

 

 

cl.DisconnectHost

This sub routine is used to disconnect the instance of the (protocol engine control) client thread from the end device.

If should be called after the device has been logged out of to disconnect the client thread gracefully.