Table Of Contents

IMO Specification

IMO Format/Syntax

IMO OIDs

Format and Syntax

OID Example

Sample OID Hierarchies

Alcatel ASAM - Physical Object

Lucent CBX - Physical Object

Redback SMS - Physical Object

Redback SMS - Logical Object

IMO Primitives

IMO Constructs

Nesting IMO Objects

IMO Object Arrays

Complex Constructs

Retrieval Specifications

Defining the Retrieval Scope

Specifying the Retrieved IMO Types

IMO Type Inheritance

Excluding IMO Types and Properties

Format and Syntax of a Retrieval Specification

Aspects

Example

Specifying Properties vs. Aspects

Required Aspects vs. Excluded Aspects

Registrations and Notifications

Registering for Notifications

Unregistering

Notifications

IScalarNotification

IAddNotification

IRemoveNotification

IObjectDeleteNotification

IMO Specification

---

IMO Format/Syntax

Table 21-1 presents the general XML format of an IMO object.

Table 21-1 XML Format of an IMO Object 

IMO	<IMO_TYPE> IMO_OID IMO_PROPERTIES </IMO_TYPE>
IMO_OID	<ID type="Oid"> OID_FORMAT </ID>
IMO_PROPERTIES	SIMPLE_PROPERTY | PROPERTIES_ARRAY
SIMPLE_PROPERTY	<PROPERTY_NAME type=PROPERTY_TYPE> PROPERTY_VALUE </PROPERTY_NAME>
PROPERTIES_ARRAY	<PROPERTY_NAME type=IMObjects_Array> IMO < IMObjects_Array>
OID_FORMAT	A valid string encoding of an OID
PROPERTY_NAME	String representing property name
PROPERTY_TYPE	String representing a valid type. This can be either a primitive type or an IMO type
PROPERTY_VALUE	String representation of a property value

IMO OIDs

An IMO OID (Object Identifier) is the unique identifier of every IMO instance in the system. The OID uniquely identifies every IMO object by providing a cascading structure that describes the location of the entity. For example, the OID of a specific port in a typical NE is formatted by cascading the NE IP address, Shelf number, Module number, and Port number.

Different device types can have different OID schemas. For example, a port OID in some NE might also include such items as submodules or subslots.

Format and Syntax

Table 21-2 IMO OID Format and Syntax 

OID	{INTERFACE_LIST}
INTERFACE_LSIT	INTERFACE | INTERFACE INTERFACE_LIST
INTERFACE	[INTERFACE_NAME] | [INTERFACE_NAME(INTERFACE_PARAMS)]
INTERFACE_NAME	String representation of a physical hierarchy in the device
INTERFACE_PARAMS	KEY=VALUE| KEY=VALUE, INTERFACE_PARAMS
KEY	String
VALUE	String

OID Example

In this example, the OID of Port 3 on module 1, subslot C of the NE "London5" is:

{[ManagedElement(Key=London5)][PhysicalRoot][Chassis] 
[Slot(SlotNum=1)][Module][Slot(SlotNum=C)][Module] 
[Port(PortNumber=3)]}

Figure 21-1 illustrates the hierarchy of this OID.

Figure 21-1 OID Hierarchy

Sample OID Hierarchies

As described in previous sections, each NE type can have its own IMO schema, that is, different object types and tree hierarchy. To specify the correct OID for each NE, the client application must be familiar with the OID hierarchy of the relevant NE. The following sections provide examples of IMO hierarchies.

Alcatel ASAM - Physical Object

The OID of a port of an Alcatel ASAM is encoded:

{[ManagedElement(Key=ASAMLab)][PhysicalRoot][Chassis] 
[Shelf(ShelfNum=1)][Slot(SlotNum=NTA)][Module] 
[Port(PortNumber=1)]}

Figure 21-2 illustrates the physical hierarchy represented by this OID.

Figure 21-2 Alcatel ASAM Port OID

Lucent CBX - Physical Object

The OID of a port of a Lucent CBX is encoded:

{[ManagedElement(Key=CBX500Lab)][PhysicalRoot][Chassis] 
[Slot(SlotNum=12)][Module][Port(PortNumber=6)]}

Figure 21-3 illustrates the physical hierarchy represented by this OID.

Figure 21-3 Lucent CBX Port OID

Redback SMS - Physical Object

The OID of a port of a Redback SMS is encoded:

{[ManagedElement(Key=RB1)][PhysicalRoot][Chassis] 
[Slot(SlotNum=7)][Module][Port(PortNumber=1)]}

Figure 21-4 illustrates the physical hierarchy represented by this OID.

Figure 21-4 RedBack SMS Port OID

