TCP Probes

type="tcp-script"

TCP probes connect to the specified device and port and execute a script that sends and receives data from the device. Intermapper examines the responses and sets the device status and condition based on the results.

For example, the HTTP probe connects to the specified port and issues the commands of an HTTP request to send data to the web server. It also verifies the received data. If the response is not as expected, the probe sets the device into an alarm or warning status.

As another example, the TCP Example shows another TCP-based probe that connects to a device. It sends the specified string, waits several seconds, and checks the response to determine the device state.

The custom TCP probe is shown in full as an example. This probe can be used for making your own probes.

Common Sections of TCP Probes

Each TCP probe uses the following general format that is used by other probe files:

• The <header> section specifies the probe type, name, and other properties fundamental to the operation of the probe.
• The <description> section specifies the help text displayed in the Set Probe window. You can format the description using IMML, Intermapper's Markup language.
  
• The <parameters> section defines the fields displayed in the Set Probe window.

Sections Specific to TCP Probes

Each TCP probe also includes the following:

• The <script> section of a TCP probe defines a sequence of commands the probe uses to interact with and query a device and specifies how to interpret the responses from the device. The <script> section uses the TCP Probe Scripting Language, a sequential language with a rich set of commands.
  
• The <script-output> section of a TCP probe file formats the information retrieved from the device and sends it to the device Status window. Format the script output using IMML, Intermapper's Markup language.

Intermapper's TCP probes establish a connection to a remote system, exchange commands and receive responses, and set the status of the device based on those responses.

You can use regular expressions and comparisons to parse out information from the responses.

Overall Process

There is an annotated FTP probe in the Developer Guide. This provides an overview of the script language and shows how it connects to and logs into an FTP server, how a script can respond to error conditions, and how to set the device status based on those conditions.

Regular Expressions

The TCP Script Language uses the MTCH command to compare a response string to expected values. It can also use a regular expression to match on a part of a string. For example,

MTCH "A([BCD]+)E"r else goto @NOMATCH
STOR "testval" "${1}" 

If the incoming line contains ABDE, the testval variable contains BD.

In the MTCH regular expression, enclosing something in parentheses turns it into a capturing subgroup. The one or more Bs, Cs, or Ds that it matches are stored in the ${1} variable. If you have several capturing groups, they are stored in ${2}, ${3}, and so on.

For more information, see the Regular Expressions examples in Probe Calculations.

Calculations in Scripts

You can use the EVAL command to perform calculations in a TCP script. The argument is an expression (in quotation marks) that is evaluated. It usually contains an assignment (with the := operator) that sets a variable to the result of the expression. For example,

EVAL $celsius := (($fahrenheit - 32) * 5 / 9) 

sets the variable $celsius to the temperature that corresponds to the $fahrenheit variable. The value of the $celsius variable can be used in subsequent statements.

Comparisons in Scripts

You can use the EVAL statement to compare strings or numeric (integer or floating point) values. To do this, write an EVAL statement that compares the two values and sets the result in a new variable. If the comparison is true, the resulting variable is set to 1, otherwise it is set to 0.

The following are examples of comparing numeric and string values:

EVAL $x := ($val > 50.5)
NBNE #$x #0 @greater       
@less:           
...           
GOTO @ENDIF           
@greater:           
...           
GOTO @ENDIF           
@ENDIF:           

EVAL $x := ("dog" > "cat")
NBNE #$x #0 @dog           
@cat:           
...           
GOTO @ENDIF           
@dog:           
...           
GOTO @ENDIF           
@ENDIF:           

For more information, see Eval Macro section in Built-In Custom Probe Variables.

Simple Comparisons in Scripts

Intermapper TCP scripts can compare two string or integer numeric values and branch based on the results. The commands below are no longer preferred as the EVAL statement described above is equally simple and more powerful.

The SBNE (String Branch Not Equal) compares two string values and branches if they are not equal. One or both of the arguments can be variables, expressed as ${variable-name}.

The NBNE (Numeric Branch Not Equal) and NBGT (Numeric Branch Greater Than) compares two numeric values, branching on the result. The arguments to these commands are strings and are enclosed in quotation marks. To convert a string to a numeric value, add a pound sign (#) before the parameter. For example,

STOR "val1" "100"
STOR "val2" "50"
NBGT #${val1} #${val2} @exit 

In this example, the string ${val1} is converted to the numeric value of 100, ${val2} is converted to the numeric value of 50, and the branch is accepted because 100 is greater than 50.

For more information on these commands, see TCP Probe Command Reference.