Client script - cl. variables and functions

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. 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

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

Functions and Sub routines

General and File

Activity

Device

Functions and Sub routines - Details and examples

The functions and sub routines listed in the above table are further detailed below with their input parameters and 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:

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:

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:

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:

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:

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:

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:

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:

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:

Example

Check an activity, in this instance a Device.CLI.Send commands activity, to see if the output of the commands 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:

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. It should be called after the device has been logged out of to disconnect the client thread gracefully.