Main script - ct. variables and functions

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

Variables

ct.ScheduleNumber	The current schedule number.
ct.Devices	A pipe (|) delimited string of devices to connect to (i.e. the devices associated with the current schedule).
ct.ScriptFileClient	A string variable to store the file name of the client script file that is used by the activity.
ct.QuitNow	A variable that is checked in a number of places within an activity to stop it running. For example, it is set to 1 when the 'STOP' button is pressed while an activity is running. This variable can only be referenced from within an activity Main Script. Use the cl.QuitNow client variable is referencing within the Client Scripts.

Functions and Sub routines - Summary list

General and File

ct.Log	Sends a line of text to the Infolog.txt file and Info Log pane
ct.ReadFromFile	Read in contents of a given file
ct.ReplaceFilenameVariables	Replace filename variables in report filenames to real text values.
ct.CreateMasterTable	Creates a master table file.
ct.CreateAndSendReport	Creates report files (.txt .html, etc.) and sends by email.
ct.RemoveClientResults	Removes existing client temporary .txt files within the \ClientTemp folder.

Activity

ct.MarshalThreads	Manages the client threads used within the activity schedule.
ct.DBScheduleGetField	Get activity field value from the CatTools database.

Device

ct.RemoveHeader

Removes the first line of data from within a data block.

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.

ct.Log(sDevice, iPriority, sMessage)

This sub routine sends a line of text to the Infolog.txt file and Info Log pane. It has three input parameters:

sDevice	The name of the device as a string. If an empty string, or VBNullString, then the string value is "CatTools" referring to an internal application related log message rather than a device specific message.
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 1 (error) message for CatTools, rather than any specific device, such as sDevice= "", with the text "No devices have been selected".

ct.Log "", 1, "No devices have been selected"

ct.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 client function cl.ReadFromFile, but can only be called from within an activity Main 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 file called "ReportData", removing the first row header row.

Dim sReportFile
Dim sReportData 

' Get the file name and path from the activity settings and replace any filename variables.
sReportFile = ct.DBScheduleGetField(ct.ScheduleNumber, "ReportFile")
sReportFile = ct.ReplaceFilenameVariables("", ReportFile)

' Read the contents of the report file, remove the first line of data (header row) and save the results to sReportData variable.
sReportData = ct.RemoveHeader(ct.ReadFromFile(sReportFile))

ct.ReplaceFilenameVariables(sDeviceName, sFileName) As String

This function is used to replace any filename variables in the report filename to the actual text values. It returns the modified string with the filename variables replaced. It has two input parameters:

sDeviceName	String value for the device name. Set sDeviceName to be an empty string ("") when you are translating an activity Report file name, as these should not contain device specific filename variables.
sFileName	String of the filename and path of the file being checked.

Example

Get the report filename for an activity and perform any filename variable replacements, then store the value in a string variable.

sReportFile = ct.DBScheduleGetField(ct.ScheduleNumber, "ReportFile")
sReportFile = ct.ReplaceFilenameVariables("", sReportFile)

ct.CreateMasterTable(sReportFile, sHeader, bOverwrite, sDeviceList, sClientFilePrefix, sTableFormat) As Boolean

This function is used to create the master table file. If successful, it returns a value of True, else if not then returns False. It has six input parameters:

sReportFile	String value of the report/master table file name and path to create
sHeader	Tab delimited string for the report header as defined in the activity Main Script.
bOverwrite	Boolean value. If 0 (False) the file will be appended to, otherwise it is overwritten.
sDeviceList	Pipe (|) delimited string of devices associated with the current schedule (use the "ct.Devices" variable)
sClientFilePrefix	File name prefix string for the temporary client (device) files that the activity creates in \ClientTemp in order to consolidate for the Master table file.
sTableFormat	Pipe (|) delimited string used for those activities where you can modify the table definition output (change column names; include/exclude columns from the output; and change the table column order: For example, the Options tab of the Report.SNMP.System Summary activity).

Example

Create the master table for a version report. Get the Report file name and Overwrite values from the activity settings in the database; and define the report header. Use a prefix of "CustomReportTemplate" for each temporary client (device) file.

Dim sReportFile
Dim bOverwrite
Dim sHeader

sReportFile = ct.DBScheduleGetField(ct.ScheduleNumber, "ReportFile")
sReportFile = ct.ReplaceFilenameVariables("", ReportFile)

