This feature is only available in the licensed version.
(The freeware version will only allow you to Test the action.)
This action will run the specified script which will allow you to perform filtering or parsing on the current message.
A step by step example of creating and using a script can be found in the tutorial.
Script file rules
The script must always contain a function called Main(). No parameters are passed to the function, but a return value of "OK" must be passed back to indicate that the script ran successfully. If any value other that "OK" is returned, Syslog will assume an error has occurred in the script and place an entry in the error log. The value returned from the script function will also be included in the error log for later diagnoses.
Example (VBScript):
Function Main()
' Your code goes here
' Set the return value
Main = "OK"
End Function
Each of the script variables available can be accessed from the Fields object.
Script file name
The script file is a standard text file that contains the script commands. The file name can have any extension, but .txt is used by default for ease of editing with Notepad.
Script description
This field can contain any descriptive text you like. Its purpose is to briefly describe the function of the script
Script Language
Windows Script provides two script engines, Visual Basic® Scripting Edition and Microsoft JScript®
VBScript - A variation of Visual Basic or VBA (Visual Basic for Applications) used in MS Word and Excel. This language is easy to learn and has a rich feature set.
JScript - A variation of Java Script used in web pages. If you are familiar with Java Script then this may be your language of choice.
Both languages offer similar functionality and speed, so the choice on which to use is up to personal preference. However we have found through our tests that if your script is performing mainly string manipulation then JScript appears to be faster in most cases.
More info on VBScript can be found at:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/vtoriVBScript.asp
More info on JScript can be found at:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/js56jsoriJScript.asp
It is also possible to add additional scripting languages such as Perl or Python.
To do this you will need to install the Active Scripting engines for any new languages that you want to script in.
For information on using PerlScript please visit:
http://www.activestate.com/Products/ActivePerl
For information on using Python please visit:
http://www.activestate.com/Products/ActivePython
To download and for further information on ActiveScriptRuby please visit:
http://arton.hp.infoseek.co.jp/index.html
Edit script button
This will open the script file in Notepad and allow you to view/modify the code. If you modify the code, make sure you save the changes. The script can then be tested by pressing the Test button.
Test button
This will attempt to run the specified script. The script must contain a function named Main(). This is the only function called by Syslog. A return value of "OK" must be passed back from the Main() function to tell Syslog that the script ran successfully.
If an error occurs while trying to run the script, a message box will be displayed indicating the error description and the line number on which it occurred. If the script runs successfully and you have the "show test results" option checked, a before and after dump of the variables will be shown. This will show you any changes that have been made to the variables by your script.
When scripts are tested from the Kiwi Syslog Daemon Setup window (Test button pressed) they are not cached. Each script is freshly loaded before it is run.
Show test results option
If the script runs successfully and you have the "show test results" option checked, a before and after dump of the variables will be shown. This will show you any changes that have been made to the variables by your script.
Script file caching
During normal operation, the script files are cached after they have been read from disk. This improves the program speed and saves a lot of additional disk accessing. If you are modifying the script externally and saving it back to disk, the changes will not take effect until you restart the program.
If you are running Kiwi Syslog Daemon as a standard interactive application you can flush the script file cache and cause the program to reload the files from disk by using the File | Debug options | Clear the script file cache menu option. Or by pressing Ctrl-F8 from the main syslog window.
If you are running Kiwi Syslog Daemon as a service then this option is not available. To flush the script file cache you will need to stop and restart the service via the Manage menu.
Remember you will need to flush the cache each time you want the new script file to be read from disk.
Field Read/Write permissions
For reasons of security and speed, access to the message/scripting variables can be restricted. Each time a script is run, the message fields are copied to the script variables and back again upon completion of the script. Because the copying takes time and uses CPU cycles, limiting the read/write access to only the variables you want to use will improve the speed of the program.
When you enable read access for a group of fields, their values will copied into the script variables and will readable from within the script.
When you enable write access for a group of fields, their values will copied from the script variables and will replace the equivalent program fields.
The fields are divided into groups based on the likelihood of usage within a script.
More details on each of the fields can be found here
Common fields
VarFacility
VarLevel
VarInputSource
VarPeerAddress
VarPeerName
VarPeerDomain
VarCleanMessageText
Other fields
VarDate
VarTime
VarMilliSeconds
VarSocketPeerAddress
VarPeerAddressHex
VarPeerPort
VarLocalAddress
VarLocalPort
VarPriority
VarRawMessageText
Custom fields
VarCustom01 to VarCustom16
The following script variables are always available for read and write access by the script.
Inter-script fields
VarGlobal01 to VarGlobal16
Custom Statistics fields
VarStats01 to VarStats16
Control and counter fields
ActionQuit
SecondsSinceMidnight
SecondsSinceStartup
Triggering a script on a regular basis.
By enabling the Keep-alive input function, a message will be injected on a regular interval. This message can be used to trigger the scripting action.