Custom device script cl. variables and functions for Kiwi CatTools

The custom device template script contains many references to the internal CatTools client variables and calls to client functions. These variables and functions can be identified by their 'cl.' prefix.

Although the functions and variables are not documented within the template script itself, to understand what each one is used for and, in the case of the functions, understand the parameters they require and what their return values are, each variable and function exposed in the custom device template file is detailed below.

Variables

Device configuration variables (read from the device setup screen tabs)

Device Info tab

Variable	Description	Field Type
cl.CurDevName	Unique name assigned by user to refer to device.	Name field
cl.CurDevTelnet	The device connection method, i.e. Telnet or SSH.	Method field
cl.CurDevGroup	The logical group that this device belongs to.	Group field
cl.CurDevHostAddress	IP address or host name of the device.	Host Address field
cl.CurDevModel	The device model /series number.	Model field
cl.CurDevType	The CatTools device type.	Device Type field
cl.CurDevFilename	The base file name to use for this device (unique)	File Name field
cl.CurDevConnectVia	The name of another device to connect to first	Connect via field
cl.CurDevTelnetPort	Port number to use	Port field

Passwords tab

Variable	Description	Field Type
cl.CurDevVTYPass	Device VTY password	VTY password field
cl.CurDevEnablePass	Device Enable password	Enable password field
cl.CurDevPrivilegeLevel	Device Enable mode privilege level	Privilege level field
cl.CurDevAAAUsername	Device Username	Username field
cl.CurDevAAAPassword	Device Password	Password field
cl.CurDevRequireVTYLogin	Device requires Password only to log in (Initial login requires password tick box field)
cl.CurDevLoginUsesAAA	Device requires Username and Password to log in (Initial login requires username/password tick box field)
cl.CurDevEnableUsesAAA	Device requires Username and Password to enter Enable mode (Enable mode requires username/password tick box field)
cl.CurDevConsolePass	Device console (com port connection) password	Console password field
cl.CurDevSSHUsername	SSH username	SSH Username field
cl.CurDevSSHPassword	SSH Password	SSH Password field
cl.CurDevSNMPRead	SNMP Read community name	SNMP Read field
cl.CurDevSNMPWrite	SNMP Write community name	SNMP Write field

Prompts tab

Variable	Description	Field Type
cl.CurDevVTYPrompt	Device VTY custom prompt assigned by user to device	VTY Prompt field
cl.CurDevEnablePrompt	Device Enable mode custom prompt assigned by user to device	Enable Prompt field
cl.CurDevConsolePrompt	Device Console port custom prompt assigned by user to device	Console Prompt field
cl.CurDevAAAUserPrompt	Device AAA Username custom prompt assigned by user to device	Username Prompt field
cl.CurDevAAAPassPrompt	Device AAA Password custom prompt assigned by user to device	Password Prompt field

Contact info tab

Variable	Description	Field Type
cl.CurDevAddress1	Location of the device	Address1 field
cl.CurDevAddress2	Location of the device	Address2 field
cl.CurDevAddress3	Location of the device	Address3 field
cl.CurDevContactName	The name of the person responsible for this device	Contact Name field
cl.CurDevContactPhone	How to contact the person responsible for this device	Contact Phone field
cl.CurDevContactEmail	How to contact the person responsible for this device	Contact Email field
cl.CurDevContactOther	Any additional contact info	Contact Other field
cl.CurDevAlertEmail	Who to notify by e-mail of any alarms or alerts for this device	Alert e-mail field

Extra Info tab

Variable	Description	Field Type
cl.CurDevSerialNumber	The serial number of this device	Serial Number field
cl.CurDevAssetTag	Asset tag information	Asset Tag field
cl.CurDevIdentification	Identification info for this device	Identification field
cl.CurDevSerialOther	Any other serial number information	Other info field
cl.CurDevActivitySpecific1	Information specific to a particular activity	Activity Specific 1 field
cl.CurDevActivitySpecific2	Information specific to a particular activity	Activity Specific 2 field

Other variables

