Script functions in Kiwi CatTools

Kiwi CatTools includes several built in functions available to Client scripts. Use the "cl." prefix to access a function from the client. For example:

cl.Log 1, "Expected response not received from command ..."

Functions

ConnectHost() As Boolean

• Attempts to connect to the current host specified in CurDevHostAddress.
  • True = the connection is successful.
  • A warning message is logged if a connection attempt fails.
• The connection is attempted three times before failing. After three failed attempts, an error message is logged.

ConnectHostSingleAttempt() As String

• Attempts to connect to the current host specified in CurDevHostAddress.
• If the connection is successful, a value of "OK" is returned. Otherwise the error description is returned.
• This function is called 3 times by ConnectHost.

ConvertToFilename(Filename as variant) As String

• Converts a device name into a suitable filename.
• Replaces any invalid characters in the filename with an underscore, including quotes and spaces. The following characters are considered invalid in a filename: "&+?:;,()=|\/<>*^%@

CreateFile(Filename) As Boolean

• Attempts to create the specified file even if the path does not exist.
  • If the file already exists, no action is taken.
  • If the file does not exist, the path and a file are created. The file is 0 bytes in length.

CurrentDateStamp(Format as long) as String

• Returns the current date formatted based on the value of "Format".
• Format values:
  • 0 = ISO Format (YYYY/MM/DD)
  • 1 = US Format (MM/DD/YYYY)
  • 2 = UK Format (DD/MM/YYYY)

CurrentDateTime(Format as long) as String

• Returns the current date and time formatted based on the value of "Format".
• Format values:
  • 0 = ISO Format (YYYYMMDDHHNNSS)
  • 1 = US Format (MMDDYYYYHHNNSS)
  • 2 = UK Format (DDMMYYYYHHNNSS)

CurrentDateTimeStamp(Format as long) as String

• Returns the current date and time without separators, formatted based on the value of "Format".
• Format values:
  • 0 = ISO Format (YYYY/MM/DD HH:MM:SS)
  • 1 = US Format (MM/DD/YYYY HH:MM:SS)
  • 2 = UK Format (DD/MM/YYYY HH:MM:SS)

DBCheckScheduleOption(ScheduleNumber, Option Number) As Long

• Returns the activity specific option check box value.
  • 0 = unchecked
  • 1 = checked.
• Each activity has 10 optional data values that can be set for the activity. Pass the activity number and an option value - from 1 to 10 - and the return value of the specific option check box is returned.
• Refer to the activity .ini file for details of each specific option.

Sub DBDevicesClearCurDevFields()

• Clears all the current device variables and sets them to "".

Sub DBDevicesGetAllFields(DeviceName)

• Locates the specified device in the database and loads all the fields into the CurDevXXX variables.
• To check if the function worked: check len(CurDevName) > 0

Function DBDevicesGetField(DeviceName, FieldName) as Variant

• Returns the data contained in the field "FieldName" of device "DeviceName" from the database file.
• Returns blank if the data retrieval fails.

Function DBScheduleGetField(ScheduleNumber, FieldName) as String

• Returns the data contained in the field "FieldName" of activity "ScheduleNumber" from the database.
• Returns blank if the data retrieval fails.

Function DeleteFile(Filename) As Boolean

• Deletes the specified file and returns true or false based on if the file exists after the delete attempt.
  • True = File deleted.
  • False = File still exists and was not deleted successfully.

Sub DisconnectHost()

• Closes the active connection to the current device

Function FileExists(Filename) As Boolean

• Tests to see if the specified file exists.
  • True = the file is found.
  • False = the file is not found.

Sub FlushRxBuffer()

• Flushes the data found in the receive buffer and waits until there is no further data being received from the active socket.

Sub InfoUpdate(Message)

• Sends an info update message back to the main program.

Sub LogToFile(Filename, Data, Append)

• Opens a file for writing. Writes the data stored in Data to the file.
  • Append = 1, the data is appended to the end of the file.
  • Append = 0, the file is overwritten with the new data.

Function Ping(Hostname As String, Timeout As Long, PingCount As Long, ProcessID As Long) As String

• Attempts to ping the host name and returns the results in the format:

  !!!!! TAB 100% TAB 10 TAB 100 TAB 80 or ..... TAB 0% TAB TAB TAB

  • Hostname is the IP address or hostname of the device to ping Timeout is in seconds. The default is 5 seconds.
  • PingCount is the number of Ping echo requests to send. Default is 5 pings.
  • ProcessID is the current processID (cl.ProcessID). This is used to identify the sent ping packets so that the responses can be tied back to the correct process that sent them.
• The min, max and average response times are calculated from any ping echoes received.
• The return data is tab delimited for easy parsing and reporting.

Function ReadFromFile(Filename) As String

• Reads the contents of the specified filename and returns the data as a string value.
• A "" value is returned if the file doesn't exist or contains no data.

Function ReplaceClientFilenameVariables(Filename) As String

• Replaces the %Variable% item with the associated value.
  • %AppPath% = cl.AppPath
  • %GroupName% = cl.CurDevGroup
  • %DeviceName% = cl.CurDevName
  • %DateISO% = cl.CurrentDateStamp(0) ("YYYY-MM-DD")

Sub SaveResults(Data, Append)

• Saves results data into separate files.
• The file name is created from the device name and UniqueFileID set in the Main script in the format:

  Filename = cl.AppPath + "\ClientTemp\" + UniqueFileID + ConvertToHex(DeviceName) + ".txt"

• DeviceName is converted to hex format to remove any invalid characters present.

Sub SendData(MessageText)

• Sends the string in MessageText to the current connection.

Function WaitForMultData(Mult, Choices, Timeout) As Long

• Monitors the RxBuffer for data contained in the Mult() array.
• If a match is found, the array index value is returned.
  • A return value of 0 indicates that no match was found before the timeout occurred.
• The timeout is specified in seconds and the variable cl.RecDataTimeOut is usually passed as this value.
• Choices indicates the number of elements in the Mult array. For example: Mult(1) = "Login:" Mult(2)= "Password:", Choices=2

Function ReplaceControlChrs(Message) As String

• Replaces any control characters less than ASCII value of 32 with a text string of the numeric value.
• For example: A tab character (ASCII 9) becomes <009>.
• This is used when logging debug data to the display or file for later analysis.

cl.Log

Sub Log(Priority, Message)

• Sends a log event message back to the main program.
• Use one of the following priority codes to classify the message:
  • 4 = Debug
  • 3 = Info
  • 2 = Warning
  • 1 = Error