Redback SMS - Logical Object

The OID of a logical object (IP interface) of a RedBack SMS is encoded:

{[ManagedElement(Key=RB1)][LogicalRoot] 
[Context(ContextName=cyberworks.net.sg)][RoutingEntity] 
[IpInterface(IPAddress=10.254.253.37)]}

Figure 21-5 illustrates the logical hierarchy represented by this OID.

Figure 21-5 RedBack SMS Logical OID

IMO Primitives

When encoding an IMO object, each of its properties can be either a primitive (basic) type or another IMO. The simplest case is when all properties of the IMO are primitives, as in the following example:

<IManagedElement>

<ID type="Oid">{[ManagedElement(Key=CBX500Lab)]}</ID>

<CommunicationStateEnum type="Integer">3

</CommunicationStateEnum>

<DeviceName type="String">CBX500Lab</DeviceName>

<ElementCategoryEnum type="Integer">2

</ElementCategoryEnum>

<ElementTypeEnum type="Integer">22</ElementTypeEnum>

<IP type="com.sheer.types.IPAddress">192.168.2.70</IP>

<InvestigationStateEnum type="Integer">2

</InvestigationStateEnum>

<SoftwareVersion type="String">04.02.01.00

</SoftwareVersion>

<VendorEnum type="Integer">6</VendorEnum>

</IManagedElement>

Table 21-3 describes the primitive types that can be used for IMO object properties.

Table 21-3 IMO Primitive Types 

Type	Description	Example
Int	4 Bytes integer	1
Long	8 Bytes integer	100
String		"John Smith"
Counter	Counter representation	Octet counter: <long> octets Packet counter: <long> packets
Ipaddress	IP address	192.168.2.23
Macaddress	MAC address	ABAECD FCBBCD
Ipsubnet	IP address, mask ip address	202.79.94.0, 255.255.255.192
Key	String identifier	"Redback17"
Speed	Speed representation with units	<long> Cells/sec <long> bps <long> Kbps <long> Mbps <long> Gbps <long> Cell/sec
Rate	Rate representation with units	<long> bps <long> Kbps <long> Mbps <long> Gbps <long> Bps <long> KBps <long> MBps <long> GBps <long> Cell/sec
vpvcrange	Define available range for VCs	If minimal vp=maximal vp: VP: <integer min vp>, VC: <integer min vc>..<integer max vc>   Otherwise: VP: <integer min vp>.. VP: <integer max vp>, VC: <integer min vc>.. VC: <integer max vc>
vprange	Available vps range	<integer min vp>..<integer max vp>
vpvcrangecollection	A collection of available VCs ranges	[vpvcrange][ vpvcrange]...

IMO Constructs

IMO constructs support recursive nesting of IMO objects as well as arrays of IMO objects. Topics in this section include:

•Nesting IMO Objects

•IMO Object Arrays

•Complex Constructs

Nesting IMO Objects

Each of the properties of an IMO object can be an IMO object by itself. In this case, the type of the property is one of the existing IMO types. For example:

<technologies.IAtm>

<Bandwidth type="technologies.IAtmBandwidthTrafficDescriptor">

<TxMaxBandwidth type="com.sheer.types.Speed">0.0 bps 
       </TxMaxBandwidth>

<TxUbrAllocBandwidth type="com.sheer.types.Speed">13.86 Mbps 
       </TxUbrAllocBandwidth>

</Bandwidth>

</technologies.IAtm>

In this example, the IMO object of type technologies.IAtm contains a property called Bandwidth, which is an IMO object of the type technologies.IAtmBandwidthTrafficDescriptor.

The following example combines both primitives and nested IMOs:

<technologies.IAtm>

<Bandwidth type="technologies.IAtmBandwidthTrafficDescriptor">

<TxMaxBandwidth type="com.sheer.types.Speed">0.0 bps 
       </TxMaxBandwidth>

<TxUbrAllocBandwidth type="com.sheer.types.Speed">13.86 Mbps 
       </TxUbrAllocBandwidth>

</Bandwidth>

<VcsTableSize type="Integer">50</VcsTableSize>

<VpVcRange type="String">[VP: 0..4096, VC: 0..65536]</VpVcRange>

</technologies.IAtm>

IMO Object Arrays

The general format of the encoding of an IMO array is:

<IMObjects_Array>

IMO1

IMO2

...

</IMObjects_Array>

The following example of an IMO construct includes an array of two IMO objects of the type IManagedElement:

