Solstice Enterprise Manager 4.1 Customizing Guide |
Using RCL System Variables
This chapter describes the Request Condition Language (RCL) system variables that you can use in building Nerve Center request templates. The individual system variables along with examples illustrating their use are discussed in alphabetical order.
This chapter describes the following topics:
- Section 21.1.1 $eventInfo
- Section 21.1.2 $eventOI
- Section 21.1.3 $eventTime
- Section 21.1.4 $eventType
- Section 21.1.5 $messType
- Section 21.1.6 $pollfdn
- Section 21.1.7 $pollFdnSet
21.1 System Variables
The names and types of the available system variables are summarized in the following table.
TABLE 21-1 System Variables Available to a Condition $eventOC OID Object class of last/current event. $eventOI ObjectInstance Object instance of event. $eventInfo eventInfo eventInfo of eventType. $eventTime GeneralizedTime Actual time the event was generated. $eventType OID OID of the event type of the last event. $messType INTEGER Type of current message (refer to TABLE 21-3 for $messType values). $pollOC ObjectClass Object class last polled or being currently polled. $pollfdn ObjectInstance Object instance being polled. $pollFdnSet SET OF ObjectInsance Set of distinguished names pointing to the managed object instances configured for the target device. Assigned when request launched against a selected element in the Network Views. $pollTime GeneralizedTime Delay until the first poll is sent and the time between successive polls, in seconds. $severity INTEGER Severity level of current state.
21.1.1 $eventInfo
$eventInfo is the current event notification. This will be a sequence of ASN.1 values of the attributes comprising the event. The attributes that comprise $eventInfo depend upon its event type (the value of $eventType). The definition of the event type specifies the required attributes for that type and optional attributes, if any. The required attributes for a communicationsAlarm, for example, are probableCause and perceivedSeverity. If the attribute has an assigned name, this tag can be used to extract the ASN.1 value of that attribute from $eventInfo, as in the following example:
$cause = Extract(&$eventInfo,"probableCause");The attributes that comprise a given event notification depend upon the definition of its event type. The definitions used by the MIS are contained in the pertinent ASN.1 and GDMO documents. The event types known to the MIS by default are described in Chapter 8 of Management Information Server Guide.
In the following example, the value of $eventInfo is set to contain a nerveCenterAlarm:
$eventInfo = strToAsn("EM-NC- ASN1:NerveCenterAlarmInfo","{1,critical,\"Device Down\",3,1}";The first argument passed to strToAsn1() is text that refers to the event type--NerveCenterAlarmInfo. This type is defined in the ASN.1 document /opt/SUNWconn/em/etc/asn1/nc.asn1. The definition specifies that an event of type NerveCenterAlarmInfo is a sequence of ASN.1 attributes. A nerveCenterAlarm is defined as including four required attributes--probableCause, perceivedSeverity, mosiSeverity, mosiStateID--and an optional fifth attribute, additionalText. The permissible values and standard interpretation of perceivedSeverity values is provided in the following table.
TABLE 21-2 perceivedSeverity Values Indeterminate 0 Blue Critical 1 Red Major 2 Orange Minor 3 Cyan Warning 4 Yellow Clear 5 No color
Thus, in the example above, $eventInfo is defined as a nerveCenterAlarm with a perceivedSeverity of critical, a mosiSeverity value of 3, a probableCause value of 1, and a mosiStateID value of 1. The strToAsn() function is used to convert the string constant to the sequence of ASN.1 values required by the event type definition.
In the request template, mosiSeverity represents the severity of the state (this could be the state in which the event originated). The number of the state is mosiStateID, the same as the above referenced state (as ordered in the request designer).
21.1.2 $eventOI
$eventOI indicates the managed object instance that was the source of an event notification that "woke up" the request. In the following example, the OiToOiName() function is used to convert the $eventOI to a string.
$name = OiToOiName($eventOI);21.1.3 $eventTime
$eventTime provides the time when the event notification was generated. In the EventSample request template, a request is listening for startup of Solstice Enterprise Manager (Solstice EM) tools. After subscribing for objectCreation events, the time of connection of the application to the MIS is calculated from the $eventTime value of the objectCreation event:
$connect_time = $eventTime;When the application instance is terminated, the EventSample request receives an objectDelection event. The timestamp saved in $connect_time is then used to calculate the length of time the application was connected to the MIS:
$delete_time = getTimeStamp();$time_connected = $delete_time - $connect_time;$time_connected = $time_connected / 1000.00;21.1.4 $eventType
$eventType is the Object Identifier for the type of the event that "woke up" the request. The following example shows a condition used to define a transition from one state to another. The transition will take place if communicationsAlarm is the event type.
$comm = NameToOid("communicationsAlarm");$eventType == $comm;In the next example, an IF statement tests whether an event is an internetAlarm and, if it is, calls sendEvent() to post the event to the alarm log.
$itType=NameToOid("internetAlarm");IF ($eventType == $itType){sendEvent("internetClass",$pollfdn,"internetAlarm",$eventInfo);}The event types known to the MIS by default are the following:
- objectCreation
- objectDeletion
- attributeValueChange
- relationshipChange
- stateChange
- communicationsAlarm
- environmentalAlarm
- equipmentAlarm
- integrityViolation
- operationalViolation
- physicalViolation
- processingErrorAlarm
- qualityofServiceAlarm
- securityServiceOrMechanismViolation
- timeDomainViolation
- internetAlarm
- snmAlarmEvent
- snmAlarmTrap
- nerveCenterAlarm
- coldStartTrap
- warmStartTrap
- linkDownTrap
- linkUpTrap
- linkDownTrap
- egpNeighborLossTrap
- authenticationFailureTrap
- enterpriseSpecificTrap
For more information on these event types refer to Chapter 8 inManagement Information Server (MIS) Guide.
21.1.5 $messType
When an event or poll response is received, the variable $messType is set in the request. A condition can check the value of $messType. In a state machine that is both poll- and event-based, $messType will indicate the current message received, either an EVENT_REPORT_REQ, GET_RES, or errors. As an example of the use of $messType, the following is a condition that defines a transition. The probableCause value is extracted from an equipmentAlarm and a transition occurs if an event notification has been received ($messType == 0) and it has a probableCause value indicating equipmentMalFunction.
$cause = Extract($eventInfo,"probableCause");$messType == 0 AND $cause == 15;A CMIP event notification has a $messType value of 0 (EVENT_REPORT_REQ) because it is generated by the agent on its own initiative; it is not a response to a request generated by a management station.
Another use of $messType is to check for errors in the request. If errors occur during polls, the state machine can be designed to transition to a "dead" state.
The possible values of $messType are specified in the following table.
21.1.6 $pollfdn
The $pollfdn variable represents the object that is the target of the request. In the following example, $pollfdn is used to pass the request's target managed object instance to the subscribeOi() function to subscribe for SNMP event notifications generated by that object.
$itindx=subscribeOi("internetAlarm","{}",$pollfdn);The $pollfdn is based on the object's Fully Distinguished Name, the absolute path to the object through the Management Information Tree (MIT). When a request is launched in the Network Views, the $pollfdn is initially set to the first managed object in $pollFdnSet. In the following example, a request launched against the router bigguy has its $pollfdn set to the cmipsnmpProxyAgent:
/systemId=name:"gatoloco"/internetClassId={1 3 6 1 4 1 42 2 2 2 9 2 4]/ cmipsnmpProxyAgentId="bigguy"However, this $pollfdn could be changed to point to particular MIBs "contained" under the SNMP agent. In the following example, the appendRdn() function is used to change the $pollfdn to point to the snmp-mibII object:.
$tmp = "/InternetSystemId=NULL";$pollfdn = appendRdn($pollfdn,$tmp);After the append operation, the $pollfdn is the following:
/systemId=name:"gatoloco"/internetClassId={1 3 6 1 4 1 42 2 2 2 9 2 4]/ cmipsnmpProxyAgentId="bigguy"/InternetSystemId={1 3 6 1 4 1 42 2 2 2 9 1 1 3 6 1 2 1 1 0}Chapter 15 describes sample templates that change the target of polling during execution.
21.1.7 $pollFdnSet
When a request is launched against a device selected in the Network Views, $pollFdnSet is assigned a set of fully distinguished names (FDNs) which denote the managed objects that have been configured for the device (for example, when Network Discovery is run to populate the MIS). A "managed object" is the internal representation in the MIS of the agent, for example, a cmipsnmpProxyAgent object, which represents an SNMP agent system. The order of the FDNs in $pollFdnSet depends upon the order in which they were added to the MIS. Individual FDNs can be extracted from $pollFdnSet using the RCL extract() function. The following is an example of a condition that extracts the RPC proxy table FDN from $pollFdnSet in order to set the $pollfdn to ping-reach, the reach attribute group of the RPC ping agent.
Sun Microsystems, Inc. Copyright information. All rights reserved. |
Doc Set | Contents | Previous | Next | Index |