Custom device script cl. variables and functions

Previous  Top  Next

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 (mainly to cut down the size of the script file), in order for you 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 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) Passwords tab 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) Prompts tab 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.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) Other variables 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 - Summary list

General & file cl.Initialise Initialises (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 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 cl.FlushRxBuffer Clears 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 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

FUNCTIONS - Detail and examples

The functions 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.Initialise()
This function initialises (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 filename in the \ClientTemp folder based on the device.
The function has a return value of String being the path and a unique filename.

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

sFolderName String value to append to beginning of filename. Can accept and empty string "" sPrefixName String value to append after sFolderName within the filename

Example: write the 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: 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.
They are not run on a device. Utility meta commands change the default behaviour 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: check whether command to send is a utility meta command. If it isn't then send it to 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: log a level 4 (debug) message sending the text "Login Device Template: Custom Device 1" (assume Const SCRIPT_NAME from 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 will be appended to otherwise it is overwritten

Example: save current device response to temp.txt file on 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: 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.FlushRxBuffer()
This function clears the cl.RxBuffer string. 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
The purpose of this function is to establish and set the cl. variables listed below and return a value of True if successful.

cl.DeviceHostnameID The host name of the device (e.g. DevHost123), used as 'seed' for following prompts:

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: 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 ensure that the string that we are expecting to send is actually the string that is sent (just in case 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 a 'cl.SendData vbCr' which then executes the echoed string on the device.

Example: send command to show the device running configuration and wait for an echo. If echoed, then 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, 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: send the command to exit config mode and then check if we have been returned to the 'Enable' mode prompt within 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: 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

   
You could also just 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 1: replace all occurrences of the substring "old text" with "new data" within the string object sData

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

Example 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 (e.g. 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: 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: remove all config lines of data from the buffer string object sConfigData, containing the device paging prompt text i.e. --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: find the start position of the device header text. If value is 0, we haven't found it 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, i.e. 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 will trim up to 'and including' the substring text sFind. If False (default) then the substring sFind will be not be trimmed bForwards (Optional). Boolean value; if set to True (default) will trim from the start (or top) of the string we are searching. If False, then the function trims from the end (or bottom) of the string backwards

Example: check output for header text and if found remove everything up to and including it

Const DEVICE_CONFIGHEADERTEXT = "Generating configuration:"

If cl.TextInText(sConfigData, DEVICE_CONFIGHEADERTEXT) > 0 Then

sConfigData = cl.TextRemoveTextUpTo(sConfigData, DEVICE_CONFIGHEADERTEXT, True, True)

End If