Variable	Description
cl.RxBuffer	String of response data sent from the device
cl.ScheduleNumber	The current schedule number
cl.DeviceHostnameID	Device host name as recovered from the device after successful login
cl.DeviceVTYPrompt	The host name and ending with DEVICE_STANDARDPROMPT
cl.DeviceEnablePrompt	The host name and ending with DEVICE_PRIVILEGEDPROMPT
cl.DeviceConfigPrompt	The host name and ending with DEVICE_CONFIGPROMPT

Functions

The follow table lists a summary of functions available in custom device script files.

General and File

Variable	Description
cl.Initialise	Initializes (or defaults) cl. variables
cl.Delay	Force CatTools to pause for a given amount of time
cl.GetUniqueDeviceFileName	Generates unique filename in the \ClientTemp folder based on the device
cl.DBMetaCmd	Checks if a command is a database meta command, and then processes it
cl.UtilityMetaCmd	Checks if a command is a utility meta command, and then processes it
cl.Log	Sends a line of text to the Infolog.txt file and Info Log pane
cl.LogToFile	Writes data to a file

Activity

Variable	Description
cl.CatToolsNoSupport	Called for activities not supported by the device script
cl.DBCheckScheduleOption	Determine whether a particular option has been selected within a given activity

Device

Variable	Description
cl.FlushRxBuffer	Clears the cl.RxBuffer string. Used to clear previous response data before receiving next data
cl.DetermineHostname	Establishes and sets the device hostname and prompts cl.variables
cl.SendData	Sends text to device
cl.SendAndWaitForEcho	Sends text to device and waits for echo
cl.SendAndWaitForPrompt	Sends text to device, waits for an echo and then device prompt
cl.WaitForData	Waits for a specific data string to returned from the device
cl.WaitForMultData	Waits for any one of a range of specific data strings to be returned from the device

Text Manipulation

Variable	Description
cl.ReplaceText	Replace a substring within a given string of data, with a new substring
cl.TextRemoveBlankHeaderLines	Remove blank header lines from the beginning of a string (e.g. a device output buffer)
cl.TextRemoveLinesContainingText	Remove lines which contain a specific substring of text
cl.TextInText	Return start position of a substring within a string
cl.TextRemoveTextUpTo	Trim a text from a string up to or including a specified substring

Details and examples of functions

The functions listed are further detailed below with their input parameters and, where applicable, examples of their usage are provided.

cl.Initialise()

This function initializes (or defaults) cl.variables as follows:

cl.DeviceHostnameID = ""
cl.DeviceVTYPrompt = ""
cl.DeviceEnablePrompt = ""
cl.DeviceConfigPrompt = ""
cl.WaitForEcho = True
cl.WaitForTime = 0

cl.Delay(lDuration)

This function forces CatTools to pause for a given amount of time.

It has one input parameter:

lDuration

Amount of time to wait for (in seconds)

cl.GetUniqueDeviceFileName(sFolderName, sPrefixName) As String

This function generates a unique file name in the \Program Files (x86)\CatTools3\ClientTemp folder based on the device. The function has a return value of String being the path and a unique file name.

It has two input parameters passed by value, and two optional parameters:

sFolderName	String value to append to beginning of file name. This parameter can accept an empty string "".
sPrefixName	String value to append after sFolderName within the file name

Example use case

Write an output to a temporary file in the \ClientTemp folder:

' create the unique filename using only the prefix 'CLI'
sClientResultsFile = cl.GetUniqueDeviceFileName("", "CLI")
' write the data in the RxBuffer to a file in \ClientTemp folder using the filename just created.
cl.LogToFile sClientResultsFile, cl.RxBuffer

cl.DBMetaCmd(sCmd) As Long

This function checks a command to see if it is a database meta command. If it is, then CatTools tries to process it. A database meta command enables you to directly update a field in a table in the CatTools database as part of an Activity. They are not run on a device. The syntax for a database meta command is %ctDB:tablename:fieldname:value

The function has one input parameter:

