PMDF System Manager's Guide

The first step in installing the message circuit check facility is to insert the channel definition in the PMDF configuration file. The channel definition should have the form:

circuitcheck slave CIRCUITCHECK-DAEMON

Note that such a channel should always be marked with the slave keyword. (Indeed, there is no actual channel program executed, not even a slave channel program; all the actual circuit check operation is performed by the circuit check detached process.)

An alias entry should also be added to the PMDF alias file. Pick a name, e.g. "circuitcheck", that is otherwise unused on your system, and then add an entry such as:

circuitcheck: circuitcheck@CIRCUITCHECK-DAEMON

This will set up the address circuitcheck@your-local-domain, where your-local-domain is the official host name of the local channel, to be the loopback address---the eventual destination address to use when sending circuit check messages.

An option file can also be specified, if desired. This file should be located in the PMDF table directory and named circuitcheck_option. on OpenVMS or circuitcheck_option on UNIX or NT. One available option is:

INTERVAL (60 <= integer <= 3600)

This option specifies in seconds how frequently the circuit check detached process should "wake up" to look for received circuit check messages and, if an appropriate interval has elapsed, send new circuit check messages. The default if this option is not specified is 240, corresponding to four minutes.

Once the channel and alias are set up, the next step is to configure the message circuits and timings of your choice in the circuit check configuration file, described below in Section 33.3.1.1.

33.3.1.1 The Circuit Check Configuration File

Note that the circuit check configuration file is part of a compiled configuration, so if using a compiled PMDF configuration you must recompile (and on OpenVMS reinstall the compiled configuration) after changes to the file. The circuit check detached process will not see changes to its configuration file until it is restarted via a command such as PMDF RESTART CIRCUIT_CHECK (OpenVMS) or pmdf restart circuit_check (UNIX and Windows).

The circuit check configuration file is a text file containing entries in a format similar to the conversion file format (described in Section 24.1.3). Namely, an entry consists of one or more lines grouped together, with each line containing one or more "parameter=value;" clauses. Every line except the last must end with a semicolon. Entries are terminated by either a line that does not end in a semicolon, one or more blank lines, or both.

Each circuit check entry must specify a NAME parameter, providing a name or "handle" for a particular circuit, a DESTINATION parameter, specifying the loopback address used for this circuit, and a RECURRENCE parameter, specifying a recurrence rule describing how often to send messages on this circuit. Additional parameters may also be included, to specify things like the size and priority of messages to send on this circuit, or to establish thresholds relating to circuit completion timings or circuit completion failures and commands to execute upon such threshholds being exceeded.

Each time the circuit check facility executes (each time it "wakes up", as controlled by its INTERVAL option), it will send out new messages, plus take any special actions regarding completion or lack thereof of previous circuits, according to the entries in its configuration file.

For instance, the circuit check configuration file for a sample site domain.com shown in Example 33-1 establishes two circuits, one named "domain-alpha" that loops through a system alpha.domain.com, and another named "domain-beta" that loops through another system beta.domain.com. The "domain-alpha" circuit sends out a new message every five minutes; the "domain-beta" circuit sends out a new message every 10 minutes.

Example 33-1 Sample Circuit Check Configuration File

name=domain-alpha; destination="circuitcheck%domain.com@alpha.domain.com"; recurrence=MI5; name=domain-beta; destination="circuitcheck%domain.com@beta.domain.com"; recurrence=MI10;

Due to the parser used, circuit check configuration file parameter values must conform to MIME conventions for Content-type: header line parameters. In particular, this means that destination values (since they contain an @ character) must be quoted.

33.3.1.1.1 Available Circuit Check Parameters

Table 33-2 Available Circuit Check Parameters

Parameter	Meaning
Required parameters
NAME	Name (handle) for this circuit
DESTINATION	Destination address for this circuit's messages
RECURRENCE	A recurrence rule specifying how often to send messages on this circuit
Optional parameters
AVERAGE_THRESHOLD	A threshold value for the average circuit completion time
AVERAGE_THRESHOLD_COMMAND	Command to execute when the AVERAGE_THRESHOLD value is exceeded
OBSOLETE_COMMAND	Command to execute when obsolete circuit message files are seen
EXPIRY	An ISO 8601 P specification of a time after which to consider messages expired
EXPIRY_COMMAND	Command to execute when an expired message is received
FAILED_COMMAND	Command to execute when messages fail
MAXIMUM_THRESHHOLD	A threshold value for the maximum circuit completion time
MAXIMUM_THRESHHOLD_COMMAND	Command to execute when the MAXIMUM_THRESHOLD value is exceeded
OUTSTANDING_COMMAND	Command to execute when the OUTSTANDING_MAX value is exceeded
OUTSTANDING_MAX	The maximum number of outstanding messages to permit; when there are more than this number of outstanding messages, then additional new circuit messages will not be generated and sent
PRIORITY	Priority of generated messages
SIZE	Size of generated messages

AVERAGE_THRESHOLD (real number)