bOverwrite = ct.DBScheduleGetField(ct.ScheduleNumber, "ReportOverwrite")
sHeader = "Group" & vbTab & "Device Name" & vbTab & "IP Address" & vbTab & "Serial #" & vbTab & _"Processor" & 
vbTab & "IOS" & vbTab & "Uptime"

' Create the master table
bRetVal = ct.CreateMasterTable(sReportFile, sHeader, bOverwrite, ct.Devices, "CustomReportTemplate", "")

ct.CreateAndSendReport(sScheduleName, sHeader, sData, sReportFile)

This sub routine is used to create the report files (.txt .html, etc.) and if the relevant options are set, it will also send the reports by email. It has four input parameters:

sScheduleName	The schedule name used for the report title, and email message subject title.
sHeader	Tab delimited string for the report header as defined in the activity Main Script.
sData	String of the report data.
sReportFile	String value of the report file name and path to create.

Example

Create a simple version report. Get the Activity name and Report file name from the activity settings in the database; and define the report header.

Dim sClientFile
Dim sScheduleName
Dim bOverwrite
Dim sReportFile
Dim sHeader

' Prefix for temporary client file filenames
sClientFile = "CustomReportTemplate"

' Get the schedule name from the activity settings
sScheduleName = ct.DBScheduleGetField(ct.ScheduleNumber, "Name")

' Get overwrite option value
bOverwrite = ct.DBScheduleGetField(ct.ScheduleNumber, "ReportOverwrite")

' Get report file name
sReportFile = ct.DBScheduleGetField(ct.ScheduleNumber, "ReportFile")
sReportFile = ct.ReplaceFilenameVariables("", ReportFile)

' Define the report header
sHeader = "Group" & vbTab & "Device Name" & vbTab & "IP Address" & vbTab & "Serial #" & vbTab & _"Processor" & 
vbTab & "IOS" & vbTab & "Uptime"

' Create the master table
Call ct.CreateMasterTable(sReportFile, sHeader, bOverwrite, ct.Devices, sClientFile, "")

' Call CatTools function to create and send the report
Call ct.CreateAndSendReport(sScheduleName & " (Custom Template Report)", sHeader,ct.RemoveHeader
(ct.ReadFromFile(sReportFile)), sReportFile)

' Finally, clean up by deleting any temp client files
Call ct.RemoveClientResults(sClientFile)

ct.RemoveClientResults(sClientFile)

This sub routine removes any existing client temporary .txt files within the \ClientTemp folder, with a filename beginning with the string value of sClientFile. It has one input parameter:

sClientFile

String value of the file names to find.

ct.MarshalThreads(ByVal sDeviceList As String, ByVal sScriptFile As String, ByValsFunctionName As String, ByVal lMaxProcessCount As Long, ByVal sUniqueFileID AsString)

This sub routine manages the client threads used within the activity schedule. It has five input parameters:

sDeviceList	Pipe (|) delimited string of devices associated with the current schedule (use the "ct.Devices" variable for this parameter).
sScriptFile	String of the filename of client script file to use (specify the "ct.ScriptFileClient" variable for this parameter).
sFunctionName	String of the Function name within the client script file to use (normally this should be "Client").
lMaxProcessCount	Maximum number of client threads to use for the activity (this will be automatically restricted by your Edition of CatTools).
sUniqueFileID	File name prefix string for the temporary client (device) files that the activity creates in \ClientTemp within the activity.

Example

Start the client threads for a simple version report. Get the maximum client threads from the activity settings in the database.

Dim lMaxClientThreads 

' Get the number of client threads from the activity settings
lMaxClientThreads = ct.DBScheduleGetField(ct.ScheduleNumber, "ClientThreads")

' Start the threads
Call ct.MarshalThreads(ct.Devices, ct.ScriptFileClient, "Client", lMaxClientThreads, "CustomReportTemplate")

ct.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 client function cl.DBScheduleGetField, but can only be called from within an activity Main 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

Get the report filename for an activity and store the value is the string variable sReportFile.

sReportFile = ct.DBScheduleGetField(ct.ScheduleNumber, "ReportFile")

ct.RemoveHeader(sData) As String

This function is used to remove the first line of data in a given block of data. It does so by locating the first instance of a vbCrLf, and removes everything up to and including it. The function returns a string with the first data line removed. It has one input parameter:

sData

String of the data to manipulate.