sCmd	String value of the command being evaluated

Function return values:

0	Command if not a database meta command
1	Command evaluates as a database meta command and is processed successfully (a debug message also sent to the Info Log)
-1	Command evaluates as a database meta command, but fails to be processed (an error message also sent to the Info Log)

Example use case:

Check whether command to send is a database meta command. If it isn't (i.e. it is a device command) then send it to device.

lRetVal = cl.DBMetaCmd(sCmd)
If lRetVal = 0 Then 'not a database meta command so send it
cl.FlushRxBuffer
' send command to device and wait for echo
bRetVal = cl.SendAndWaitForEcho(sCmd)
If bRetVal then
' command has been echoed, so lets execute it
cl.SendData vbCr
End if
End If 

cl.UtilityMetaCmd(sCmd) As Long

This function checks a command to see if it is a utility meta command. If it is, then CatTools tries to process it. A utility meta command enables you to set various options for use in the Device.CLI.Send commands and Device.CLI.Modify Config activities. The activities are not run on a device. Utility meta commands change the default behavior of some of the internal CatTools functions.

The function has one input parameter:

sCmd	String value of the command being evaluated

Function return values:

0	command if not a utility meta command
1	command evaluates as a utility meta command and is processed successfully (a debug message also sent to the Info Log)
-1	command evaluates as a utility meta command, but fails to be processed (an error message also sent to the Info Log)

Example use case

Check if the command to send is a utility meta command. If the command is not meta, then send it to the device.

lRetVal = cl.UtilityMetaCmd(sCmd)
If lRetVal = 0 Then 'not a utility meta command so send it
cl.FlushRxBuffer
' send command to device and wait for echo
bRetVal = cl.SendAndWaitForEcho(sCmd)
If bRetVal then 
' command has been echoed, so lets execute it
cl.SendData vbCr
End if
End If

cl.Log(iPriority, sMessage)

This function 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 use case

Log a level 4 (debug) message sending the text "Login Device Template: Custom Device 1". Assume Const SCRIPT_NAME from the Device Template script and that you have named your device Custom Device 1 in the Name field of the Device Info tab of the device setup screen.

cl.Log 4, "Login " & SCRIPT_NAME & ": " & cl.CurDevName

cl.LogToFile(sFilename, sData, bAppend)

This function writes data to a file.

It has three input parameters:

sFilename	String of the name and path of the file to write to
sData	String of data to write
bAppend	Boolean value (default or if unspecified is False). If True, then the file is appended. Otherwise it is overwritten

Example use case

Save current device response to temp.txt file on the C:\ drive.

cl.LogToFile "c:\temp.txt", cl.RxBuffer, 1

cl.CatToolsNoSupport()

This function is called for those activities not currently supported by the device script.

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

Example use case

Check an activity, in this case a Device.CLI.Send commands activity, to see if the output of the command should be emailed.

lRetVal = cl.DBCheckScheduleOption(cl.ScheduleNumber, 8)
If lRetVal = 1 then
'code to email commands goes here...
End if

cl.FlushRxBuffer()

This function clears the cl.RxBuffer string. This function is normally used to clear out any previous device response data before receiving the next chunk of response data.

cl.DetermineHostname(Optional ByVal vStandardPrompt As Variant, Optional ByVal vPrivilagedPrompt As Variant, Optional ByVal vConfigPrompt As Variant) As Boolean

This function establishes and sets the cl.variables listed below and returns a value of True if successful.

