Table Of Contents
BQL Generic Commands
Introduction
BQL defines five generic commands, which are supported by most IMO objects. These commands are:
•
Get—Retrieve an information for a specific object
•
•
•
•
In this section we describe each of these generic commands. There are other specialized commands that allow performing operations that cannot be mapped into one of these basic commands, e.g. Activation commands. These specialized commands are beyond the scope of this manual.
Since Cisco ANA is based on network auto-discovery, the Update, Create and Delete commands may be invalid for some IMO objects. Moreover, not all IMO objects support all the generic commands. The supported commands for each IMO are described in the IMO reference manual.
GET Command
Description
The GET command retrieves an IMO construct (related IMO objects) based on a specified retrieval specification (RS). It also enables registering for notifications on changes in the specified IMO objects.
Syntax
GET_COMMAND:
<command name="Get">
<param name="oid">
<value> OID </value>
</param>
<param name="rs">
<value>
RETRIEVAL_SPEC
</value>
</param>
</command>
OID:
OID format as explained in the IMO OIDs section
RETREIVAL_SPEC:
Retrieval spec format as explained in the Format/Syntax Retrieval Specification section
Output
The output is IMO data in XML format. If the GET command registers for changes then the output would terminate with \n$\n. Otherwise, the output of the command will end with the standard EOT sequence \n.\n.
Example
<command name="Get"><param name="oid"><value>{[ManagedElement(Key=ASAMSim)]}</value></param><param name="rs"><value><key name=""><entry name="register">false</entry><key name="requiredProperties"><key name="com.sheer.imo.IManagedElement"><entry name="*"/></key></key></key></value></param></command>UPDATE Command
Description
The UPDATE command modifies an existing IMO object.
The command receives an OID of an object to modify and an array of notifications. The notifications are of type scalar notification, add notification and remove notification. These notifications describe how to modify the IMO object, i.e., what properties to change, add or remove.
Syntax
UPDATE_COMMAND:
<command name="Update">
<param name="oid">
<value> OID </value>
</param>
<param name="imoobjectArr">
<value>
NOTIFICATION_ARRAY
</value>
</param>
</command>
OID:
OID format as explained in the IMO OIDs section
NOTIFICATION_ARRAY:
NOTIFICATION_IMO |
NOTIFICATION_IMO NOTIFICATION_ARRAY
NOTIFICATION_OBJECT:
IMO object of type IScalarNotification, IAddNotification or IRemoveNotification as described in the Notifications section
Output
None
Example
<?xml version="1.0" encoding="UTF-8"?><command name="Update"><param name="oid"><value>{[ManagedElement(Key=ACESim)][BusinessObject]}</value></param><param name="imobjectArr"><value><IScalarNotification><ID type="Oid">{[Notification]}</ID><PropertyName type="String">EKey</PropertyName><NewIMO type="IBusinessObject"><ID type="Oid">{[ManagedElement(Key=ACESim)] [BusinessObject]}</ID><EKey type="String">key2</EKey><Name type="String">name2</Name></NewIMO></IScalarNotification></value><value><IScalarNotification><ID type="Oid">{[Notification]}</ID><PropertyName type="String">Name</PropertyName><NewIMO type="IBusinessObject"><ID type="Oid">{[ManagedElement(Key=ACESim)] [BusinessObject]}</ID><EKey type="String">key2</EKey><Name type="String">name2</Name></NewIMO></IScalarNotification></value></param></command>CREATE Command
Description
The create command creates a new data object in the system. The command receives as a parameter the data of the new IMO object.
Syntax
CREATE_COMMAND:
<command name="Create">
<param name="imobject">
<value>
IMO_DATA
</value>
</param>
</command>
IMO_DATA:
IMO object representation
Output
None
Example
<?xml version="1.0" encoding="UTF-8"?><command name="Create"><param name="imobject"><value><IBusinessObject><ID type="Oid">{[ManagedElement(Key=ACESim)] [BusinessObject]}</ID><EKey type="String">key1</EKey><Name type="String">name1</Name><Notes type="String" /><TypeEnum type="Integer">0</TypeEnum></IBusinessObject></value></param></command>DELETE Command
Description
The Delete command deletes existing IMO object. The deleted element is identified by its OID. Note that not all data elements in the system can be deleted.
Syntax
DELETE_COMMAND:
<command name="Delete">
<param name="oid">
<value> OID </value>
</param>
</command>
OID:
OID format as explained in the IMO OIDs section
Output
None
Example
<?xml version="1.0" encoding="UTF-8"?><command name="Delete"><param name="oid"><value>{[ManagedElement(Key=ACESim)][BusinessObject]} </value></param></command>Find
Description
The "Find" command retrieves a list of data entities (IMO objects) according to a search qualifier. The command includes a Retrieval Spec and an IMO object which serves as a search qualifier.
The Find section specifies a list of IMO objects and their respective qualifier values. For example, if our RS is for port information, we can specify a qualifier value for the port OperStatus, and the reply will only contain those ports that have this status.
Syntax
FIND_COMMAND:
<command name="Find">
<param name="imo">
<value> IMO </value>
</param>
<param name="rs">
<value>
RETRIEVAL_SPEC
</value>
</param>
</command>
IMO:
This IMO object defines the search qualifier. The search qualifier object includes one or more properties with specified values.
RETRIEVAL_SPEC:
Retrieval spec format as explained in the Format/Syntax Retrieval Specification section. Defines what is returned from the objects that match the search criteria.
Output
The function returns the IMO objects (of the same type as the search qualifier) whose properties match the properties of the search qualifier. For each such object it returns its part that matches the retrieval spec. The output is IMObject_Array where each element in the array is the IMO that matches the retrieval spec.
For example, to find subscribers named "John Smith", we should:
Specify as search qualifier a Business Attachment IMO object, in which name = "John Smith" and typeEnum = 1 (subscriber)
Provide a Retrieval Spec for Business Attachment object types.
Example
<command name="Find"><param name="imo"><value><IBusinessObject><Name type="String">John Smith</Name><TypeEnum type="Integer">1</TypeEnum></IBusinessObject></value></param><param name="rs"><value><key name="find-business-object"><entry name="register">false</entry><key name="requiredProperties"><key name= "com.sheer.imo.IBusinessObject"><entry name="*"/></key></key></key></value></param></command>The output of this query will be:
<?xml version="1.0" encoding="UTF-8"?><IMObjects_Array><IBusinessObject><ID type="Oid">{[ManagedElement(Key=ACESim)] [BusinessObject]}</ID><EKey type="String">key2</EKey><Name type="String">name2</Name><Notes type="String"/><TypeEnum type="Integer">0</TypeEnum></IBusinessObject></IMObjects_Array>Refresh
Description
The IMO model polls its data from the VNE model, the VNE model is polling its data from the devices. When a "Get" command is executed, a set of IMOs is retrieved. Sometimes the data is not updated to the current device state as it was polled from the VNE model. When the most recent data is needed, use the Refresh command to request the VNE to "retrieve now" the data from the device before polling its model.
Example
<command name="Refresh"><param name="oid"><value>{[ManagedElement(Key=C_1)]}</value></param><param name="oids"><value>{[ManagedElement(Key=C_1)][PhysicalRoot][Chassis] [Slot(SlotNum=0)][Module] [Port(PortNumber=FastEthernet0/0)]}</value><value>{[ManagedElement(Key=C_1)][PhysicalRoot][Chassis] [Slot(SlotNum=0)][Module] [Port(PortNumber=FastEthernet0/0)] [PhysicalLayer]}</value><value>{[ManagedElement(Key=C_1)][PhysicalRoot][Chassis][Slot(SlotNum=0)][Module][Port(PortNumber=FastEthernet0/0)] [PhysicalLayer][DataLinkLayer]}</value><value>{[ManagedElement(Key=C_1)][PhysicalRoot][Chassis] [Slot(SlotNum=0)][Module] [Port(PortNumber=FastEthernet0/0)] PhysicalLayer][DataLinkLayer][VlanEncapMux]}</value></param></command>