<IMObjects_Array>

  <IManagedElement>

   <ID type="Oid">{[ManagedElement(Key=CBX500Lab)]}</ID>

    <DeviceName type="String">CBX500Lab</DeviceName>

    <CommunicationStateEnum type="Integer">3 
        </CommunicationStateEnum>

  </IManagedElement>

  <IManagedElement>

    <ID type="Oid">{[ManagedElement(Key=CBX_Iftach)]}</ID>

    <CommunicationStateEnum type="Integer">3 
        </CommunicationStateEnum>

    <DeviceName type="String">CBX_Iftach</DeviceName>

  </IManagedElement>

</IMObjects_Array>

Complex Constructs

This example combines the properties of type IMO with IMO arrays to create a nested construct of IMO objects:

<IVrf>

  <ID type="Oid">{[ManagedElement(Key=DallsPE)][LogicalRoot] 
         [FWComponentContainer(Type=3)][Vrf(VrfName=ACME)]}</ID>

  <Name type="String">ACME</Name>

  <RouteDistinguisher type="IRouteDistinguisher">

     <ID type="Oid">{[ManagedElement(Key=DallsPE)][LogicalRoot] 
        [FWComponentContainer(Type=3)][Vrf(VrfName=ACME)] 
        [RouteDistinguisher]}</ID>

     <RouteDistinguisher type="String">3603:1</RouteDistinguisher>

  </RouteDistinguisher>  

  <VrfTable type="IMObjects_Array">

    <technologies.IVrf>

      <ID type="Oid">{[ManagedElement(Key=DallsPE)][LogicalRoot] 
          [FWComponentContainer(Type=3)][Vrf(VrfName=ACME)] 
          [VrfEntry(IP=172.16.101.0)]}</ID>

      <BGPNextHop type="">Null</BGPNextHop>

      <InnerLabel type="">Null</InnerLabel>

      <NextHop type="IPAdderss">172.16.101.254</NextHop>

      <RouteDest type="IPAdderss">172.16.101.0</RouteDest>

      <RouteMask type="IPAdderss">255.255.255.0</RouteMask>

      <RouteProtocolTypeEnum type="Integer">14 
            </RouteProtocolTypeEnum>

      <TypeEnum type="Integer">3</TypeEnum>

               </technologies.IVrf>    

    <technologies.IVrf>

      <ID type="Oid">{[ManagedElement(Key=DallsPE)][LogicalRoot] 
           [FWComponentContainer(Type=3)][Vrf(VrfName=ACME)] 
           [VrfEntry(IP=192.168.107.207)]}</ID>

       <BGPNextHop type="">Null</BGPNextHop>

       <InnerLabel type="">Null</InnerLabel>

       <NextHop type="">Null</NextHop>

       <RouteDest type="IPAdderss">192.168.107.207</RouteDest>

       <RouteMask type="IPAdderss">255.255.255.255</RouteMask>

       <RouteProtocolTypeEnum type="Integer">14 
           </RouteProtocolTypeEnum>

       <TypeEnum type="Integer">3</TypeEnum>

     </technologies.IVrf>    

  </VrfTable>

</Vrf>

Retrieval Specifications

The Retrieval Specification (RS) defines the scope of information to be retrieved by a GET or FIND command. It describes the IMO objects that are returned as well as the properties that are returned in each IMO object. The retrieval specification allows you to include or exclude every element in the result.

The RS also allows registering for change notifications to be sent whenever a property changes within the specified data scope. Registration for changes enables, for example, receiving notifications on port or module status change, or any changes in the configuration of the network.

The retrieval specification has another section that refers to Aspects. For more information, see Aspects.

Defining the Retrieval Scope

The retrieval specification is an XML string that represents the scope and structure of the result of a GET query. It defines the IMO objects that should be included in the answer and the properties that should be included for each IMO object type. Consider, for example, the following retrieval specification:

<param name="oid">     

<value>{[ManagedElement(Key=DallasPE)]}</value>   

</param>   

<param name="rs">     

  <value>

    <key name="RS1">

     <key name="requiredProperties">

      <key name="com.sheer.imo.IManagedElement">

        <entry name="*"/>

        </key>

      </key>

  </key>

  </value>   

</param>

This retrieval specification specifies that:

•The answer is to contain only objects of type IManagedElement.

•For each object of that type, it is to include all of its properties.

The name of the retrieval specification (RS1) is an optional string identifier that is used only for readability of the XML and is ignored when the query is processed.

The following example demonstrates the general format of a retrieval specification. It lists the IMO types and the properties within each IMO type that are to be included in the reply.

<param name="rs">     

  <value>

    <key name="RS_name">

      <key name="requiredProperties">

        <key name=IMO_TYPE_A>

        <entry name=PROPERTY_1/>

  <entry name=PROPERTY_2/>

  ...

        </key>

     <key name=IMO_TYPE_B>

  <entry name=PROPERTY_1/>

  <entry name=PROPERTY_2/>

  ...

      </key>

      </key>

  </key>

  </value>   

