change_state()

Change the rule state of a PATROL application instance.

Syntax
Parameters
Rule State and Combined State
Description
Example

Syntax

change_state( object , state ,[description])

Parameters

Parameter	Definition
object	name of the application instance whose state is to be changed
state	operational state to which object will be setValid Values OFFLINE OK WARN ALARM Typically you should use the OK state. Using any other state causes PATROL to suspend the parameters that the object may have.
description	optional text string that can be used to explain the state change action The text string must be enclosed in double quotation marks. The text string is recorded in the Event Diary of the State Change Event in the Event Manager. Default NULL string

Rule State and Combined State

Each PATROL object has two state values associated with it: a rule state and a combined state. The rule state is the state of the object. The combined state is the state of the object and all its children.

When an object changes state and propagates that state change to its parent, it can change the combined state of its parent but not the rule state. However, if you change the state of an object using the change_state() function, you change the rule state of that object.

Setting the rule state of an object via the change_state() function is not equivalent to setting the combined state via child ﬁ parent state propagation. If you change the rule state of an application instance to ALARM (or OFFLINE) via the change_state() function, the PATROL Agent assumes that the application instance is in critical condition and deactivates all its parameters while it is in that state. But if you allow an ALARM state to propagate from parameter to application instance, the application instance will show ALARM as its combined state, but if its rule state is not in ALARM the PATROL Agent will not deactivate its parameters.

Tip

You should never use the change_state() function to set the state of the parent object.

Description

The change_state() function changes the rule state of application instance object to state. The change_state() function returns the new state or the NULL string on error.

Example

The following PSL statement changes the state of object person to the ALARM state and issues a message to the Event Manager Event Diary:

# change state of instance <person>
change_state(person,ALARM,"User close to process quota");