|
Custom device script cl. variables and functions |
Top Previous 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.
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:
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:
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:
Function return values:
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:
Function return values:
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:
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:
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:
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.
It has three optional input parameters passed by value:
cl.SendData(sDataToSend) This function sends the specified text to the device.
It has one input parameter:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||