This parameter takes a value in seconds. If the average circuit completion time for messages in this circuit exceeds this value, PMDF will execute the command specified by the AVERAGE_THRESHOLD_COMMAND parameter value. Note that once a AVERAGE_THRESHOLD value has been exceeded, the average completion time must drop back down below AVERAGE_THRESHOLD before another execution of AVERAGE_THRESHOLD_COMMAND will be performed. That is, the message circuit check facility performs the AVERAGE_THRESHOLD_COMMAND upon AVERAGE_THRESHOLD first being exceeded---or upon any subsequent occasion when, after having been below AVERAGE_THRESHOLD, the average time again crosses over AVERAGE_THRESHOLD. During a sustained interval of being over AVERAGE_THRESHOLD, the AVERAGE_THRESHOLD_COMMAND will not be repeatedly executed.

AVERAGE_THRESHOLD_COMMAND (shell command)

This option specifies a command (a DCL command on OpenVMS or shell command on UNIX or NT) to be executed if the average circuit completion time for messages in the defined circuit exceeds the circuit's AVERAGE_THRESHOLD value.

DESTINATION (address within quotes)

The DESTINATION parameter is required in each entry. Its value must be an address, and more specifically should consist of the circuit check's own loopback address embedded within explicit routing to route the message through some channels or remote system(s). (Due to the presence of the @ character, the address must be enclosed in quotes.)

EXPIRY (ISO 8601 P time period)

The EXPIRY option may be used to specify a time after which a returning message (completing a circuit) should be ignored. ISO 8601 P format is, e.g.,

PyearYmonthMweekWdayDThourHminuteMsecondS

where the values year, month, etc., are integer values specifying an offset (delta) from the current time. The initial P is required; other fields may be omitted, though the T is required if any time values are specified.

EXPIRY_COMMAND (shell command)

This option specifies a command (a DCL command on OpenVMS or shell command on UNIX or NT) to be executed if a message returns in greater than the EXPIRY parameter time value. An EXPIRY parameter value is often set on the assumption that any messages that are older than the specified time should be assumed to be lost and will never return; in such a case, a site may want to be notified or have other special action taken if an expired message does, in fact, return.

FAILED_COMMAND (shell command)

This option specifies a command (a DCL command on OpenVMS or shell command on UNIX or NT) to be executed if a message returns to the message circuit check facility due to being bounced while on its circuit, rather than returning normally by completing its circuit.

MAXIMUM_THRESHOLD (integer)

This parameter takes a value in seconds. If the circuit completion time for messages in this circuit exceeds this value, PMDF will execute the command specified by the MAXIMUM_THRESHOLD_COMMAND parameter value. Note that once a MAXIMUM_THRESHOLD value has been exceeded, the completion time must drop back down below MAXIMUM_THRESHOLD before another execution of MAXIMUM_THRESHOLD_COMMAND will be performed. That is, the message circuit check facility performs MAXIMUM_THRESHOLD_COMMAND upon MAXIMUM_THRESHOLD first being exceeded---or upon any subsequent occasion when, after having been below MAXIMUM_THRESHOLD, the time again crosses over MAXIMUM_THRESHOLD. During a sustained interval of being over MAXIMUM_THRESHOLD, the MAXIMUM_THRESHOLD_COMMAND will not be repeatedly executed.

MAXIMUM_THRESHOLD_COMMAND (shell command)

This option specifies a command (a DCL command on OpenVMS or shell command on UNIX or NT) to be executed if the circuit completion time for messages in the defined circuit exceeds the circuit's MAXIMUM_THRESHOLD value.

NAME (string)

The NAME parameter is required in each entry. Its value must be a string. It should be a descriptive name describing the circuit, as this is the name that, for instance, will be displayed by the PMDF CIRCUIT_CHECK/SHOW (OpenVMS) or pmdf circuit_check -show (UNIX or NT) utility.

OBSOLETE_COMMAND (shell command)

This option specifies a command (a DCL command on OpenVMS or a shell command on UNIX or NT) to be executed if obsolete message files are seen in the queue for the circuit check facility. See Section 33.3.3 below for a discussion of obsolete circuit check message files.

OUTSTANDING_COMMAND (shell command)

This option specifies a command (a DCL command on OpenVMS or a shell command on UNIX or NT) to be executed if the message circuit check facility is awaiting the return of more than OUTSTANDING_MAX messages.

OUTSTANDING_MAX (integer)

If more than the specified number of messages are outstanding, then the message circuit check facility will not send out any more messages until the number of outstanding messages drops below this value.

PRIORITY (string)

This option may be used to specify the Priority: of message to send on this circuit, e.g., Urgent, Normal, Non-urgent.

RECURRENCE (versit vCalendar recurrence specification)

The RECURRENCE parameter is required in each entry. Its value must be a vCalendar recurrence string. This option specifies how often the entry should be executed; i.e., how often the sort of message defined in the entry should be sent. The general form for a recurrence value for this option is

Uj

where j is an integer and U is a code letter (or two letters) specifying the units: Y for year, M for month, W for week, D for day, H for hour, or MI for minutes. For instance, H1 means to recur every hour from this moment forward; MI45 means to recur every 45 minutes from this moment forward. Note that there is no point in using a recurrence value smaller than the circuit check facility's INTERVAL option.

SIZE (integer)

This option may be used to specify the size of message to send on this circuit. By default, messages of size 0 are sent; that is, messages with just headers and no message body.