Companion Scripts and New Macros to Use with Command-Line Probes

Command-line probes have been a feature of InterMapper (IM) for quite some now, allowing users to create a probe out of almost any command that can be executed from a shell. IM 5.2 brings the latest in a series of improvements to make this capability both easier to use and more powerful.

A probe writer can now include what we're calling a "companion script" in her command-line probe. Because the script is part of the probe rather than a separate file, there is never any question of what version of the script the probe is using. In addition, the probe is much easier to distribute.

Companion scripts are written to disk whenever probes are loaded or reloaded. In order to avoid problems with conflicting filenames, they are written to subdirectories of the Tools directory; these subdirectories are named using the canonical name of the probe to which they belong.

When a companion script is present in a probe, IM makes the subdirectory in which it resides the current working directory before executing the probe, making it unnecessary to specify a path in the command.

There are also two new macros available to command-line probe writers, whether or not they are using companion scripts.

Use ${PYTHON} in your command to invoke the python interpreter installed with InterMapper DataCenter (IMDC). (IMDC is installed along with IM by default in Windows and Mac versions of IM 5.2; it is still a separate download for Linux and Unix versions.) IMDC need not be running for it to work; it need only be present. Note that this allows your probe to be cross-platform; you needn't worry about the specifics of invoking the python interpreter.

If you are a WIndows user, you may use ${CSCRIPT} in your command to invoke CSCRIPT.EXE, the Windows command-based script host, to run scripts. (Our WMI probes, also new in 5.2, make use of this macro, as well as companion scripts.)

Let's take a look at an example probe file which makes use of these components. I've attached com.dartware.companionscript.python.txt to this entry.

Looking at the header, we see:


package = "com.dartware"
probe_name = "companionscript.python"


This means the canonical name of the probe is "com.dartware.companionscript.python". InterMapper will write any companion scripts to "InterMapper Settings/Tools/com.dartware.companionscript.python".

There is a companion script in this probe, defined by using the <tool> tag:


<tool:test.py>
# Trivial example to return two values and a text condition string
print "\{ $val1 := 1, $val2 := 'abcdef' }Condition string - device should be yellow"

# Return code sets device status (Warn = 1)
raise SystemExit, 1
</tool:test.py>


The name after the ":" in the <tool> tag is the name the script will be given when written into the com.dartware.companionscript.python directory, in this case, "test.py".

Looking at the <command-line> section, we see;


<command-line>
path = ""
cmd = "${PYTHON}"
arg = "test.py"
</command-line>


No path is specified. We've used the ${PYTHON} macro as our command and passed "test.py" as an argument to the command. Because a companion script is present, IM will change the current working directory to "com.dartware.companionscript.python". IM will then invoke the IMDC python interpreter to execute "test.py", which happens to be our companion script.

I've also attached com.dartware.companionscript.vbscript.txt to this entry; this differs only in that it uses ${CSCRIPT} and a vbs script, rather than ${PYTHON} and a python script.

Probe files referred to in this post:

com.dartware.companionscript.python.txt

com.dartware.companionscript.vbscript.txt

More reading:

Custom Probe Developer's Guide

Companion Scripts

${PYTHON}, ${CSCRIPT} macros