Documentation forKiwi CatTools

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 ..."


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.


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