</param> 

To include all IMO types in the result use "*" as the IMO type. Similarly, to include all properties of a given IMO type use "*" as the property name.

<param name="rs">     

<value>

<key name="RS1">

    <key name="requiredProperties">

    <key name="* ">

      <entry name="*"/>

      </key>

    </key>

</key>

</value>   

</param>

In this example, the "*" wildcard is specified twice: First to indicate all IMO types, and then to indicate all properties in the objects. If only the IMO type wildcard were specified, the result would be empty IMO objects with no properties.

Specifying the Retrieved IMO Types

BQL determines the IMO types to retrieve by recursively traversing the containment (nesting) references between the IMO objects in the Cisco ANA information model, starting from the root object OID specified as part of the GET command. During this recursive traversing, each object that is found is tested against the IMO types in the RS and is retrieved only if it matches any of these types. Consider the example:

<param name="rs">

<value>

<key name="RS_name">

    <key name="requiredProperties">

    <key name=IMO_TYPE_A>

      <entry name=PROPERTY_1/>

   <entry name=PROPERTY_2/>

    ...

      </key>

   </key>

  <key name=IMO_TYPE_B>

  <entry name=PROPERTY_1/>

  <entry name=PROPERTY_2/>

    </key>

</key>

</value>   

</param>

Assume that IMO_TYPE_A contains IMO_TYPE_C as one of its properties. Since the example requests all properties of IMO_TYPE_A, then, IMO_TYPE_C appears in the result since it is a property of IMO_TYPE_A. However, it appears empty (that is, without properties, except for its OID), since IMO_TYPE_C is not included in the retrieval specification.

To demonstrate this, look at the following RS example:

<param name="oid">

<value>{[ManagedElement(Key=DallasPE)]}</value>   

</param>   

<param name="rs">     

  <value>

    <key name="RS1">

     <key name="requiredProperties">

      <key name="com.sheer.imo.IManagedElement">

        <entry name="*"/>

        </key>

      </key>

  </key>

  </value>   

</param>

In this example, the RS specifies the inclusion of the IMO type IManagedElement with all its properties. Since the root object (the NE) is of type IManagedElement, the NE object is returned with all its properties. However, some of the NE properties are by themselves IMO objects, such as PhysicalRoot and LogicalRoot (of the IMO types IPhysicalRoot and ILogicalRoot, respectively). Because the RS does not specify these IMO types in the "includedProperties" section, they appear empty; that is, they appear as properties of the IManagedElement object, with their OID only.

1	NE properties
2	Logical inventory (empty)

However, if IPhysicalRoot or ILogicalRoot had been included in the required IMO types, BQL would have traversed these objects as well, retrieved their properties, and continued to test their contained objects against the included IMO types, recursively.

The above examples demonstrate the recursive nature of the retrieval specification. BQL browses all nested IMO objects in the Cisco ANA information model, and tests them against the specified IMO types in the RS.

An important factor with regard to the recursive nature of the retrieval specification is having a stopping criterion for information retrieval. When retrieving an IMO object, the system recursively traverses all properties of the retrieved IMO and, for each property that is a nested IMO object, it continues to traverse it. Therefore, the included IMO types in the RS should be designed in a way that controls the depth of the returned data.

IMO Type Inheritance

IMO objects are defined through an inheritance scheme. For example, CTP objects, such as IAtm or IAdsl, are all derived from (children of) a common base type, IConnectionTerminationPoint. It is enough to specify a base type in the RS so that all derived types are implicitly included.

Assume there are two IMO types (IMO_TYPE_A and IMO_TYPE _B), where IMO_TYPE_B inherits from (is the child of) IMO_TYPE _A. Now, assume that a GET command is executed with the following retrieval specification in which the root object is of type IMO_TYPE_B:

<param name="oid">

<value>{Some-object-of-type-B)]}</value>   

</param>   

<param name="rs">     

<value>

<key name="RS3">

<key name="requiredProperties">

<key name=IMO_TYPE_A>

      <entry name=PROPERTY_1/>

    <entry name=PROPERTY_2/>

      </key>

</key>

</key>

</value>

</param>

When processing the properties of the root object, the system inspects the retrieval specification and detects that its IMO type (IMO_TYPE_B) is not included. However, it detects that its ancestor (IMO_TYPE_A) is included in the retrieval spec, and the object is qualified for retrieval (with the properties PROPERTY_1 and PROPERTY_2). In other words, to specify the retrieval specification of an object, it is sufficient to specify the retrieval specification for any of its ancestors.

