Cisco Active Network Abstraction Customization User Guide, 3.6.4
BQL Generic Commands
Download this chapter
BQL Generic CommandsBQL Generic Commands
Download the complete book
PDF of Cisco Active Network Abstraction Customization User Guide, 3.6.4PDF of Cisco Active Network Abstraction Customization User Guide, 3.6.4 (PDF - 4 MB)
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 Command

Description

Syntax

Output

Example

Refresh Command

Description

Example

BQL Error Handling

Example 1

Example 2

Example 3

Example 4


BQL Generic Commands

This chapter describes BQL generic commands and old and new error message formats. Topics include:

•Introduction

•Get Command

•Update Command

•Create Command

•Delete Command

•Find Command

•Refresh Command

•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.

This section describes each of these generic commands. There are other specialized commands that perform operations that cannot be mapped into one of these basic commands, such as Activation commands. These specialized commands are beyond the scope of this document.

Because Cisco ANA is based on network autodiscovery, Update, Create, and Delete commands might be invalid for some IMO objects. Moreover, not all IMO objects support all 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 IMO OIDs, page 21-1

RETREIVAL_SPEC

Retrieval specification format as explained in Format and Syntax of a Retrieval Specification, page 21-14


Output

The output is IMO data in XML format. If the Get command registers for changes, the output terminates with \n$\n. Otherwise, the output of the command ends 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, page 21-1 section

NOTIFICATION_ARRAY:

NOTIFICATION_IMO |

NOTIFICATION_IMO NOTIFICATION_ARRAY

NOTIFICATION_OBJECT:

IMO object of type IScalarNotification, IAddNotification, or IRemoveNotification as described in Notifications, page 21-19


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, page 21-1 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 Command

Description

The Find command retrieves a list of data entities (IMO objects) according to a search qualifier. The command includes a retrieval specification and an IMO object that serves as a search qualifier.

The Find section specifies a list of IMO objects and their respective qualifier values. For example, if the RS is for port information, a qualifier value can be specified for the port OperStatus, so that the reply contains 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 Format and Syntax of a Retrieval Specification, page 21-14. Defines what is returned from the objects that match the search criteria.


Output

The function returns 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 specification. The output is IMObject_Array where each element in the array is the IMO that matches the retrieval specification.

For example, to find subscribers named "John Smith":

•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 is: 

<?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 Command

Description

The IMO model polls its data from the VNE model; the VNE model polls 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 when 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 error messages formats 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 XML format.

ISystemError contains an identifier field that has an 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 in the following sections display the same error messages in the old and new format.

Example 1

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>

Example 2

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>

Example 3

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>

Example 4

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 message format is supported for backward compatibility. The default system error message 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 message format.

Note Changes to the registry should be performed only with the support of Cisco. For details, please contact the Cisco Project Manager or Cisco Account Team.

You can switch between two modes during each BQL session:

1. Enter xmlerrorreporting off

The server response is "XML Error Reporting was set to OFF". This enables the old nonXML error message format.

2. Enter xmlerrorreporting on

The server response is "XML Error Reporting was set to ON". This enables the new XML error message format.

To check the current XML error message format, enter xmlerrorreporting. The server response is either "XML Error Reporting is : ON" or "XML Error Reporting is : OFF".