The script functions

A number of built in functions are available from the Fields object. More functions will be added to future releases to help improve the functionality of the scripting engine.

To use a built in function, simply access the function name prefixed with the Fields object. Pass any parameters needed and the result will be returned.

Built-in functions of the "Fields" object

Fields.IsValidIPAddress(IPAddress as string) as Boolean

Function: Checks the string passed to it and returns true if the string has a valid IP address format.

Input parameters: IPAddress as string

Return value: Boolean (true/false)

Example usage:

If Fields.IsValidIPAddress(Fields.VarPeerAddress) = True then

  Fields.VarCustom01 = Fields.VarPeerAddress

End if

Fields.ConvertIPtoHex(IPAddress As String) As String

Function: Converts an IP address to 8 byte hex format.

Input parameters: IPAddress as string

Return value: 8 byte hex value

Example usage:

If Fields.IsValidIPAddress(Fields.VarPeerAddress) = True then

  Fields.VarCustom01 = Fields.ConvertIPToHex(Fields.VarPeerAddress)

End if

Fields.GetDailyStatistics() As String

Function: Returns the daily statistics page as a CRLF delimited string.

Input parameters: None

Return value: String

Example usage:

MyStats = Fields.GetDailyStatistics()

The resulting string can then be written to a file or e-mailed etc.

Fields.ConvertPriorityToText(PriorityValue)

Function: Converts a message priority value to a text representation of the facility.level.

Input parameters: Priority value

Range: 0 to 191

Return value: Facility.Level as text string

Example: A value of 191 returns "Local7.Debug"

Example usage:

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt"

' Use the date and time from the current message

With Fields

    MsgDate = .VarDate & " " & .VarTime

    MsgText = "This is a test message from the scripting action"

    Data = MsgDate & vbtab & .ConvertPriorityToText(.VarPriority) & vbtab & _

           .VarPeerAddress & vbtab & MsgText

    Call .ActionLogToFile(Filename, Data)

End with

Fields.ActionPlaySound(SoundFilename As String, RepeatCount as Long)

Function: Plays a beep or specified wav file. Can be repeated for x times or until cancelled.

Input parameters: SoundFilename as string, RepeatCount as long

Return value: None

Specifying a empty string ("") for SoundFilename will result in the system beep sound.

RepeatCount options:

0 = repeat until cancelled (Cancel by pressing flashing bell on main display window)

1 to 100 = repeat specified number if times, or until cancelled manually

When the repeat count is greater than 1, the wav file or beep sound will be played at 5 second intervals.

Example usage:

' Play the squeak sound 5 times

Call Fields.ActionPlaySound("C:\Program Files\Syslogd\Sounds\Squeak.wav", 5)

' Play the squeak sound until cancelled

Call Fields.ActionPlaySound("C:\Program Files\Syslogd\Sounds\Squeak.wav", 0)

' Play the system beep sound 10 times

Call Fields.ActionPlaySound("", 10)

' Play the system beep sound until cancelled

Call Fields.ActionPlaySound("", 0)

Fields.ActionSendEmail(MailTo, MailFrom, MailSubject, MailMessage , [MailImportance] , [MailPriority] , [MailSensitivity] )

Function: Sends an e-mail to the addresses specified

Return value: None

Importance, Priority and Sensitivity E-mail Delivery Option parameters are optional.

E-mail Delivery Options

These parameters allow for the importance, priority and sensitivity flags of the e-mail message to be specified.

The e-mail recipients will recieve the messages with the various importance/priority/sensitivity levels set accordingly.

MailImportance:        0 - Unspecified (Default)

         1 - High

         2 - Normal

         3 - Low

MailPriority:        0 - Unspecified (Default)

         1 - Normal

         2 - Urgent

         3 - Non-Urgent

MailSensitivity:        0 - Unspecified (Default)

         1 - Personal

         2 - Private

         3 - Confidential

To send the message to multiple addresses, separate each address with a comma.

E.g.:

MailTo = "user1@company.com,user2@company.com,user3@company.com"

Example usage:  Send e-mail to joe@company.com, use default importance, priority and sensitivity

MailTo = "joe@company.com"

MailFrom = "server@company.com"

MailSubject = "This is a test of the scripting action"

MailMessage = "This is a test mail message" & vbCrLf & "Multiple lines."

Call Fields.ActionSendEmail(MailTo, MailFrom, MailSubject, MailMessage)

Example usage:  Send e-mail to joe@company.com, High importance, Urgent priority, Confidential sensitivity

MailTo = "joe@company.com"

MailFrom = "server@company.com"

MailSubject = "This is a test of the scripting action"

MailMessage = "This is a test mail message" & vbCrLf & "Multiple lines."

MailImportance = 1

MailPriority = 2

MailSensitivity = 3

