Chapter 22. Writing your own Scripts

Table of Contents

Target Scripts
VB-Script
Perl-Script
Action Scripts
VB-Script
Perl Script

Scripts can be written in any scripting language. The following languages have been tested:

There should be no reason that other scripting languages supported by Microsoft platforms should not work. In terms of a Remote-Script.pl, any script that can be run on the remote computer should work. The 'Target Scripts' and 'Action Scripts' documentation will be limited to VB-Script and Perl-Script.

The Remote-Probe.pl program will work with all the above tested script languages. Additional configuration will be required to enable it to support a new script language. An entry will have to be added to the send of the arrays:

Table 22.1. Language Customization for Remote-Probe.pl

ScriptCommandMapThe command prompt to launch the script engine. The Script file name will be appended to the end by the program.
LanguageHeadersSome script language may require that something be added to the beginning of the script file.
ScriptFooterThis is added to the end of the file and should output the result of the TargetFunction. $a,$b,$c,$d..$f will be replaced by the respective in-args sent by Net-Probe.
ActionFooters

In the case that an action is sent, then this array must contain the command to launch the DoAction function and output the result. The following tags are replaced by items sent from Net-Probe:

  • -Title-
  • -Host-
  • -TargetID-
  • -AlarmCondition-
  • -OldAlarmCondtion-
  • -Extras-
  • -FailureCount-
  • -IsHostTest-
  • -HostTestResult-
  • -HostStateChange-

Target Scripts

A Script Aquirer will execute a function, feeding in 6 parameters and returning up to 9 output values. The return value can be any of the following:

  • Tab Delimited String
  • Integer
  • Double (decimal point number)
  • Array

Within the return value up to 9 output values can be stored in the case of a String or an Array. For a string each output value must be seperated by a tab ("\t" for most languages, but VBTAB for VB-Script). The second value, or output parameter 1, should contain 'info'. Info is useful text that helps by offering information why a test failed or additional info that may be useful to the user for a passed test, like what the service responded with. Integer and Double return values can only pass a single value.

VB-Script

Function TargetFunction (a,b,c,d,e,f)
 ...
End Function

Perl-Script

sub TargetFunction
{
 ($a,$b,$c,$d,$e,$f)=@_;
 .....
}

Tags are used by the wizards to make things easier for the user. They are not a requirement. Tags always start with the comment charactor of the script language. In VB-Script this is the ', in Perl Script this is the #. Following the comment charactor of the language place a ^. Net-Probe will identify this as a tag. Four tag types are supported by Target Scripts:

Table 22.2. Language Customization for Remote-Probe.pl

Desc:following the : describes the purpose of the script.
OS:following the : specifies the operating systems that the script should work on
Arg{n}:A description of the input parameter can optionally be placed after the :. the {n} should be replaced by the argument number of interest. If an Arg is followed by either <Host> or <Timeout> then this tells the wizard that Net-Probe should put the Host and Timeout for the Target into these parameters. The user only has to setup the Target values correctly, Net-Probe will use these values for the script argument. If the <Host> or <Timeout> are not specified and an Arg is added then after the : place the description of the parameter, if required. If the parameter is not optional (i.e. the script cannot work without the argument) then place an * after the description. The wizard will not let the user continue unless a value has been entered.
OutArg{n}This describes what the output for arg number n is. In Addition this description could start with 'Alarm,' or 'Graph,'. If 'Alarm,' is found the return argument will be shown in wizards relating to alarms. Likewise, if 'Graph,' is found then the return arg is available in graph related wizards. For the workspace wizard to allow for a script to be used, then return arg 0 must have 'Alarm, State'. This means that arg0 is suitable for an alarm and it's output is the alarm state (where 0 is OK, 1 is Critical and 2 is Warning).

Below is an example of tags for the Perl IMAP server test.

#^Descr: Test an imap mailbox server. If no username and password are given only the ability to connect is tested. With username and password both connection and logon tests are performed.
#^OS: All
#^Arg0:	<Host>
#^Arg1:	<TimeOut>
#^Arg2:	Username
#^Arg3:	Password
#^OutArg0: Alarm, State
#^OutArg2: Alarm, Graph, ResponseTime

All pre-witten scripts are placed under the directory {installation directory/ScriptsTargets/{Language}/. The located script window in many of the wizards will search this location. If you setup tags for your script then you could also place any of your own scripts in this location and they will appear in the script list box. The Language required by the script is determined by the directory the script is placed in.

When developing a script you should always keep in mind that Remote-Prope.pl works differently from Net-Probe. If you are not aware of the difference you may develop a script that works with one and not the other. Net-Probe keeps the script in memory at all times, the script is normally not unloaded. Remote-Probe.pl will dump the script to disk and execute a separate process of the Script Interpreter to perform the execution. Once complete the script is unloaded. Remote-Probe.pl also adds lines to the end of the script. This enables the system to execute the function and identify when the script has been completed. Remote-Probe.pl can also be far more aggressive in enforcing a timeout than Net-Probe can be, due to the use of a separate process. If the timeout period is exceeded the script will be ended. With Net-Probe the script engine will be told to stop on the next statement. If the next statement is delayed for some reason, perhaps due to a low level function, like 'Sleep' in Perl, the script will only stop after the 'Sleep', and is not able to interpret the Sleep command.


Copyright (c) Warren Flemmer 2006www.net-probe.com