On the other hand, if IMO_TYPE_B is specified, it overrides any specification of its ancestors (in this case, IMO_TYPE_A). For example, assume the RS is modified as follows:

<param name="oid">

<value>{Some-object-of-type-B)]}</value>   

</param>   

<param name="RS4">     

<value>

<key name="RS_name">

<key name="RequiredProperties">

<key name=IMO_INTERFACE_A>

<entry name=PROPERTY_1/>

<entry name=PROPERTY_2/>

</key>

<key name=IMO_INTERFACE_B>

<entry name=PROPERTY_3/>

</key>

</key>

</key>

</value>   

</param> 

In this case, the result includes only PROPERTY_3, although its ancestor (IMO_TYPE_A) specified also PROPERTY_1 and PROPERTY_2. This is because specifying a retrieval specification for an interface overrides any retrieval specification defined for its ancestors.

Inheritance schemes enable us to simplify and generalize the retrieval specification. For example, in the case of CTPs, it is enough to specify the base type IConnectionTerminationPoint in the retrieval spec. This ensures that the whole CTP containment chain (all network layers) are retrieved.

The specific details and inheritance scheme of all IMO objects are described in the IMO reference manual.

Excluding IMO Types and Properties

Similar to the requiredProperties key, which specifies which IMO types and properties to include in the result, there is the key excludedProperties, which describes the properties to exclude from the result. This modifier is useful for filtering unneeded properties from the answer. For example:

<param name="oid">     

<value>{[ManagedElement(Key=Fore251Lab)]}</value>   

</param>   

<param name="rs">     

  <value>

    <key name="RS2">

      <key name="requiredProperties">

      <key name="com.sheer.imo.IManagedElement">

        <entry name="*"/>

      </key>

    </key>

  <key name="excludedProperties">

  <key name="com.sheer.imo.IManagedElement>

  <entry name="PhysicalRoot"/>

  </key>

  </key>

  </key>

  </value>   

</param>

In this case, the whole IManagedElement object is retrieved, including all properties, except for PhysicalRoot.

The include and exclude sections are AND-ed, that is, if the same property appears both in the requiredProperties and in the excludeProperties sections, the excludeProperties section prevails and the property is discarded.

Format and Syntax of a Retrieval Specification

The XML layout of the Retrieval Specification is:

<param name="rs">     

<value>

<key name="[rs name]">

  <entry name="register">[true/false]</entry>

  <key name="requiredProperties">

    <key name=[* or IMO type]>

      <entry name=[* or property name]/>

      <entry name=[* or property name]/>

    . . .

    </key>

  </key>

  <key name="excludedProperties">

    <key name=[* or IMO type]>

      <entry name=[* or property name]/>

      <entry name=[* or property name]/>

      . . .

    </key>

  </key>

  <key name="requiredAspects">

    <key name=[* or oid type]>

      <entry name=[* or aspect oid type]/>

      <entry name=[* or aspect oid type]/>

       . . .

    </key>

  </key>

  <key name="excludedAspects">

    <key name=[* or oid type]>

      <entry name=[* or aspect oid type]/>

      <entry name=[* or aspect oid type]/>

       . . .

    </key>

  </key>

</key>

</value>

</param>

This example demonstrates the following conventions:

•The name of the retrieval spec (rs name) is optional and used only for readability of the XML.

•The register entry indicates whether to register for changes on the objects that match the retrieval specification. This flag is optional and can be omitted. If it is not specified, it is assumed to be false. See Specifying Properties vs. Aspects for a description of registrations and notifications.

•The requiredProperties key indicates properties to include in the result. The excludedProperties key indicates properties to exclude from the result. The requiredAspects indicates aspects to attach to the result. These modifiers are optional and can be discarded from the retrieval specification.

•For included and excluded properties, you can specify a property name or wildcard ("*") to represent all properties.

•A property that is both required and excluded is excluded.

Aspects

Aspects are persistent information from the Cisco ANA database, such as alarm history or business information entities, that can be dynamically attached to any IMO object. The Cisco ANA fabric models only autodiscovered network information, and therefore does not maintain any historical or business information. Examples of business information include administrative details of the configured subscribers (such as name or phone number), descriptive labels for network objects, and alarm history. The aspects mechanism allows you to couple network information with persistent information of this type.

You can attach aspects to every IMO object by specifying the required aspects in the requiredAspects and excludedAspects sections in the RS. For example:

<command name="Get">   

<param name="oid">     

  <value>{[Snapshot]}</value>   

</param>   

