| Solstice Enterprise Manager 4.1 Customizing Guide |
|
RCL Functions
The RCL Built-in functions are described in this chapter.
This chapter describes the following topics:
Built-in functions take the form of a function call with a set of arguments. The RCL Functions list denotes an Asn1Value whose type is SET, SEQUENCE, SET OF, or SEQUENCE OF. <Var> indicates a variable name. <Attr> indicates an attribute name.
Note – The names of RCL functions are not case-sensitive.
22.1 Summary of RCL Built-in Functions
22.1.1 AlarmLog Functions
- Alarm--Generates a nerveCenterAlarm with indicated severity.
- AlarmOi--Takes severity, object instance, and event arguments.
- AlarmStr--Generates a nerveCenterAlarm with indicated severity and additionalText.
- SendEvent--Logs an event notification. Allows you to log event notifications of types other than nerveCenterAlarm.
22.1.2 String-Handling Functions
- InitialStr--True if string matches initial portion of a string.
- FinalStr--True if string matches end portion of a string.
- AnyStr--True if string appears anywhere in a string.
- StrCat--Builds string by concatenation.
22.1.3 Value Check Functions
- Defined--True if variable or attribute has a value.
- Undefine--Sets variable or attribute to have no value.
22.1.4 Name Conversion Functions
- NameToOid--Returns an Object IDentifier from a name string.
- OiNameToOi--Object instance from quoted name string.
- OiToOiName--Returns the name of an object instance.
- AddressStrToAddress--Dot address string to Internet address string.
- NameToAddress--IP address from a host name string.
- AppendRdn--Constructs an object instance from an object instance and RDN string.
22.1.5 Action Functions
- Unixcmd--Executes a specified UNIX command.
- Mail--Sends an e-mail message.
22.1.6 ASN.1 Conversion Functions
- AsnToStr--Builds string representation of an ASN.1 value.
- StrToAsn--Builds ASN.1 values from strings.
22.1.7 SunNet Manager RPC Request Functions
- SnmEventRequest--Issues request to an SNM RPC agent.
- SnmKillRequest--Kills a previously issued SNM request.
22.1.8 Debugging Function
Print--Prints values if em_debug misc_stdout option is turned on.
22.1.9 Constructed-Type Handling Functions
Parameters may be passed to constructed-type handling functions. Each parameter is an expression which in turn may contain function calls.
- CompareLists--True if the two ASN.1 lists being compared match.
- Exclude--Deletes a component from an ASN.1 list.
- Extract--Returns value of a component in a list.
- Include--Used to construct an ASN.1 value of types SET or SEQUENCE.
- IsChoice--True if a variable or attribute is a choice.
- IsList--True if variable or attribute is a list.
- IsMember--True if a given component is part of a specified ASN.1 list.
- NumElements--Returns the number of elements in a list.
- ReplaceMember--Replaces a component with another component in an ASN.1 list.
22.1.10 Time Functions
GetTimeStamp--Retrieves the current time of the MIS machine.
22.1.11 Event-Handling Functions
- Set--Performs an M-SET on a specified object.
- Subscribe--Subscribes to event type specified in string.
- SubscribeOi--Subscribes to events for specified object.
- SubscribeFilter--Subscribes for events that match a specified CMIS filter.
- TrapSpecificType--Returns number of SpecificType of a trap.
- TrapGenericType--Returns number of GenericType of a trap.
- SendAction--Sends an M-ACTION to a specified object.
- SendTrap--Sends a trap to destination IP address.
- UnSubscribe--Can be used to terminate a previously invoked event subscription.
22.1.12 Request Control Functions
Exit--Causes a request to delete itself.
22.2 The RCL Functions
The Request Condition Language (RCL) built-in functions are listed here in alphabetical order.
22.2.1 AddressStrToAddress
Syntax:
AdressStrToAdress(<addrStr>);where <addrStr> is of type OCTET STRING.
Return Value:
unsigned long. Returns the value of the inet_addr() system call.Takes a string containing an address in dot format and returns an unsigned long integer containing an internet address. For example:.
$saddr=AddressStrToAddress("129.144.44.36");22.2.2 Alarm
Syntax:
Alarm(<perceivedSeverity>);where <perceivedSeverity> is of type INTEGER (in the range 0-5).
The MIS Alarm Service (which monitors the alarm logs) causes the Viewer to change the color of the icon for the object instance associated with the alarm (the object indicated by the $pollfdn system variable), based on the value of <perceivedSeverity>. The value must be in the range 0-5. For example, the AlarmCritical sample condition provided with Solstice Enterprise Manager (Solstice EM) contains the following:
This statement will post a nerveCenterAlarm with severity critical. The valid severities and their associated icon colors are listed in the following table.
TABLE 22-1 Valid Alarm Severities 0 Indeterminate Blue 1 Critical Red 2 Major Orange 3 Minor Cyan 4 Warning Yellow 5 Cleared No color
22.2.2.1 Alarm Logging and Viewer Fault Status
The alarm() function allows you to generate a nerveCenterAlarm which is, by default, logged to the AlarmLog. Alarms logged to the AlarmLog can be viewed and cleared in the Alarms.
The AlarmLog is also, by default, monitored by the Alarm Service. The Alarm Service is a module in the MIS that controls the fault status color in the Viewer. Fault status is an attribute of topology nodes, which are represented by icons in the Viewer. Each topology node has an attribute topoNodeMOSet, which points to a set of managed object instances (MOIs), representing the agents configured for the particular device.
The Alarm Service associates an alarm posted to the AlarmLog with a topology node if and only if that alarm is posted against one of the managed objects in the topoNodeMOSet for that topology node. The Alarm Service tracks the perceivedSeverity values of the alarms that are posted against each topology node. The highest perceivedSeverity value of uncleared alarms determines the fault status of the device. Thus, if a critical alarm is logged against router bigguy, the router icon, by default, turns red. If several minor alarms are then posted against bigguy, these do not cause the router icon to turn cyan unless the critical alarm has been cleared. Once the critical alarm is cleared, the presence of uncleared minor alarms causes a change in color to cyan.
When a request is launched at a target device in the Viewer, the $pollFdnSet RCL system variable for that request points to the managed objects that are comprised in the topoNodeMOSet for the selected topology node. The $pollfdn system variable is also initially set to point to the first managed object listed in $pollFdnSet.
The alarm() function posts a nerveCenterAlarm against the managed object that the $pollfdn variable points to at the time when the alarm() function is called. If you have reset the $pollfdn variable to point to an object other than one of those comprised in $pollFdnSet in your request, you should either reset $pollfdn to an appropriate managed object before calling alarm() or else use the alarmOi() function, which enables you to specify the managed object against which the alarm is to be posted.
The alarm() and alarmStr() functions post nerveCenterAlarms that have a probableCause value equal to the perceivedSeverity value. For example, if your request uses alarm() to post a minor alarm, probableCause is set to 3. Alarm Service uses the probableCause value of nerveCenterAlarms to match a "clear" alarm to the previous nerveCenterAlarm it is clearing. For example, if your request has used
to post a critical alarm, your request must post a nerveCenterAlarm with a probableCause of 1 and a perceivedSeverity of 5 (clear) to clear this alarm. Because alarm() and alarmStr() set probableCause to equal perceivedSeverity, requests cannot use alarm() or alarmStr() to clear a previous nerveCenterAlarm. To post an alarm that clears a previous nerveCenterAlarm, your request must use the alarmOi() function.
For more information on the Alarm Service, see Chapter 4.
22.2.3 AlarmOi
Syntax:
AlarmOi( <oi>, <perceivedSeverity> | <event-notification>);
where <oi> is of type Object Instance. The second argument is either <perceivedSeverity> or <event-notification>. <perceivedSeverity> is of type INTEGER (in the range 0-5).The Viewer icon will change color based on the severity value passed in <perceivedSeverity> (as indicated in TABLE 22-1). For example, the statement
will cause the icon representing the target of the current request to turn red.
Note – For an alarm posted against $pollfdn to cause a change in icon color in the Viewer, $pollfdn must point to one of the managed objects configured for the device. The $pollFdnSet variable is initially set to point to these objects when the request is launched against a selected device in the Viewer, and $pollfdn is initially set to point to the first object in $pollFdnSet. If your request template changes the value of $pollfdn to point to an object other than those in $pollFdnSet, the alarm may not affect icon color. For the <oi> parameter, you must use a variable that points to one of the objects in $pollFdnset if the alarm is to affect the Viewer fault status of the target device. For more information, see Section 22.2.2.1 Alarm Logging and Viewer Fault Status" or Chapter 4.
If <event-notification> is passed as an argument to alarmOi(), the event notification attribute values are used to build a nerveCenterAlarm. For example:
"{3,minor, 3, 1}";If the system variable $eventInfo is passed as the second argument, $eventInfo will have been defined only if the request has subscribed for events. In that case, $eventInfo is set to the current event notification.
The alarmOi() function can be used to clear previous nerveCenterAlarms posted by a request. To post a "clear" alarm, alarmOi() must set the probableCause value to equal the probableCause of the nerveCenterAlarm it is clearing. The alarm() and alarmStr() functions automatically set the probableCause value of a nerveCenterAlarm to equal the perceivedSeverity value. Thus, to use alarmOi() to clear a previous critical alarm, you could use the following:
"{1,cleared, 3, 1}";In this example, probableCause is set to 1 to match the probableCause of the previous critical alarm.
The value of probableCause can also be assigned using the possible values defined in an ASN.1 document such as dmi.asn1. For example, the following statement clears a previous nerveCenterAlarm that had used thresholdCrossed as its probableCause value:
$info = strToAsn("EM-NC-ASN1.NerveCenterAlarmInfo","{Attribute- ASN1Module.thresholdCrossed,cleared,\"SNMP is not responding\",3,1}");alarmOi($save_pollfdn,$info);22.2.4 AlarmStr
Syntax:
AlarmStr(<perceivedSeverity>, <additionalText>);where <perceivedSeverity> is of type INTEGER (in the range 0-5) and <additionalText> is a text string, or an RCL variable of any type.
The Viewer icon will change color based on the severity value passed in <perceivedSeverity> (as indicated in TABLE 22-1).
When this function is called, a nerveCenterAlarm will be generated with severity set to <perceivedSeverity> and objectInstance set to $pollfdn. The <additionalText> string will be passed as the additionalText attribute, which can be viewed in the Alarms tool. For example:
In the following example the <additionalText> argument is used to pass the FDN of the managed object in an alarm with a severity of critical:
Note – An alarm posted using the alarmStr() function uses the value of $pollfdn to determine the managed object that is the target of the alarm. If the alarm is to affect Viewer icon color, $pollfdn must point to one of the managed objects that have been configured for that device. The $pollFdnSet variable is initially set to point to the managed objects configured for a device when the request is launched against a target device in the Viewer. $pollfdn is initially set to refer to the first of these objects. If your template resets the value of $pollfdn, you will need to either reset it to point to one of the objects in $pollFdnSet before calling alarmStr() or use the alarmOi() function, which allows you to specify the managed object that is the target of the alarm. Refer to Section 22.2.2.1 Alarm Logging and Viewer Fault Status."
The alarmStr() function cannot be used to post nerveCenterAlarms that clear previous nerveCenterAlarms. For an explanation of how to clear previous alarms, refer to the entries for the alarm() and alarmOi() functions.
When a text string is passed as <additionalText>, variables can be interspersed within the text string. For example:
The textual representation of the value of $host and $timestamp will be inserted into the text, which becomes the additionalText attribute in the nerveCenterAlarm.
22.2.5 AnyStr
Syntax:
AnyStr( <firststr>, <secondstr>);
where <firststr> and <secondstr> are of type OCTET STRING.Checks whether <secondstr> appears anywhere in <firststr>. (A string constant is enclosed in double quotes.) In the following example $anywhere is a Boolean variable that will be assigned the value true if "Agent" occurs anywhere in the string that is the value of $hostdescr.
22.2.6 AppendRdn
Syntax:
AppendRdn(<oi>, <stringRdn>);
where <oi> is of type Object Instance and <stringRdn> is of type OCTET STRING.Return Value:
Object Instance.Used to specify a new object instance (OI) from a supplied OI and a relative distinguished name (RDN) string. An RDN consists of a naming attribute and a value connected by the identity sign (=). Examples of naming attributes are systemId, networkId, internetClassId, and agentId. An RDN identifies an object uniquely relative to a superior object that "contains" it.
This built-in function can be used to set $pollfdn (the object that is the current target of the poll), which is of type Object Instance.
The following example illustrates this use. Let us suppose that you want to design a template that retrieves SNMP attribute values from an SNMP agent. The IsSnmpSystemUp template, shipped with Solstice EM, is an example of such a template. IsSnmpSystemUp polls the agent system for its system description in order to verify that the SNMP daemon is running. This requires that the template set the $pollfdn to point to the internetSystem group of the SNMP agent. To set the $pollfdn to point to the internetSystem group, the SetInternetSystem condition must first locate the cmipsnmpProxyAgent distinguished name (FDN). The cmipsnmpProxyAgent is the object in the MIS that represents the agent on the system being managed. The various groups in the SNMP agent are represented by objects "contained" in the cmipsnmpProxyAgent object. These "containment" relationships are reflected in the path to the object specified in the FDN. In the IsSnmpSystemUp template, the appendRdn() function is used to construct an FDN that points to the internetSystem group object.
When a template is launched against a device selected in the Viewer, $pollfdn is initially set to the first FDN in $pollFdnSet, which is the set of FDNs identifying the managed objects that have been configured for the target device. However, if you have instructed Discover to search for RPC agents when populating the runtime database in the MIS, the $pollFdnSet for a target device may contain FDNs for RPC agents as well as the SNMP agent. Depending upon the order in which Discover found the agents on the devices in your network, the cmipsnmpProxyAgent FDN may or may not be the first FDN in $pollFdnSet.
The SetInternetSystem sample condition checks the initial $pollfdn to determine if it is an RPC agent FDN, and, if it is, the condition then searches the FDNs in the $pollFdnSet to find the FDN for the cmipsnmpProxyAgent object.
Once the SetInternetSystem condition has located the cmipsnmpProxyAgent, it then uses the appendRdn() function to form an FDN that points to the internetSystem group contained in that SNMP agent. For example, let us suppose that an IsSnmpSystemUp request launched against the SNMP host bigguy has its $pollfdn set to the following cmipsnmpProxyAgent FDN:
The SetInternetSystem sample condition then resets the value of $pollfdn to point to the RFC 1213 internetSystem group object via an appendRdn statement:.
The affect of this appendRdn operation on our request launched against the host bigguy is to change the value of $pollfdn to the following:
/systemId=name:"gatoloco"/internetClassId={1 3 6 1 4 1 42 2 2 2 9 2 4 1 0}/ cmipsnmpProxyAgentId="bigguy"/InternetClassId={1 3 6 1 4 1 42 2 2 2 9 1 1 3 6 1 2 1 1 0}This function only appends a single RDN. Although in some contexts a string may contain several names separated by a slash (/), if such a string is given as the second argument to appendRdn, only the first RDN is appended
Another use for the extract() function is to pull out attribute values from events. For example, if $eventInfo is an enterpriseSpecificTrap, extract() can be used to get the specific type of the trap as follows:
22.2.7 AsnToStr
Syntax:
AsnToStr( <asn1_value>, <fTranslate>);
where <asn1_value> is of type Asn1Value and <fTranslate> is of type BOOLEAN.This function can be used to build an equivalent string representation of an ASN1value. It takes two arguments:
<asn1_value> is the value whose string representation you want.
<fTranslate> controls the choice of format for an object name. If <fTranslate> is TRUE, the resulting string OIDs are represented by equivalent string names. Otherwise, the resulting string OIDs are represented in curly brace form rather than its equivalent string form. For example, the textual representation of the systemId attribute would be the following:
The curly brace representation of the systemId attribute would be as follows:
attributeId { 2 9 3 2 7 4 }The textual option is available only if <asn1_value> has been defined in an ASN.1 or GDMO document that the MIS knows about. If <asn1_value> is not so defined, only the curly brace representation is available.
The SetInternetSystem sample condition uses the following statement to convert an FDN to its textual representation in order to do a string compare on its contents:
22.2.8 CompareLists
Syntax:
CompareLists(&<list1>, <list2>);This function compares two ASN.1 lists and returns TRUE if they match; the function returns FALSE otherwise. For example:
22.2.9 Defined
Syntax:
Defined(&<Var>);
where <Var> is a variable; or
Defined(&<Attr>);
where <Attr> is an attribute.Checks whether the variable <Var> or the attribute <Attr> has a value. Returns TRUE if so, FALSE if the name or attribute has not been assigned a value or is not a valid name. A valid name is any of the assigned names of system variables (refer to TABLE 21-1), a user-defined variable local to the request, or any of the names or attributes occurring in the request template. For example, the IsSystemDesc sample condition, shown below, will return true if the device has responded to a get request for its SNMP sysDescr attribute value.
However, if this condition is used to test repetitively for availability of the SNMP device, an undefine should be executed before each subsequent test. This is necessary since the attribute value will remain defined in the request if a previous defined returned successful.
22.2.10 Exit
When this function is called, this causes the deletion of the request in which it is called. This is useful for deleting a request if it has reached a dead or error state. Doing so reduces the system overhead caused by requests that have been launched against devices that are not configured to support that request. For example, the following condition might be executed as an action after transition to an Error state in a template that polls for SNMP attributes:
22.2.11 Exclude
Syntax:
Exclude(&<list_variable>,<compone nt>);This function deletes the component specified by <component> from the ASN.1 list specified by <list_variable>. For example:
22.2.12 Extract
Syntax:
Extract(&<listvalue>, <subName>);
where <listvalue> is of type LIST and <subName> is of type OCTET STRING.From <listvalue>, returns the value of the subcomponent identified by the string <subName>. <subName> specifies the name of the type of the component. Returns a null Asn1Value if the first parameter <listvalue> is not a LIST whose type is a SEQUENCE or SET. In the following example,
$ele1 will assign the first set from collectionInfoList, which is a SET OF SEQUENCE.
In the following example, the ASN.1 value for one attribute in the sequence of attributes in a communicationsAlarm is extracted using the tag probableCause that identifies that attribute:
However, a single extract() call will only extract from the first layer of components. For example, suppose that you want to extract oldAttributeValue from an attributeValueChange event notification in the system variable $eventInfo. The event contains an ASN.1 attributeValueChangeDefinition, which is itself a construct containing both the old and new attribute values. (The structure of attributeValueChange events is described in Chapter 6 of Management Information Server Guide.) To get the oldAttributeValue, you could first assign
attributeValueChangeDefinition to a variable $attrChange and then call Extract() again to pull oldAttributeValue from that variable:
22.2.13 FinalStr
Syntax:
FinalStr(<firststr>, <secondstr>);
where <firststr> and <secondstr> are of type OCTET STRING.Checks whether secondstr appears in the end of <firststr>. (A string constant is enclosed in double quotes. In the following example $at_end_of_str is a Boolean variable that will be assigned the value true if "IPX" occurs at the end of the string that is the value of $hostdescr.)
22.2.14 FirstStr
Syntax:
FirstStr( <first-string>, <delimiter-string>);
where <string1> and <string2> are of type OCTET STRING.Returns the first string delimited by <delimiter-string>. For example:
$machine1 will have "gatoloco" as its value.
22.2.15 GetTimeStamp
Return Value:
GeneralizedTime. Current time in the format YYYYMMDDHHMMSSRetrieves the current time of the host where the MIS is running. For example:
if (($curtime - $eventTime) > 600) { print($curtime);}else {print($eventTime);}22.2.16 Include
Syntax:
Include(&<list-var>, <value>);
where <list-var> is a list variable of ASN.1 type SET or SEQUENCE. <value> contains the value to be included in the list.Return Value:
Boolean. True if the include operation was successful; false if not successful.To add values to a list using include(), the list variable should be initialized first. For example:
$mylist = StrToAsn("SET","{}");$ifint = 1;$ifStr = "ifIndex";include(&$mylist,$pollfdn);include(&$mylist,$ifint);include(&$mylist,$ifStr);The second parameter <value> must be defined for include() to succeed. This is particularly important if the <value> is a variable that has been assigned an attribute's value. For example, consider:
$list = strToAsn("SET","{}");include(&$list,$element);If the defined() function is not called, then include() will fail.
22.2.17 InitialStr
Syntax:
InitialStr( <firststr>, <secondstr>);
where <firststr> and <secondstr> are of type OCTET STRING.Returns True if <secondstr> appears initially in <firststr>. (A string constant is enclosed in double quotes.)Returns FALSE otherwise. In the following example, $at_start_of_str is a Boolean variable that will be assigned the value true if "Sun" occurs at the beginning of the string that is the value of $hostdescr.
22.2.18 IsChoice
Syntax:
IsChoice(&<Var>);
where <Var> is a variable; orIsChoice(&<Attr>);
where <Attr> is an attribute.Returns TRUE if the variable or attribute is a choice. Returns FALSE otherwise. For example:
22.2.19 IsList
Syntax:
IsList(&<Var>);
where <Var> is a variable; orIsList(&<Attr>);
where <Attr> is an attribute.Returns TRUE if the variable or attribute is a LIST. Returns FALSE otherwise. For example:
22.2.20 IsMember
Syntax:
IsMember(&<list_variable>, <component_variable>);Returns TRUE if the component specified by <component_variable> is included in the ASN.1 list specified by <list_variable>. Returns FALSE otherwise. For example:
22.2.21 Mail
Syntax:
Mail(<addr>,<message-text>);
where <addr> and <message-text> are both of type OCTET STRING.Sends an e-mail message. This is the equivalent of the MAIL action. <addr> is a string containing the e-mail address. <message-text> is a string containing the message text. RCL variables can be interspersed in the string; for example:
Mail("netMgr@Eng","linkDown trap from $pollfdn");22.2.22 NameToAddress
Syntax:
NameToAddress( <hostname>);
where <hostname> is of type OCTET STRING.Returns the IP address of the host whose name is <HostName>. In the following example, the NameToAddress function is used to set up an IP address for a SendTrap operation.
22.2.23 NameToOid
Syntax:
NameToOid( <Name>);
where <Name> is of type OCTET STRING.Return Value:
OBJECT IDENTIFIER.Returns the OID (Object IDentifier) of the object whose name is <Name>. This may be any name in the MIT that has been assigned an OID, such as an attribute, a name binding, and so on. In the following example, the OID corresponding to internetAlarm is assigned to a user variable $ncType.
$ncType=NameToOid("internetAlarm");22.2.24 NumElements
Syntax:
NumElements(&<Var>);
where <Var> is a variable that is a LIST; orNumElements(&<Attr>);
where <Attr> is an attribute that is a LIST.Returns the number of elements contained in a variable or an attribute that is a LIST. Returns 0 if the variable or attribute is not a LIST. This function can be used, for example, to check how many managed objects are listed in the $pollFdnSet--the set of FDNs pointing to the managed objects that have been configured for the device that the request has been launched against. This following statement illustrates this use:
22.2.25 OiNameToOi
Syntax:
OiNameToOi(<name>);
where <name> is of type OCTET STRING.Return Value:
Object Instance.Returns the object instance for the object whose name is supplied as quoted string <Name>. In the following example, an ObjectInstance will be returned from the distinguished name string constant.
$oi = OiNameToOi("/systemId=name:\"bigguy\"/topNodeDBId=NULL/topoNo deId=5");22.2.26 OiToOiName
Syntax:
OiToOiName( <instValue>);
where <instValue> is of type ObjectInstance.Returns the name of the object instance <inst> in the format the server uses. This is the inverse of the OiNameToOi function.
22.2.27 Print
Syntax:
Print(<Var>);
Print (<AttrName>);
Print(<Constant>);Return Value: BOOLEAN. Returns TRUE.
This function is used to print the value of the supplied variable, attribute, or constant. This function will print messages only if the following em_debug command has been invoked in a shell:
For more information on running the em_debug utility, see Chapter 16.
22.2.28 ReplaceMember
Syntax:
ReplaceMember(&<list_variable>, <old_component>, <new_component>);This function replaces the a component in the ASN.1 list specified by <list_variable> with a new component. The component being replaced is specified by <old_component> and the component that is to replace it is specified by <new_component>. For example:
22.2.29 SendAction
Syntax:
<Var> = SendAction( <dest_oi>, <ActionInfo>, &<result>);
where <dest_oi> is of type ObjectInstance (an ASN.1 value) and <ActionInfo> is an OCTET STRING constant. The address of <result> is also passed. The variable <result> needs to be initialized before being passed to SendAction(). <Var> is a BOOLEAN variable.The return value <Var> will be true if the action request is issued, otherwise false. However, even if <Var> is true, this does not mean the action request was successful. To determine whether the action request was successful, you will need to check the $messType system variable.
Sends an M-ACTION to the destination object instance <dest_oi>, using <ActionInfo>. The second argument is a string in the following form:.
"{ <actionName>, <actionArgs>}"For example, suppose there is an object
/systemId=titleist/counterObject=4
which has an action incrementCounter defined in the appropriate GDMO document. This action takes as its argument a name of a counter--for example, "alarm_counter" might be such a name. The following condition sends a CMIS M-ACTION to counterObject=4 with the parameter "alarm_counter":
$dn=OiNameToOi("/systemId=name:\"titleist\"/counterObjec t=4");$result=0;$ret = SendAction($dn,"{incrementCounter,"alarm_counter"}",&$res ult);You may then wish to transition to another state to check for a response; for example:
if ($ret AND ($messType == 10)) {print($result);}Another example:
$dn=OiNameToOi("/systemId=name:\"bigguy\"/topoNodeDBId=N ULL");$result = 0;$ret = SendAction($dn,"{topoNodeGetByType,\"Host\"},&$result);After issuing this SendAction request, you can then check for a $messType of 10 in a separate condition:
if ($ret AND ($messType == 10)) {print($result);}RCL functions can also be used to extract information from <result>.
22.2.30 SendEvent
Syntax:
SendEvent(<oc_name>,<oi>,<eventTypeName>,<event-notification>);
where <oc> is of type OCTET STRING, <oi> is of type objectInstance, and <eventTypeName> is of type OCTET STRING.
<event-notification> is the event to be logged, comprised of ASN.1 attributes. The attributes must be those that would be appropriate for the type of event notification specified by <eventTypeName>. (The structure of the default Solstice EM event types is described in Chapter 8 of Management Information Server Guide.)
<oc_name> is a string that specifies the object class of which <oi> is an instance.sendEvent() has a function similar to the other alarm logging functions, such as alarm() and alarmOi(), but sendEvent() can be used to log events other than nerveCenterAlarms. For example, internetAlarms or CMIP event notifications defined by the ISO/ITU X.733 standard, such as a communicationsAlarm, can be sent to the AlarmLog using the sendEvent() function. In the following example a communicationsAlarm is logged using the sendEvent() function.
$event=strToAsn("Notification-ASN1Module.AlarmInfo", "{4, major}";sendEvent("system",$pollfdn,"communicationsAlarm",$event );This example generates a communicationsAlarm with a probableCause value of 4 and a perceivedSeverity of major.
22.2.31 SendTrap
Syntax:
SendTrap( <dest>, <type>, <info>);
where <dest> is an OCTET STRING constant, <type> is an event type, and <info> is of type InternetAlarmInfo.Sends a trap to the destination IP address <dest>, using <type> and <info>.
The appropriate <type> can be obtained from $eventType.
The appropriate <info> can be obtained from $eventInfo.Returns TRUE is successful, FALSE otherwise. For example:
22.2.32 Set
Syntax:
<Var> = Set( <oi>, <modList>);
where <oi> is of type ObjectInstance. The argument <modList> is a modification list whose structure is defined in nc.asn1 as EM-NC-ASN1.ModificationList. <Var> is a BOOLEAN variable.Performs an M-SET on the object instance specified by <oi>. Set returns TRUE if the SET request has been issued.
Because RCL doesn't support callbacks, it's not possible for RCL templates to always check for the arrival of responses. If the response comes back almost instantaneously, the NC template can check for messType value (==9) within the same state as the Set() was invoked. A value of 9 means that the Set() response has arrived. If the messType is not 9, it doesn't imply anything.
The following example is a condition that does an M-SET on the topoNodeState attribute of a topology node.
$dn=strToAsn("CMIP- 1.ObjectInstance","distinguishedName:{{{systemID,\"titleist\" }},{{topoNodeDBI d,NULL}},
{{topoNodeId,0}}}");$arg = strToAsn("[12] IMPLICIT SET OF SEQUENCE { modifyOperator [2] IMPLICIT ModifyOperator DEFAULT replace, attributeId AttributeId, attributeValue ANY DEFINED BY attributeId }",
"{{replace,topoNodeState,5}}");Set($dn,$arg);After invoking Set, you can check for success of the operation by checking the $messType system variable. If $messType has a value equal to 9, the set was successful. Otherwise, $messType will be set to a different value if the Set was unsuccessful. For example, if the set was directed at an invalid object instance, $messType would be set to 15, indicating no such object instance. The statement that checks for $messType value should be evaluated in a different condition from the one that issues the Set.
Note – Poll attributes after setting them in order to check if SET succeeded.
Another example:
$dn = OiNameToOi("systemId=name:\"solpuppy\"/topoNodeDBId=NULL");$mlist = strToAsn("EM-NC-ASN1.ModificationList","{{attributeId topoNodeDisplayStatus, {\"Down\",5}}}");$ret = set($dn,$mlist);After the M-SET is executed, you may want to transition to another state to check for a response in another condition, such as the following:
if ($ret AND ($messType == 9)) {print($ret);}22.2.33 SnmEventRequest
Syntax:
SnmEventRequest(<oi>, <EventRequest>, &<snmRequestHandle>);
where <oi> is of type ObjectInstance, <EventRequest> is of either of type OCTET STRING or of type Asn1Value.<snmRequestHandle> is a variable that has already been initialized.Return Value: BOOLEAN. The return value is true if the action equest was issued, otherwise false.
This function is used to issue a SunNet Manager event request to an SNM agent or proxy via RPC protocol.
To identify this SNM event request, the function returns a unique handle in <snmRequestHandle>. This handle can be used to kill or stop the SNM event request that was started via the function snmKillRequest(). The $messType system variable should be checked to determine if a response to the action has been received. If $messType is 10, this indicates a response has been received to the action request.
<EventRequest> is a sequence of ASN.1 attributes as described in the following table. The order of occurrence in the table is the order within <EventRequest>.
TABLE 22-2 Arguments in <EventRequest> agentHost OCTET STRING Name of target agent system Required agentProgram INTEGER RPC number of agent Required agentVersion INTEGER Agent's RPC version number Required timeout INTEGER Maximum time (in seconds) to wait for response from agent before request fails Required interval INTEGER Polling interval.(in seconds) Required group OCTET STRING Name of attribute group Required threshold SEQUENCE of attrName -- OCTET STRING
attrType -- INTEGER
relop -- INTEGER
threshValue -- OCTET STRING
priority -- ENUMERATED
-- low (1)
-- medium (2)
-- high (3)
·Name of the attribute used to define the threshold
·Data type of the operands for relop. See TABLE 22-4.
·Relational operator used in defining the threshold. See TABLE 22-3.
·Threshold value to check for
·Priority assigned to an SNM event generated if the threshold is crossedRequired proxyHost OCTET STRING Name of a proxy system if a proxy agent is being used to access the agent system Optional count INTEGER Specifies the number of polls before terminating. If count is set to 0, this indicates that polling is to continue until request is killed. Optional optionalArgs SEQUENCE name -- OCTET STRING value -- OCTET STRING Optional arguments are agent-specifc. For example, requests to na.ping use these to set packet size, time to wait for echo replies, etc. Optional key OCTET STRING Row in a table. Entire table is used if no key is specified. Interpretation is agent-specific. For example, for the na.diskinfo agent this is the name of a filesystem partition. Optional flags INTEGER Request option flags. Currently defined is NETMGT_RESTART. Optional rendezHost OCTET STRING Name of host where rendezProgram (typically na.event) is running Optional rendezProgram INTEGER RPC number of the program that is to receive the events (typically the Event Dispatcher -- na.event) Optional rendezVersion INTEGER rendezProgram's RPC version number Optional
The agentVersion number can be found in the listing for the agent in /etc/inetd.conf. For example, 10 is the version number for na.snmp in the following inetd.conf entry:
The relational operators that can be used to define thresholds are described in the following table.
TABLE 22-3 Relational Operators in SNM Request Thresholds 0 No operation 1 Equal To 2 Not Equal To 3 Less Than 4 Less Than or Equal To 5 Greater Than 6 Greater Than or Equal To 7 Value has changed 8 Value Increased By 9 Value Decreased By 10 Value Increased By More Than 11 Value Increased By Less Than 12 Value Decreased By More Than 13 Value Decreased By Less Than
The data types for operands of relational operators (attrType) are defined in the following table.
TABLE 22-4 Data Types for Threshold Operands 1 short 2 unsigned short 3 int 4 unsigned int 5 long 6 unsigned long 7 float 8 double 9 null-terminated ASCII string 10 opaque octet stream 11 Internet address 12 struct timeval 13 seconds since 1/1/70 14 enumerated type 15 RFC 1065 integer 16 RFC 1065 octet string 17 RFC 1065 object identifier 18 RFC 1065 network address 19 RFC 1065 IP address 20 RFC 1065 counter 21 RFC 1065 gauge 22 RFC 1065 timeticks 23 RFC 1065 opaque
When an SNM agent or proxy detects that a specified threshold has been crossed, an event is sent to the SNM Event Dispatcher (na.event), which is called the rendezvous. rendezHost is the name of the machine whose Event Dispatcher is to receive the SNM event. By default, rendezHost is the name of the MIS machine that initiated the event request. The SNM Event Forwarder (em_snmfwd) on the MIS machine receives the event from the Event Dispatcher and converts it to an snmAlarmEvent (a type of CMIP event notification). The Event Forwarder maps SNM event priorities to the perceivedSeverity values used by the Alarm Service in the manner indicated in the following table. The SNM Event Forwarder sends snmAlarmEvents to the MIS.
TABLE 22-5 Mapping of SNM Event Severities Low Minor Cyan Medium Major Orange High Critical Red
The following condition builds and sends an SNM event request targeted at the ping-reach managed object, which represents the reach attribute group supported by the na.ping proxy agent.
$eventRequestStr = "{agentHost \"{}";$eventRequestStr = StrCat($eventRequestStr,$Hostname);$agentStr = "\",agentProgram 100115, agentVersion 10, timeout 10, interval 12, group \"reach\", threshold {\"triptime\",21,2,\"1\", medium}}";$eventRequestStr = StrCat($eventRequestStr,$agentStr);$request_handle = 0;snmEventRequest($pollfdn,$eventRequestStr,$request_handl e);In this example, 100115 is the RPC number of the na.ping agent and 10 is the version number of this agent. The polling interval is set to 12 seconds. The threshold is triptime not equal to 1. If the threshold is crossed, the ping agent is to generate an SNM event with a medium priority. The variable $hostname holds the hostname of the target of the request; this information could be extracted from the $pollFdnSet. (An example that extracts the hostname from $pollFdnSet can be found in Section 20.9.3 WHILE Constructs.") $pollFdnSet is a system variable that contains the set of distinguished names (FDNs) pointing to managed objects configured for the target device.
To receive SNM event notifications (snmAlarmEvents) generated by the proxy agent in response to a crossed threshold, the request that initiates the SNM event request can also use the event subscription functions, such as subscribeOi(), to subscribe for snmAlarmEvents. For more information on using RCL templates to launch SNM event requests, see Chapter 17.
22.2.34 SnmKillRequest
Syntax:
SnmKillRequest(<oi>,<EventReply>);
where <EventReply> is the result returned in the <result> variable passed to snmEventRequest().Return Value: BOOLEAN. Returns true if a correct argument is passed.
Issues a request to kill a SunNet Manager event request that had been issued by a call to the snmEventRequest function.
22.2.35 StrToAsn
Syntax:
StrToAsn( <strAsn1Type>, <strAsn1Value>);
where <strAsn1Type> and <strAsn1Value> are of type OCTET STRING.This function takes two arguments:
<strAsn1Type> is the canonical text representation of the Asn1Type.
<strAsn1Value> is the text representation of the Asn1Value. For example:
$asn1_int = StrToAsn("INTEGER","1000");$asn1_bool = StrToAsn("BOOLEAN","FALSE");returns the ASN1 encoding of <strAsn1Value>, but returns FALSE if the arguments are invalid. In the following example, strToAsn is used to build an internetAlarmInfo value for a SendTrap operation:
$alarminfo = "{ ";$alarminfo = strcat($alarminfo,$cause);$alarminfo = strcat($alarminfo,$trans_domain);$alarminfo = strcat($alarminfo,$traddr);$alarminfo = strcat($alarminfo,$access);$alarminfo = strcat($alarminfo,$ainfo);$alarminfo = strcat($alarminfo," }");$internetAlarmInfo = strToAsn("IimcCommonDef.InternetAlarmInfo",$alarminfo);$eventInfo = $internetAlarmInfo;SendTrap($destIp,$itType,$eventInfo);22.2.36 StrCat
Syntax:
StrCat( <string1>, <string2>);
where <string1> and <string2> are of type OCTET STRING.Returns a string built by concatenating <string1> and <string2>. For example:
$probCOid = "{1 3 6 1 4 1 42 2 2 2 9 1 9 1 999 1 1 1}";$cause = "probableCause globalValue: ";$cause = Strcat($cause,$probCOid);22.2.37 Strstr
Syntax:
StrStr( <string1>, <string2>);
where <string1> and <string2> are of type OCTET STRING.Returns a string with the first occurrence of <string2> in <string1>. For example:
22.2.38 StrStrPlus
Syntax:
StrStrPlus( <string1>, <string2>);
where <string1> and <string2> are of type OCTET STRING.Returns the remainder of a string after the first occurrence of <string2> in <string1>. For example:
22.2.39 Subscribe
Syntax:
Subscribe( <event_name_str>);
where <event_name_str> is of type OCTET STRING.Used to subscribe to events of the type identified in <event_name_str> . The <event_name_str> must be one of the event names that appears as a NOTIFICATION in a GDMO document that the MIS knows about. The following condition subscribes to receive SNMP traps. This condition could be used to define an initial transition out of the Ground state.
$itindx=Subscribe("internetAlarm");$itType=NameToOid("internetAlarm"); true;The OID retrieved using NameToOid() can be tested against the system variable $eventType to determine if an event of the subscribed type has arrived, as, for example, in the following condition:
Note – In composing a condition that tests for object creation, use subscribeOi(), rather than subscribe(), and subscribe to the creation of only a specific type of object. Do not listen for all object creations, as this can result in a deadlock (infinite loop) situation.
If a problem prevents the subscription from being implemented, a -1 is returned. Otherwise, this function returns a handle index; that is, a unique index for a subscription in a request. This handle can be passed in a call to the unsubscribe() function to terminate the event subscription.
22.2.40 SubscribeFilter
Syntax:
<result> = SubscribeFilter(<cmis_filter_string>);
where <cmis_filter_string> is a CMIS filter construct of type OCTET STRING.
<result> = SubscribeFilter(<asn1_cmis_filter>);
where <asn1_cmis_filter> is a CMIS filter construct of type Asn1Value.Return Value:
INTEGER. <result> is a a handle of type INTEGER. If there is a failure that prevents implementation of the subscription, -1 is returned. Otherwise, a handle index is returned; this handle can be passed to the unsubscribe() function to terminate the subscription.It is recommended that you check for a return value of -1 to determine if errors have been encountered. For example, if the syntax of the CMIS filter passed as <cmis_filter_string> is incorrect, -1 will be returned.
This command subscribes for events that match the specified CMIS filter. If an event passes the filter, it will be forwarded to the request. The CMIS filter can be passed to the function either as a string or as an ASN.1 value. For information on the format of a CMIS filter, refer to Chapter 6 in Developing C++ Applications.
22.2.40.1 Considerations
- If you invoke two subscriptions using CMIS filters and one filter selects a subset of the other, your request will receive duplicate events for the overlapping subset. An example of this would be the following two subscriptions:
$myFilter = strToAsn("CMIP-1.CMISFilter","or: {item: equality: {objectClass,mosi}, item: equality: {eventType, internetAlarm}}");$index = subscribeFilter($myFilter);$myFilter = strToAsn("CMIP-1.CMISFilter", "item: equality: {eventType, internetAlarm}");$index = subscribeFilter($myFilter);
- If these two subscriptions are invoked, each incoming internetAlarm is forwarded twice to the request. You should tailor your event subscriptions so as to avoid this duplication of events.
- When a subscription is created using a CMIS filter, every event in the system is checked against that filter. Additional filter subscriptions thus place an increasing load on the MIS. To avoid an adverse impact on performance, it is recommended that you exercise care in the use of filter subscriptions.
22.2.40.2 Examples
- The following is an example of a subscription that passes a CMIS filter that forwards all events to a request:
$index = subscribeFilter("and : { }");
- This same CMIS filter could be passed as an ASN.1 value:
$filter = strToAsn("CMIP-1.CMISFilter","and : { }");$index = subscribeFilter($filter);- A CMIS filter could be used to forward all events of a specified managed object class to the request. For example, all nerveCenterAlarm, generated using the RCL alarm-logging functions (alarm(), alarmOi(), alarmStr())s are instances of a managed object class called mosi. The following filter forwards to the request all events whose managed object class is mosi.
$filter = strToAsn("CMIP-1.CMISFilter", "item: equality {managedObjectClass, mosi}");$index = subscribeFilter($filter);
- This same CMIS filter could be passed as a string:
$index = subscribeFilter("item: equality {managedObjectClass, mosi}");- The following example uses a CMIS filter that selects all events whose managed object class is system and whose eventType is communicationsAlarm:
$filter = strToAsn("CMIP-1.CMISFilter", "and: {item: equality: {managedObjectClass, system}, item: equality: {eventType, communicationsAlarm}}");$index = subscribeFilter($filter);22.2.41 SubscribeOi
Syntax:
SubscribeOi( <event_name_str> , <oc_str >, <event_oi>);
where <event_name_str> and <oc_str> are of type OCTET STRING and <event_oi> is of type ObjectInstance.For example:
$lkidx = subscribeOi("linkDownTrap","cmipsnmpProxyAgent",$pollfdn);$lkType=NameToOid("linkDownTrap");true;subscribeOi() is used to subscribe to events of a specific type that concern objects of a specific type, a specific object class, or a specific object instance. The <event_name_str> must be one of the event names that appears as a NOTIFICATION in a GDMO document that the MIS knows about.
The <event_oi> argument is an ObjectInstance specifying the instance of interest.
The <oc_str> argument specifies the object class of interest. The function will accept an empty string "{}" as the value of <oc_str>, and in that case supplies the class to which <event_oi> belongs. However, for performance reasons it is preferable to supply the object class explicitly.
If a failure occurs that prevents implementation of the subscription, -1 is returned. Otherwise, this function returns a handle index; that is, a unique index for a subscription in a request. This handle can be passed in a call to the unsubscribe() function to terminate the event subscription.
Currently when a request is disabled or deleted, its subscription(s) are automatically deleted also.
Note – In composing a condition that tests for object creation, use subscribeOi(), rather than subscribe(), and subscribe to the creation of only a specific type of object. Do not listen for all object creations, as this can result in an infinite loop.
22.2.42 TrapGenericType
Syntax:
TrapGenericType( <info>);
where <info> is an event of type InternetAlarmInfo.Returns the number of the GenericType of the received trap (for example, from $eventInfo). For example:
Note – $eventInfo in this example must be an internetAlarm.
The possible return values are described in the following table.
TABLE 22-6 Standard SNMP Trap Types 0 coldStart The originating SNMP device is reinitializing itself, typically due to unexpected reboot. 1 warmStart The originating SNMP device is reinitializing itself, typically due to normal restart. 2 linkDown One of the agent's communication links is down. The first name/value pair in the variable bindings is the ifIndex for the interface. 3 linkUp One of the agent's communication links has come up. The first name/value pair in the variable bindings is the ifIndex for the interface. 4 authenticationFailure The originating system has received a protocol message that has failed authentication. 5 egpNeighborLoss An External Gateway Protocol peer has been marked down. 6 enterpriseSpecific Further information about the event is indicated in the <specific-trap> field.
22.2.43 TrapSpecificType
Syntax:
TrapSpecificType( <info>);
where <info> is an event of type InternetAlarmInfo.Returns the number of the SpecificType of the received trap (for example, from $eventInfo). For example:
Note – $eventInfo in this example must be an internetAlarm. This function does not apply to the enterpriseSpecificTrap event notifications to which Solstice EM maps SNMP enterprise-specific traps by default. To obtain the specific trap number from enterpriseSpecificTrap notifications, use the Extract() function to obtain the value of the probableCause attribute. Refer to Section 22.2.12 Extract."
22.2.44 Undefine
Syntax:
Undefine(&<Var>);
where <Var> is a variable; or
undefine(&<Attr>);
wher e <Attr> is an attribute.Return Value:
BOOLEAN. Always returns TRUE.Sets the variable <Var> or the attribute <Attr> to have no value.
The IsSnmpSystemUp sample template illustrates the use of the undefine function. The availability of the target device is tested using a call to define in the IsSystemDescr sample condition.
Once this condition returns true, however, the value will always remain true unless the undefine function is called, as in the UndefineSystemDescr sample condition.
Once the value of sysDescr has been undefined, the IsSystemDescr sample condition can once again invoke the define the function to test for system availability.
22.2.45 Unixcmd
Syntax:
Unixcmd(<command>,<arguments>);
where <command> and <arguments> are both of type OCTET STRING.Executes the indicated UNIX command. This is the equivalent of the UNIXCMD action. The <arguments> parameter can contain RCL variables, either alone or embedded inside a quoted string. For example:
UnixCmd("echo","$pollfdn > /tmp/mydata");22.2.46 UnSubscribe
Syntax:
UnSubscribe(<subscription_handle>);where <subscription_handle> is an INTEGER value returned from a previous call of one of the subscription functions, such as subscribe() or subscribeOi(). This function can be used to turn off a previous event subscription.
|
Sun Microsystems, Inc. Copyright information. All rights reserved. |
Doc Set | Contents | Previous | Index |