Cisco Active Network Abstraction BQL User Guide Version 3.5.2
BQL Generic Commands
Download this chapter
BQL Generic CommandsBQL Generic Commands
give_us_feedback

Table Of Contents

BQL Generic Commands

Introduction

GET Command

Description

Syntax

Output

Example

UPDATE Command

Description

Syntax

Output

Example

CREATE Command

Description

Syntax

Output

Example

DELETE Command

Description

Syntax

Output

Example

Find

Description

Syntax

Output

Example

Refresh

Description

Example

BQL Error Handling


BQL Generic Commands

This chapter describes the BQL generic commands and the new error messages format, see BQL Error Handling.

Introduction

BQL defines five generic commands, which are supported by most IMO objects. These commands are:

•Get—Retrieve information for a specific object

•Update—Set properties and relations for an existing object

•Create—Create a new IMO object

•Delete—Delete an existing IMO object

•Find—Retrieve information for several objects according to search criteria

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, for example, Activation commands. These specialized commands are beyond the scope of this guide.

Because 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 guide.

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, that is, which 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. 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 contain only 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 that it returns, its part 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>

BQL Error Handling

This section describes the new error messages format and provides several examples of the old and new format. Previously error messages were presented in a plain string format. The new format presents the error messages as ISystemError IMO in an xml format.

ISystemError contains an identifier field that has the error code, a string description field, and a string array field named ErrorStackTrace containing an exception stack trace, if present, as shown in the example below: 

<ISystemError>

<ID type="Oid">{[SystemError(Code=ERROR CODE GOES HERE)]}</ID>

<Description type="String">DESCRIPTION OF THE ERROR</Description>

<ErrorStackTrace type="java.lang.String_Array">

<java.lang.String>StackEntry 1</java.lang.String>

<java.lang.String>StackEntry 2</java.lang.String> 

...

<java.lang.String>StackEntry N</java.lang.String>

</ErrorStackTrace>

</ISystemError>

The examples provided below display the same error messages in the old and new format.

Old Format 

Exception Message: 13Source: 13(MM.SA-127.0.0.1 [6346738]-0:0:0:0:0:0:0:27 
[64]13Destination: (CL.TS-127.0.0.1 [2]-0:0:0:0:0:0:0:5 [64]13Exception: 
java.lang.IllegalArgumentException: Template Simple.template not found 
at 
com.sheer.system.os.services.workflow.dwe.InternalWorkflowUtil.getTemplateIdByName(Interna
lWorkflowUtil.java:80) 
at 
com.sheer.system.os.services.workflow.dwe.InternalWorkflowUtil.getTemplateIdByName(Interna
lWorkflowUtil.java:42) 
at 
com.sheer.system.os.services.workflow.WorkflowServiceImpl.runWorkflow(WorkflowServiceImpl.
java:373) 
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) 
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) 
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) 
at java.lang.reflect.Method.invoke(Method.java:324) 
at com.sheer.system.os.services.base.BaseOSService.invoke(BaseOSService.java:57) 
at 
com.sheer.system.os.services.management.ServiceWrapper.executeCommand(ServiceWrapper.java:
202) 
at 
com.sheer.system.os.services.management.ManagementService.execute(ManagementService.java:2
08) 
at 
com.sheer.system.os.services.management.adapters.rtc.RemoteTransportConnectorAgent.execute
Local(RemoteTransportConnectorAgent.java:157) 
at 
com.sheer.system.os.services.management.adapters.rtc.RemoteTransportConnectorAgent.handleE
xecuteMessage(RemoteTransportConnectorAgent.java:102) 
at 
com.sheer.system.os.services.management.adapters.rtc.RemoteTransportConnectorAgent.process
Message(RemoteTransportConnectorAgent.java:66) 
at com.sheer.system.agentshell.AgentBase.run(AgentBase.java:232) 
at com.sheer.system.os.services.scheduler.OSAgent.run(OSAgent.java:107) 
at com.sheer.system.os.util.ThreadPool$OSThread.run(ThreadPool.java:272)

New Format 

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

<ISystemError>

<ID type="Oid">{[SystemError(Code=1000)]}</ID>

<Description type="String">ERROR (1000): General error, Exception: 
java.lang.IllegalArgumentException: Template Simple.template not found</Description>

<ErrorStackTrace type="java.lang.String_Array">