<param name="rs">     

  <value>

    <key name="RS5">

      <entry name=\"register\">false</entry>

      <key name=\"requiredProperties\">

        <key name=\"com.sheer.imo.IManagedElement\">

           <entry name=\"*\"/>

        </key>

      <key name=\"com.sheer.imo.IAlarmList\">

         <entry name=\"*\"/>

      </key>

      <key name=\"com.sheer.imo.ICompiledAlarm\">

         <entry name=\"*\"/>

      </key>

      </key>

      <key name="excludedProperties">

        <key name="com.sheer.imo.topology.ISnapshot">

            <entry name="Links"/>

       </key>

      </key>

      <key name="requiredAspects">

        <key name="com.sheer.imo.keys.IManagedElementOid">

          <entry name="com.sheer.imo.keys.IAlarmListOid"/>

        </key>

      </key>

    </key>

  </value>   

</param> 

</command>

This GET command retrieves the network snapshot, excluding links (that is, retrieves the list of devices). The aspects section of the retrieval specification is given by:

<key name="requiredAspects">

<key name="com.sheer.imo.keys.IManagedElementOid">

<entry name="com.sheer.imo.keys.IAlarmListOid"/>

</key>

</key>

This aspects specification states that the GET command is to attach a list of all corresponding alarms to each returned ManagedElement IMO object. The alarm list for each NE in the snapshot is an example of the information that resides in the Cisco ANA database and that cannot be inferred from the network.

The aspects section in the retrieval specification is processed as follows:

1. The Cisco ANA system executes the GET command with the given retrieval specification while ignoring the aspects. The query generates an IMO construct that contains all information matching the retrieval specification.

2. Cisco ANA inspects each IMO in the result, including IMOs that are properties of other IMOs. For each such IMO, it determines if the OID matches any of the OIDs in the aspects section in the retrieval specification. If so, it executes an internal GET command for the respective aspects.

3. Cisco ANA then attaches each aspect to its respective IMO object (according to the OID) and returns the combined output. Aspects are attached in the XML response under a key called Aspects of type IMObjects_array (even if the array contains only one element).

Example

Executing the command in Aspects returns the following reply, which is a list of the NEs in the network, each with its related alarms. In this case, there is one NE:

<IManagedElement>

  <ID type="Oid">{[ManagedElement(Key=ASAMSim)]}</ID>

  <CommunicationStateEnum type="Integer">3 
     </CommunicationStateEnum>

  <DeviceName type="String">MINIRAMSim</DeviceName>

  <ElementCategoryEnum type="Integer">1</ElementCategoryEnum>

  <ElementTypeEnum type="Integer">27</ElementTypeEnum>

  <InvestigationStateEnum type="Integer">2 
     </InvestigationStateEnum>

  <SysContact type="String">Alcatel</SysContact>

  <SysDescription type="String">ASAM</SysDescription>

  <SysLocation type="String">Alcatel Bell-Antwerpen 
     </SysLocation>

  <SysName type="String">ASAM</SysName>

  <SysUpTime type="java.util.Date"> 
       Mon Feb 03 11:32:28 IST 2003</SysUpTime>

  <VendorEnum type="Integer">2</VendorEnum>

</IManagedElement>

  <Aspects type="IMObjects_Array">

    <IAlarmList>

      <ID type="Oid">{[ManagedElement(Key=ASAMSim)] 
           [AlarmList]}</ID>

      <Alarms type="IMObjects_Array">

        <ICompiledAlarm>

          <ID type="Oid">{[CompiledAlarm(Id=969)]}</ID>

          <AckStatusEnum type="Integer">0</AckStatusEnum>

          <ActiveAlarmCount type="Integer">3 
              </ActiveAlarmCount>

          <AffectedSncNum type="Integer">53</AffectedSncNum>

          <AlarmType type="Integer">1</AlarmType>

          <CategoryEnum type="Integer">0</CategoryEnum>

          <Description type="">Null</Description>

          <EventTime type="java.util.Date"> 
               Mon Feb 03 17:05:47 IST 2003</EventTime>

          <LatestModificationTime type="java.util.Date"> 
               Mon Feb 03 17:09:47 IST 2003 
               </LatestModificationTime>

          <PerceivedSeverityEnum type="Integer">2

              </PerceivedSeverityEnum>

          <RemoveApproved type="Boolean">false 
              </RemoveApproved>

          <RootCause type="String">Link Up</RootCause>

          <Source type="Oid"> 
             {[TopologicalLink(LinkIdentifier=10.10.12.14- 
              10.10.12.22_168430606_5365972917668516095_ 
              168430614_5365493598785573887_bi_)]}</Source>

        </ICompiledAlarm>

      </Alarms>

    </IAlarmList>

   </Aspects>

