Action - Run Script

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