Call Fields.ActionSendEmail(MailTo, MailFrom, MailSubject, MailMessage, MailImportance, MailPriority, MailSensitivity)

Fields.ActionLogToFile(Filename, Data, [RotateLogFile] , [RotationType] , [NumLogFiles] , [Amount] , [Unit])

Function: Opens the specified log file and appends the Data to the end of the file.

Return value: None

This function can be used to log messages to file in your own format.

AutoSplit syntax values can be used in the filename if you want.

To have the filename contain the current hour of the day, use %TimeHH

Example: Filename = "C:\Program files\Syslogd\Logs\TestLog%TimeHH.txt"    

Example usage:

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt"

MsgPriority = "Local7.Info"

MsgHostAddress = Fields.VarPeerAddress

' Use the date and time from the current message

MsgDate = Fields.VarDate & " " & Fields.VarTime

MsgText = "This is a test message from the scripting action"

Data = MsgDate & vbtab & MsgPriority & vbtab & MsgHostAddress & vbtab & MsgText

Call Fields.ActionLogToFile(Filename, Data)

Note: this example requires that Read permission be enabled for "Other fields". This gives the script read access to the VarDate and VarTime variables.

Log File Rotation:

For more information on Log File Rotation in Kiwi Syslog Server, please see Log File Rotation

The parameters RotateLogFile, RotationType, NumLogFiles, Amount and Unit are all optional and only need to be specified if logging to a rotated log file.

RotateLogFile:        0 = Do not rotate log file

         1 = Rotate log file

RotationType:        0 = Rotate log files when log file size exceeds the amount specified by Amount and Unit

         1 = Rotate log files when log file age exceeds the amount specified by Amount and Unit

NumLogFiles:        The number of log files to be used in the rotation.

Amount:        For RotationType=0 : Amount is a file size.

         For RotationType=1 : Amount is a file age.

Unit                For RotationType=0 :        Unit relates to the size of the file and specifies whether the Amount is Bytes, KB, MB, etc.

                                 0 = Bytes

                                 1 = Kilobytes

                                 2 = Megabytes

                                 3 = Gigabytes

         For RotationType=1:        Unit relates to the age of the file and specifies whether the Amount is Minutes, Days, Weeks, etc.        

                                 0 = Minutes

                                 1 = Hours

                                 2 = Days

                                 3 = Weekdays

                                 4 = Weeks

                                 5 = Months

                                 6 = Quarters

                                 7= Years

Example Usage:

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt"

MsgPriority = "Local7.Info"

MsgHostAddress = Fields.VarPeerAddress

' Use the date and time from the current message

MsgDate = Fields.VarDate & " " & Fields.VarTime

MsgText = "This is a test message from the scripting action"

Data = MsgDate & vbtab & MsgPriority & vbtab & MsgHostAddress & vbtab & MsgText

RotateLogFile = 1        'Rotate this log

RotationType = 0        'Using File size rotation -

NumLogFiles = 4        'Use up to 4 log files

Amount = 1000                'Each log file no more than 1000

Unit = 0                'bytes in length

Call Fields.ActionLogToFile(Filename, Data, RotateLogFile, RotationType, NumLogFiles, Amount, Unit)

Example Usage (2):

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt"

MsgPriority = "Local7.Info"

MsgHostAddress = Fields.VarPeerAddress

' Use the date and time from the current message

MsgDate = Fields.VarDate & " " & Fields.VarTime

MsgText = "This is a test message from the scripting action"

Data = MsgDate & vbtab & MsgPriority & vbtab & MsgHostAddress & vbtab & MsgText

RotateLogFile = 1        'Rotate this log

RotationType = 1        'Using File age rotation -

NumLogFiles = 12        'Use up to 12 log files

Amount = 1                'Each log file no more than 1

Unit = 5                'month old

Call Fields.ActionLogToFile(Filename, Data, RotateLogFile, RotationType, NumLogFiles, Amount, Unit)

Fields.ActionSendSyslog(Hostname, Message, Port, Protocol)

Function: Sends a syslog Message to Hostname on Port via Protocol.

Return value: None

Hostname: Text string containing the hostname or IP address of the remote host.

Message: Text string containing the priority tag and syslog message text

Port: Integer between 1 and 65535 (514 is the standard syslog port)

Protocol: Integer between 0 and 1 (0=UDP, 1=TCP)

This function can be used to send syslog messages to another syslog host via the UDP or TCP protocol.

Example usage:

Hostname = "10.0.0.1" ' Remote syslog host

Priority = 191        ' Local7.Debug

Port = 514            ' Use the standard syslog port

Protocol = 0          ' 0=UDP, 1=TCP

' Construct the syslog message by adding <PRI> value to the front of the text

Message = "<" + Cstr(Priority) + ">" + "This is an example of a syslog message"