Specifying Properties vs. Aspects

The aspects section is used only to attach the database object OID to the network IMO object. The actual data contents of the database IMO construct is specified in the requiredProperties section (same as for the network IMO objects). In Example, the requiredAspects section extended the ManagedElement IMO object (the NE) to include the database IMO object of type IAlarmListOid (which is the OID of the alarm container). However, to retrieve the actual alarms information, it must be specified in the requiredProperties section:

<key name=\"com.sheer.imo.IAlarmList\">

<entry name=\"*\"/>

</key>

<key name=\"com.sheer.imo.ICompiledAlarm\">

<entry name=\"*\"/>

</key>

This instructs BQL to retrieve the AlarmList container and all of its contained alarm objects (of type ICompiledAlarm).

Required Aspects vs. Excluded Aspects

As described in Specifying Properties vs. Aspects, the aspects section is used only to attach database objects to network IMO objects, while the data retrieval scope in these database objects is specified in the requiredProperties section. Similarly, the excludedAspects section is used only to fine-tune the attachment definition, and not to specify the retrieval data scope. An example of the relationship between requiredAspects and excludedAspects can be demonstrated in the case of IMO inheritance. Assume a generic database IMO type A and an inherited (more specific) IMO type B, which is derived from A. By specifying the attachment of objects of type A in the requiredAspects section, and object type B in the excludedAspects section, the result is that all objects of type A (and their derivatives) are attached, except for objects of type B (and their derivatives).

Registrations and Notifications

This section includes:

•Registering for Notifications

•Unregistering

•Notifications

Registering for Notifications

If the register flag in the retrieval specification is set to "true", the system returns the IMO construct that matches this retrieval specification and registers for changes of the data. Registering for changes is always performed as "Get and Register". Any change detected in any of the data items is sent in an unsolicited message to the BQL client.

When a BQL session is closed, the system clears all registrations associated with that session. Therefore, you do not need to explicitly unregister before closing the BQL session.

When registering for notifications, users can optionally specify a registration ID for each registration. This registration ID can be used later for unregistering. The registration ID should be unique, and it is up to the client application to ensure uniqueness. If a user performs two registrations with the same ID, the second registration overrides the first. The first registration remains active and sends notifications, but the user cannot unregister it. In such situations, the only way to unregister the first registration is by issuing an unregister all command.

To specify a command ID in a register command, append commandId=ID to the beginning of the GET command. For example:

commandId=5

<command name="Get">

  <param name="oid">

    <value>{[ManagedElement(Key=RB1800Sim)]}</value>

  </param>

  <param name="rs">

    <value>

      <key name="RS6">

          <entry name="register">true</entry>

          <key name="requiredProperties">

              <key name="com.sheer.imo.ICompiledAlarm">

                  <entry name="*"/>

              </key>

          </key>

      </key>

    </value>

  </param>

</command>

Unregistering

To unregister a specific registration ID, send an unregister command with the command ID as a parameter. For example:

<command name="unregister">

<param name="commandId">

<value>5</value>

</param>

</commands>

To unregister all previous registrations, use "all" as the command ID:

<command name="unregister">

<param name="commandId">

<value>all</value>

</param>

</commands>

When the system detects a change in a registered object, it responds with an unsolicited notification message, which is described in Notifications.

Notifications

A notification is an IMO object that describes the change in another IMO. For example:

commandId=7

<IMObjects_Array>

  <IScalarNotification>

    <ID type="Oid">{[Notification(SequenceNumber=249) 
       (Time=1052903741029)]}</ID>

    <PropertyName type="String">RemoveApproved</PropertyName>

    <NewIMO type="ICompiledAlarm">

      <ID type="Oid">{[CompiledAlarm(Id=7)]}</ID>

      <RemoveApproved type="Boolean">true</RemoveApproved>

    </NewIMO>

    <OldIMO type="ICompiledAlarm">

      <ID type="Oid">{[ManagedElement(Key=RB1800Sim)] 
          [AlarmList][CompiledAlarm(Id=7)]}</ID>

      <RemoveApproved type="Boolean">false</RemoveApproved>

    </OldIMO>

  </IScalarNotification>

</IMObjects_Array>

In this example, the notification indicates that in the IMO object of type ICompiledAlarm, the property RemoveApproved changed state from "false" to "true". The notification is always of type IMObjects_Array and contains an IMO object for each notification. In this example it contains only a single notification of type IScalarNotification, which indicates a change in a single property. The notification includes the registration ID and, for each object, the changed property type, time, sequence number, new value, and old value.

IScalarNotification