<java.lang.String>com.sheer.system.os.services.workflow.dwe.InternalWorkflowUtil.getTempla
teIdByName(InternalWorkflowUtil.java:80)</java.lang.String>


<java.lang.String>com.sheer.system.os.services.workflow.dwe.InternalWorkflowUtil.getTempla
teIdByName(InternalWorkflowUtil.java:42)</java.lang.String>

<java.lang.String>com.sheer.system.os.services.workflow.WorkflowServiceImpl.runWorkflo
w(WorkflowServiceImpl.java:373)</java.lang.String>

<java.lang.String>sun.reflect.NativeMethodAccessorImpl.invoke0(Native 
Method)</java.lang.String>

<java.lang.String>sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl
.java:39)

</java.lang.String>

<java.lang.String>sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAcce
ssorImpl.java:25)</java.lang.String>

<java.lang.String>java.lang.reflect.Method.invoke(Method.java:324)</java.lang.String>

<java.lang.String>com.sheer.system.os.services.base.BaseOSService.invoke(BaseOSService
.java:57)>

</java.lang.String>

<java.lang.String>com.sheer.system.os.services.management.ServiceWrapper.executeComman
d(ServiceWrapper.java:202)</java.lang.String>

<java.lang.String>com.sheer.system.os.services.management.ManagementService.execute(Ma
nagementService.java:208)</java.lang.String>


<java.lang.String>com.sheer.system.os.services.management.adapters.rtc.RemoteTransportConn
ectorAgent.executeLocal(RemoteTransportConnectorAgent.java:157)</java.lang.String>


<java.lang.String>com.sheer.system.os.services.management.adapters.rtc.RemoteTransportConn
ectorAgent.handleExecuteMessage(RemoteTransportConnectorAgent.java:102)</java.lang.String>


<java.lang.String>com.sheer.system.os.services.management.adapters.rtc.RemoteTransportConn
ectorAgent.processMessage(RemoteTransportConnectorAgent.java:66)</java.lang.String>

<java.lang.String>com.sheer.system.agentshell.AgentBase.run(AgentBase.java:232)</java.
lang.String>

<java.lang.String>com.sheer.system.os.services.scheduler.OSAgent.run(OSAgent.java:107)
>

</java.lang.String>

<java.lang.String>com.sheer.system.os.util.ThreadPool$OSThread.run(ThreadPool.java:272
)>

</java.lang.String>

</ErrorStackTrace>

</ISystemError>

Old Format 

Invalid Command Syntax. 
java.lang.IllegalArgumentException: Invalid command syntax. no such command

New Format 

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

<ISystemError>

<ID type="Oid">{[SystemError(Code=1200)]}</ID>

<Description type="String">Invalid Command Syntax.

java.lang.IllegalArgumentException: Invalid command syntax. no such command</Description>

</ISystemError>

Old Format 

Error parsing XML.

org.jdom.input.JDOMParseException: Error on line 1: The element type "dfgA" must be 
terminated by the matching end-tag "</dfgA>".

New Format 

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

<ISystemError>

<ID type="Oid">{[SystemError(Code=1200)]}</ID>

<Description type="String">Error parsing XML.

org.jdom.input.JDOMParseException: Error on line 1: The element type "asdf" must be 
terminated by the matching end-tag "&lt;/asdf&gt;".</Description>

</ISystemError>

Old Format 

Error executing command

java.lang.Exception: ShellRaw: null cid returned (Unknown command)

New Format 

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

<ISystemError>

<ID type="Oid">{[SystemError(Code=1202)]}</ID>

<Description type="String">Error executing command

java.lang.Exception: ShellRaw: null cid returned (Unknown command)</Description>

</ISystemError>

The old error messages format is supported for backward compatability. The default system error messages format is configurable in the registry in mmvm/agents/adapters/ShellRawServer/XMLErrorReporting. By default the value is "true", meaning that the BQL reports errors in the new XML error messages format.

Note Changes to the registry should only be carried out with the support of Cisco Professional Services.

The user can switch between two modes during each BQL session:

1. Typing: xmlerrorreporting off

The server response is "XML Error Reporting was set to OFF" and this enables the old non-xml error messages format.

2. Typing: xmlerrorreporting on

The server response is "XML Error Reporting was set to ON" and this enables the new xml error messages format.

To check the current xml error messages format:

•Type: xmlerrorreporting

The server response is either "XML Error Reporting is : ON" or "XML Error Reporting is : OFF".