Call Fields.ActionSendSyslog(Hostname, Message, Port, Protocol)

Fields.ActionSpoofSyslog(AdapterAddress, SrcAddress, DstAddress, DstPort, Message)

Function: Sends a spoofed Syslog Message (UDP only) to DstAddress on Port DstPort.

Return value: None

AdapterAddress: Text string containing the IP or MAC address of the network adapter that the message will be sent from.

          (Can be an IP Addres:- ie "192.168.0.1", or MAC address:- ie. "00:50:56:C0:00:08")

SrcAddress:         Text string containing the hostname or IP address of the source of the message (actual or spoofed)

DstAddress:         Text string containing the hostname or IP address of the remote (receiving) host.

DstPort:         Integer between 1 and 65535 (514 is the standard syslog port)

Message:         Text string containing the priority tag and syslog message text

This function can be used to send syslog messages to another syslog host via the UDP protocol.

Example usage:

AdapterAddress = "192.168.1.100"        ' Adapter Address (Can be IP Address- ie "192.168.0.1", or MAC address - ie. "00:50:56:C0:00:08")

SrcAddress = "192.10.10.1"                ' Source of message

DstAddress = "10.0.0.1"                        ' Destination of message

DstPort = 514                                  ' Use the standard syslog port

Priority = 191                              ' Local7.Debug

' Construct the syslog message by adding <PRI> value to the front of the text

Message = "<" + Cstr(Priority) + ">" + "This is an example of a syslog message"

Call Fields.ActionSpoofSyslog(AdapterAddress, SrcAddress, DstAddress, DstPort, Message)

Important Note:

This option also requires that WinPcap version 4.1 and above is installed.  WinPcap (Windows Packet Capture library) is available for download from: WinPcap, The Packet Capture and Network Monitoring Library for Windows

Fields.ActionLogToFileWithCache(Filename, Data, [RotateLogFile] , [RotationType] , [NumLogFiles] , [Amount] , [Unit])

Function: Writes data to the specified log file. This function uses a write cache to improve performance. The cache is flushed every 100 messages or 5 seconds, which ever comes first. The cache settings can be adjusted via registry settings. This function is exactly the same as ActionLogToFile, except that it uses a write cache. We recommend the use of the write caching function when you are receiving more than 10 messages per second.

Return value: None

This function can be used to log messages to file in your own format.

AutoSplit syntax values can be used in the filename if you want.

To have the filename contain the current hour of the day, use %TimeHH

Example: Filename = "C:\Program files\Syslogd\Logs\TestLog%TimeHH.txt"    

Example usage:

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt"

MsgPriority = "Local7.Info"

MsgHostAddress = Fields.VarPeerAddress

' Use the date and time from the current message

MsgDate = Fields.VarDate & " " & Fields.VarTime

MsgText = "This is a test message from the scripting action"

Data = MsgDate & vbtab & MsgPriority & vbtab & MsgHostAddress & vbtab & MsgText

Call Fields.ActionLogToFileWithCache(Filename, Data)

Note: this example requires that Read permission be enabled for "Other fields". This gives the script read access to the VarDate and VarTime variables.

Log File Rotation:

For more information on Log File Rotation in Kiwi Syslog Server, please see Log File Rotation

The parameters RotateLogFile, RotationType, NumLogFiles, Amount and Unit are all optional and only need to be specified if logging to a rotated log file.

RotateLogFile:        0 = Do not rotate log file

         1 = Rotate log file

RotationType:        0 = Rotate log files when log file size exceeds the amount specified by Amount and Unit

         1 = Rotate log files when log file age exceeds the amount specified by Amount and Unit

NumLogFiles:        The number of log files to be used in the rotation.

Amount:        For RotationType=0 : Amount is a file size.

         For RotationType=1 : Amount is a file age.

Unit                For RotationType=0 :        Unit relates to the size of the file and specifies whether the Amount is Bytes, KB, MB, etc.

                                 0 = Bytes

                                 1 = Kilobytes

                                 2 = Megabytes

                                 3 = Gigabytes

         For RotationType=1:        Unit relates to the age of the file and specifies whether the Amount is Minutes, Days, Weeks, etc.        

                                 0 = Minutes

                                 1 = Hours

                                 2 = Days

                                 3 = Weekdays

                                 4 = Weeks

                                 5 = Months

                                 6 = Quarters

                                 7= Years

Example Usage:

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt"

MsgPriority = "Local7.Info"

MsgHostAddress = Fields.VarPeerAddress

' Use the date and time from the current message

MsgDate = Fields.VarDate & " " & Fields.VarTime

MsgText = "This is a test message from the scripting action"

Data = MsgDate & vbtab & MsgPriority & vbtab & MsgHostAddress & vbtab & MsgText

RotateLogFile = 1        'Rotate this log