IScalarNotification describes changes in one or more properties of an IMO object. Consider the example:

commandId=7

<IMObjects_Array>

  <IScalarNotification>

    <ID type="Oid">{[Notification(SequenceNumber=249) 
       (Time=1052903741029)]}</ID>

    <PropertyName type="String">RemoveApproved</PropertyName>

    <NewIMO type="ICompiledAlarm">

      <ID type="Oid">{[CompiledAlarm(Id=7)]}</ID>

      <RemoveApproved type="Boolean">true</RemoveApproved>

    </NewIMO>

    <OldIMO type="ICompiledAlarm">

      <ID type="Oid">{[ManagedElement(Key=RB1800Sim)] 
          [AlarmList][CompiledAlarm(Id=7)]}</ID>

      <RemoveApproved type="Boolean">false</RemoveApproved>

    </OldIMO>

  </IScalarNotification>

</IMObjects_Array>

IScalarNotification has four elements:

Oid	The OID of the notification. Identifies the sequence number and the time of the notification.
NewIMO	The IMO object after the change.
OldIMO	The IMO object before the change.
PropertyName	The property in the IMO that was changed.

In the example, the scalar notification describes a change in the property RemoveApproved for a specific alarm of the device RB1800Sim.

IAddNotification

IAddNotification indicates that an IMO object was added to the system. For example:

commandId=alarms1

<?xml version="1.0" encoding="UTF-8"?>

<IMObjects_Array>

  <IAddNotification>

    <ID type="Oid">{[Notification(SequenceNumber=253) 
       (Time=1052903750795)]}</ID>

    <PropertyName type="String">Alarms</PropertyName>

    <NewIMO type="IAlarmList">

      <ID type="Oid">{[ManagedElement(Key=RB1800Sim)] 
        [AlarmList]}</ID>

      <Alarms type="IMObjects_Array">

        <ICompiledAlarm>

          <ID type="Oid">{[CompiledAlarm(Id=7)]}</ID>

        </ICompiledAlarm>

      </Alarms>

    </NewIMO>

  </ IAddNotification >

</IMObjects_Array>

This example shows that a CompiledAlarm with ID 7 was added to the Alarms table.

IAddNotification has three elements:

Oid	OID of the notification. Identifies the sequence number and the time of the notification.
NewIMO	The added IMO.
PropertyName	The table whose element was added. In this example, the Alarms table changed. The change is the addition of a compiled alarm.

IRemoveNotification

IRemoveNotification is sent by a containing object to indicate that one of its internal IMO objects was deleted. For example:

commandId=alarms1

<?xml version="1.0" encoding="UTF-8"?>

<IMObjects_Array>

  <IRemoveNotification>

    <ID type="Oid">{[Notification(SequenceNumber=253) 
       (Time=1052903750795)]}</ID>

    <PropertyName type="String">Alarms</PropertyName>

    <NewIMO type="IAlarmList">

      <ID type="Oid">{[ManagedElement(Key=RB1800Sim)] 
        [AlarmList]}</ID>

      <Alarms type="IMObjects_Array">

        <ICompiledAlarm>

          <ID type="Oid">{[CompiledAlarm(Id=7)]}</ID>

        </ICompiledAlarm>

      </Alarms>

    </NewIMO>

  </IRemoveNotification>

</IMObjects_Array>

The OID of the removed element is always given under the NewIMO key.

IRemoveNotification has three elements:

Oid	OID of the notification. Identifies the sequence number and the time of the notification.
NewIMO	The removed IMO.
PropertyName	The containing object whose element was deleted. In this example, the Alarms table changed. The change is the removal of a compiled alarm.

IObjectDeleteNotification

IObjectDeleteNotification is sent by an object when it is deleted. For example:

<?xml version="1.0" encoding="UTF-8"?>

<IMObjects_Array>

<IObjectDeleteNotification>

   <ID type="Oid">{[Notification(SequenceNumber=1201) 
      (Time=1052837316305)]}</ID>

   <Oid type="Oid">{[ManagedElement(Key=RB1)][LogicalRoot] 
      [Context(ContextName=cyber.net)]}</Oid>

</IObjectDeleteNotification>

</IMObjects_Array>

This example illustrates the notification that occurs when a context is deleted from an NE named RB1. IObjectDeletedNotification reports the OID of the deleted element.

Note the difference between IRemoveNotification and IObjectDeletedNotification. IRemoveNotification is generated for a containing object when one of its elements is removed. For example, when registering on a Virtual Circuit (VC), notification is sent whenever a VC is removed. However, when registering on a specific VC, an IObjectDeletedNotification notification is sent only when the VC is removed.