Documentation forKiwi CatTools

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