RotationType = 0        'Using File size rotation -

NumLogFiles = 4        'Use up to 4 log files

Amount = 1000                'Each log file no more than 1000

Unit = 0                'bytes in length

Call Fields.ActionLogToFileWithCache(Filename, Data, RotateLogFile, RotationType, NumLogFiles, Amount, Unit)

Example Usage (2):

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt"

MsgPriority = "Local7.Info"

MsgHostAddress = Fields.VarPeerAddress

' Use the date and time from the current message

MsgDate = Fields.VarDate & " " & Fields.VarTime

MsgText = "This is a test message from the scripting action"

Data = MsgDate & vbtab & MsgPriority & vbtab & MsgHostAddress & vbtab & MsgText

RotateLogFile = 1        'Rotate this log

RotationType = 1        'Using File age rotation -

NumLogFiles = 12        'Use up to 12 log files

Amount = 1                'Each log file no more than 1

Unit = 5                'month old

Call Fields.ActionLogToFileWithCache(Filename, Data, RotateLogFile, RotationType, NumLogFiles, Amount, Unit)

Fields.ActionDeleteFile(Filename)

Function: Attempts to delete the specified file.

Return value: None

This function can be used to delete a log file to ensure a fresh start.

This function does not support wildcards, a specific file name must be specified. No confirmation is required, so be careful when using this function.

Example usage:

Filename = "C:\Program files\Syslogd\Logs\TestLog.txt"

Call Fields.ActionDeleteFile(Filename)

Fields.ActionDisplay(DisplayNumber, TabDelimitedMessage)

Function: Displays a message to the specified virtual display number.

Return value: None

This function can be used to display messages on the screen in your own format.

The TabDelimitedMessage must contain 5 tab delimited fields. The contents of each field can be anything you like. The normal display fields are: Date TAB Time TAB Priority TAB Hostname TAB Message.

Example usage:

With Fields

     MsgPriority = ConvertPriorityToText(.VarPriority)

     MsgHostAddress = .VarPeerAddress

     ' Use the date and time from the current message

     MsgDate = .VarDate & " " & .VarTime

     MsgText = "This is a test message from the scripting action"

     Display = MsgDate & vbtab & MsgTime & vbtab & MsgPriority & vbtab &_

               MsgHostAddress & vbtab & MsgText

     Call .ActionDisplay(0, Display)

End with

Fields.ActionLogToODBC(DSNString, TableName, InsertStatement, Timeout)

Function: Passes the InsertStatement to the database specified by DSNString and TableName. The timeout specifies how many seconds to keep the database connection open when idle.

Return value: For success, an empty string is returned. Otherwise the error is passed back as a string value.

This function can be used to log messages to a database in your own format. The connection to the database is held open internally to the program. This avoids the overhead of creating and breaking the connection each time data is sent. If no further data is sent to the database, once the timeout period has elapsed, the connection will be closed. The next time data needs to be sent, the connection will be reopened.

Example usage:

In the case of this example, a System DSN called "KiwiSyslog" has been created and points to a MS Access database. The SQL insert statement syntax changes slightly depending on the database type being written to. The example here has only been tested on MS Access 97 and 2000.

This example assumes that a table called "Syslogd" has already been created and contains all the required fields.

MyDSN = "DSN=KiwiSyslog;"

MyTable = "Syslogd"

MyFields = "MsgDate,MsgTime,MsgPriority,MsgHostname,MsgText"

' MS Access DB SQL INSERT command example:

' INSERT INTO Syslogd (MsgDate,MsgTime,MsgPriority,MsgHostname,MsgText)

' VALUES ('2004-08-08','13:26:26','Local7.Debug','host.company.com',

' 'This is a test message from Kiwi Syslog Server')

With Fields

    ' Construct the insert statement

    SQLcmd = "INSERT INTO " & MyTable & " (" & MyFields & ") VALUES (" & _

    Quote(.VarDate) & "," & Quote(.VarTime) & "," & _

    Quote(.ConvertPriorityToText(.VarPriority)) & "," & _

    Quote(.VarPeerAddress) & "," & Quote(.VarCleanMessageText) & ")"

    ' Log the data to database using DSN, Table, SQLcmd and Timeout of 30 seconds

    .VarCustom01 = .ActionLogToODBC(MyDSN, MyTable, SQLcmd, 30)

    ' VarCustom01 now holds the return value from the function.

End with

Function Quote(Data)

   ' Replace all occurrences of ' with '' to escape existing quotes

   ' Wrap data with single quotes  

   Quote = "'" & Replace(Data, "'", "''") & "'"

End Function

Note: This example requires that Read permission is enabled for "Other fields". This gives the script read access to the .VarDate and .VarTime variables.

Note: There are more example scripts installed in the \Scripts sub folder.