cl.DeviceHostnameID	The host name of the device (e.g. DevHost123), used as 'seed' for the prompts below.
cl.DeviceVTYPrompt	The host name and ending with DEVICE_STANDARDPROMPT	example: ??DevHost123>
cl.DeviceEnablePrompt	The host name and ending with DEVICE_PRIVILEGEDPROMPT	example: ??DevHost123#
cl.DeviceConfigPrompt	The host name and ending with DEVICE_CONFIGPROMPT	example: ??DevHost123(

It has three optional input parameters passed by value:

vStandardPrompt	Device standard mode prompt (or VTY prompt). If none specified then ">" is used as the default
vPrivilagedPrompt	Device privileged mode prompt (or Enable prompt). If none specified then "#" is used as the default
vConfigPrompt	Device configuration mode prompt (or VTY prompt). If none specified then "(" is used as the default

cl.SendData(sDataToSend)

This function sends the specified text to the device.

It has one input parameter:

sDataToSend

string of the data to be sent to the device

Example use case:

Send a carriage return to the device

cl.SendData vbCr

cl.SendAndWaitForEcho(sDataToSend) As Boolean

This function sends a text string to the device and waits for an echo. By waiting for an echo of the text string it ensures that the string we are expecting to send is actually the string that is sent. For example, there may be a case in which we send a string and the device doesn't echo back with it in its entirety, or it gets substituted / corrupted.

The function has a Boolean return value: True if string is echoed back as expected, False if not.

It has one input parameter:

sDataToSend

String of the data being sent to the device and expected to be echoed back

This function is sometimes followed by the function cl.SendData vbCr which then executes the echoed string on the device.

Example use case

Send a command to show the device running configuration and wait for an echo. If echoed, execute the command.

bRetVal = cl.SendAndWaitForEcho("show running-config")
If bRetVal then 
cl.SendData vbCr
End if

cl.SendAndWaitForPrompt(sDataToSend) As Boolean

This function sends a text string to the device and waits for an echo. If successfully echoed, the string is executed and the function waits for a valid device prompt to be returned (standard or privileged prompts). This function is normally called when executing a known valid command on a device with no output, for example, term len 0 to turn off output paging.

The function has a Boolean return value: TRUE if string is echoed back and you then receive one of the expected prompts after the command has been executed, and FALSE if not.

It has one input parameter:

sDataToSend

String of the data being sent, echoed and then executed on device

cl.WaitForData(sData, lTimeOut) As Boolean

This function waits for a given amount of time for the specific string data to be returned from the device. The function has a Boolean return value: True if string is found within the timeout period specified, False if not.

It has two input parameters:

sData	The string of data we are waiting to receive from the device
lTimeOut	The amount of time to wait for (in seconds)

Example use case

Send the command to exit config mode and then check if we have been returned to the Enable mode prompt within a 30 seconds timeout.

cl.SendData Chr(26) ' i.e. CTRL-Z
If cl.WaitForData('HostName1#', 30) = False Then
cl.Log 4, "Failed to exit Configure Terminal mode"
End if

cl.WaitForMultData(rgMult, Optional iChoices = 0, Optional lTimeOut = 0) As Long

This function waits for a given amount of time for any one of string data items defined in the range, to be returned from the device within the specified amount of time. The function has a return value of Long representing which item of string data it has found first. It returns 0 if none of the items are found within the given timeout value.

It has three input parameters:

rgMult	The range of possible string data items we are expecting back from the device
iChoices	(Optional) The count of the number of items we are looking for - excludes rgMult(0)item. Optional as this is now calculated by the function itself if not specified
lTimeOut	(Optional) The amount of time to wait for (in seconds). Optional parameter, if not specified then default CatTools internal timeout value is applied

Example use case

Wait for one of the device prompts to be returned within 30 seconds.

rgMult(1) = "HostName1>"
rgMult(2) = "HostName1#"
rgMult(3) = "HostName1(Config)"
iChoices = 3
lTimeOut = 30
iRetVal = cl.WaitForMultData(rgMult, iChoices, lTimeOut)
If iRetVal = 0 Then
cl.Log 4, "Failed to receive device prompt"
End if

To satisfy this case, you can also send:

cl.WaitForMultData(rgMult) 

which uses the default timeout within CatTools, or:

cl.WaitForMultData(rgMult, , lTimeOut)

which uses your specified timeout value. The function works out the iChoices value. If you are using the constant COMMAND_TIMEOUT to specify your timeout, then you can increase the timeout using:

Const COMMAND_TIMEOUT = 30 '(i.e. in seconds)
iTimeOutMultiplier = 2 '(increase by a factor of 2)
cl.WaitForMultData(rgMult, , COMMAND_TIMEOUT * iTimeOutMultiplier)

cl.ReplaceText(sData, sFind, sReplace) As String

This function replaces a substring within a given string of data, with a new substring. It replaces all substring occurrences with the new substring. The function has a return value of String being the new string of data with replacements. If no replacements are made, then the return string is the same as the original string. The function returns a null string if the length of the input parameter sData is 0.

It has three input parameters:

sData	String to be searched
sFind	The substring we want to replace
sReplace	The new substring we want to replace with

Example use case 1

Replace all occurrences of the substring "old text" with "new data" within the string object sData.

sData = cl.ReplaceText(sData, "old text", "new data")

Example use case 2

Remove nulls from within the string object sData.

sData = cl.ReplaceText(sData, Chr(0), "")

cl.TextRemoveBlankHeaderLines(ByVal sData) As String

This function is used to remove blank header lines from the beginning of a string, such as a device output buffer. It is used primarily for massaging the configuration data output from a device to create the backup file. It works through from the top of the output buffer string, removing lines containing just a carriage return <CR> or a line-feed <LF> (or both). The function has a return value of String being the 'trimmed' buffer string.

It has one input parameter passed by value:

sData

String we are manipulating

Example use case

Trim all the blank lines from the top of the buffer string object sConfigData.

sConfigData = cl.TextRemoveBlankHeaderLines(sConfigData)

cl.TextRemoveLinesContainingText(ByVal sData, ByVal sFind) As String

This function is used to remove lines from within the device output buffer which contain a specific substring of text. It is used primarily for massaging the output data from a device to create a text file or report. The function has a return value of String being the new buffer with the lines containing the substring removed.

It has two input parameters passed by value:

sData	String to be searched
sFind	Substring we are searching for

Example use case

Remove all config lines of data from the buffer string object sConfigData, containing the device paging prompt text for example --More--.

Const DEVICE_MORETEXT = "--More--"
sConfigData = cl.TextRemoveLinesContainingText(sConfigData, DEVICE_MORETEXT)

cl.TextInText(ByVal sData, ByVal sFind) As Integer

This function returns the start position of a substring within a string. If nothing is found, or the length of either input strings are 0, then the function returns 0.

It has two input parameter passed by value:

sData	String to be searched
sFind	Substring we are searching for

Example use case

Find the start position of the device header text. If the value is 0, the start position has not been found, so send a line to the Info Log.

Const DEVICE_CONFIGHEADERTEXT = "Generating configuration:"
iRetVal = cl.TextInText(sConfigData, DEVICE_CONFIGHEADERTEXT)
If iRetVal = 0 then
cl.Log 4, "Failed to find device configuration header text"
End if

cl.TextRemoveTextUpTo(ByVal sData, ByVal sFind, Optional bAndIncluding As Boolean = False, Optional bForwards As Boolean = True) As String

This function is used to trim a text from a string up to or including a specified substring. The trim can work in either direction, such as from the start of a file to the end, or from the end to the start. The function has a return value of String, being the new string with the relevant text removed, or if the substring sFind cannot be found then the original string sData is returned.

It has two input parameters passed by value, and two optional parameters:

sData	String to be searched
sFind	Substring we are searching for
bAndIncluding	(Optional) Boolean value: if set to True trims up to and including the substring text sFind. If False (default) then the substring sFind is not trimmed.
bForwards	(Optional) Boolean value: if set to True (default) trims from the start, or top, of the string we are searching. If False, the function trims from the end (or bottom) of the string backwards.

Example use case

Check output for header text and if found remove everything up to and including the header text.

Const DEVICE_CONFIGHEADERTEXT = "Generating configuration:"
If cl.TextInText(sConfigData, DEVICE_CONFIGHEADERTEXT) > 0 Then
sConfigData = cl.TextRemoveTextUpTo(sConfigData, DEVICE_CONFIGHEADERTEXT, True, True)
End If