Submit a ticketCall us

Bridging the ITSM Divide
Integrated help desk and remote support software for faster resolution

Join us on Wednesday, November 29, 2017 at 11 a.m. CT, as we discuss the benefits of effectively integrating your help desk software with remote support solutions to help increase the efficiency of IT administration, improve communication, and decrease mean time to resolution (MTTR) for IT issues of all sizes. This directly impacts end-user satisfaction and your business’ bottom line. Register Now.

Home > Success Center > Kiwi CatTools > Kiwi CatTools 3.11 Administrator Guide > Devices > Creating a custom device > Custom device script cl. variables and functions

Custom device script cl. variables and functions

Table of contents
No headers
Created by Caroline Juszczak, last modified by Caroline Juszczak on Oct 03, 2017

Views: 79 Votes: 0 Revisions: 3

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)

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

 

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

 

 

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

 

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

 

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

 

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

 

Last modified

Tags

Classifications

Public