Cisco Active Network Abstraction Customization User Guide, 3.6.6
BQL Generic Commands
Download this chapter
BQL Generic CommandsBQL Generic Commands
Download the complete book
PDF of Cisco ANA 3.6.6 Customization User GuidePDF of Cisco ANA 3.6.6 Customization User Guide (PDF - 4 MB)
give_us_feedback

Table Of Contents

BQL Generic Commands

Overview

Get Command

Description

Syntax

Output

Example

Update Command

Description

Syntax

Output

Example

Create Command

Description

Syntax

Output

Examples

Creating a Business Object

Creating an AVM

Creating a VNE

Delete Command

Description

Syntax

Output

Example

Find Command

Description

Syntax

Output

Example

Refresh Command

Description

Output

Example

BQL Error Handling

BQL Error Example 1

BQL Error Example 2

BQL Error Example 3

BQL Error Example 4


BQL Generic Commands

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

•Overview

•Get Command

•Update Command

•Create Command

•Delete Command

•Find Command

•Refresh Command

•BQL Error Handling

Overview

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 Cisco Active Network Abstraction 3.6.6 Technology Support and Information Model Reference Manual.

Get Command

Description

The Get command retrieves an IMO construct (related IMO objects) based on a specified RS. It also enables registering for notifications on changes in the specified IMO objects.

Syntax

Table 26-1 BQL Get Command Syntax 

Element
Details

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 25-1

RETREIVAL_SPEC

RS format as explained in Format and Syntax of a Retrieval Specification, page 25-14


Output

The output consists of 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

Table 26-2 BQL Update Command Syntax 

Element
Details

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 IMO OIDs, page 25-1.

NOTIFICATION_ARRAY:

NOTIFICATION_IMO |

NOTIFICATION_IMO NOTIFICATION_ARRAY

NOTIFICATION_OBJECT:

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


Output

A dot (.) indicates success. In the event of a failure, an error message is displayed.

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

Table 26-3 BQL Create Command Syntax 

Element
Details

CREATE_COMMAND:

<command name="Create">

<param name="imobject">

<value>

IMO_DATA

</value>

</param>

</command>

IMO_DATA:

IMO object representation


Output

A dot (.) indicates success. In the event of a failure, an error message is displayed.

Examples

Creating a Business Object 

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

A dot (.) indicates success. In the event of a failure, an error message is displayed.

Creating an AVM 

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

<command name="Create">

   <param name="imobject">

      <value>

         <management.IAvm>

            <ID type="Oid">{[MCNetwork][MCVM(IP=172.20.68.122)][Avm(AvmNumber=555)]}</ID>

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

            <AvmKey type="com.sheer.types.Key">AVM555</AvmKey>

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

            <MaximumMemory type="Integer">256</MaximumMemory>

         </management.IAvm>

      </value>

   </param>

</command>

A dot (.) indicates success. In the event of a failure, an error message is displayed.

Table 26-4 Creating an AVM Syntax 

Field
Description

ID

IP address of the unit, combined with the AVM number, using the following format:

{[MCNetwork][MCVM(IP=ip-addr)][Avm(AvmNumber=AVM-number)]}

AdminStatusEnum

Administrative status of the AVM:

•1—Administrative status is activated upon creation.

•0—Administrative status is not activated upon creation.

AvmKey

Unique identifier of the AVM.

HighAvailabilityEnabled

Protection status of the AVM:

•True—AVM protection is enabled.

•False—AVM protection is disabled.

MaximumMemory

The maximum amount of memory allocated to the AVM.


Creating a VNE

The command to create a VNE includes seven sections. The following topics describe and provide examples for each of these sections. The last topic shows a complete command for creating a VNE:

•Header

•General

•SNMP

•Telnet

•ICMP

•Polling

•Footer

•VNE Example

Header

The command header opens the command and sets the initial parameters. When creating a VNE using the Create command, you must enter the header exactly as follows: 

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

<command name="Create">

   <param name="imobject">

      <value>

         <management.IElementManagement>

General

The general section of the command contains specific information regarding the VNE and uses the following format: 

            <ID type="Oid">

               {[MCNetwork][MCVM(IP=unit-ip)][Avm(AvmNumber=AVM-number)] 

               [ElementManagement(Key=NewVNEName)]}

            </ID>

            <ElementName type="String">NewVNEName</ElementName>

            <IP type="com.sheer.types.IPAddress">AVM-ip-addr</IP>

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

            <SchemeName type="String">ipcore</SchemeName>

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

Table 26-5 Creating a VNE - General Section Syntax 

Field
Description
Validation Rule

ID

IP address of the unit, AVM number, and name for the new VNE, in the following format:

{[MCNetwork][MCVM(IP=unit-ip)][Avm(AvmNumber=AVM-number)] [ElementManagement(Key=NewVNEName)]}

Mandatory.

ElementName

Name of the new VNE.

Text. Mandatory.

IP

IP address of the AVM.

IP address. Mandatory.

ElementClassEnum

The VNE type:

•0—Autodetects the device type.

•1—Loads a generic VNE.

•2—Loads an unmanaged network segment (cloud).

•3—Uses an ICMP-based reachability test to validate communication with the device.

Integer. Mandatory.

SchemeName

The scheme to use for the VNE:

•product—Uses the product scheme (default).

•ipcore—Uses the ipcore scheme.

Omit this field to use the default value (product).

Text.

AdminStatusEnum

The initial state of the VNE:

•0—The VNE is not loaded.

•1—The VNE is loaded and starts collecting data.

Integer. Mandatory.

MaintenanceEnabled

Indicates whether the VNE should be in maintenance mode upon creation:

•True—The VNE is placed in maintenance mode.

•False—The VNE is not placed in maintenance mode. This is the default value.

If this field is omitted, the default value (false) is used.

Text.


SNMP

The SNMP section of the command enables you to configure the VNE for SNMPv1, SNMPv2, or SNMPv3. The SNMP section uses the following format: 

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

            <SNMPReadCommunity type="String">public</SNMPReadCommunity>

            <SNMPWriteCommunity type="String">private</SNMPWriteCommunity>

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

            <SnmpV3AuthenticationPassword type="String" />

            <SnmpV3AuthenticationUserProfile type="String" />

            <SnmpV3EncryptionPassword type="String" />

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

Table 26-6 Creating a VNE - SNMP Section Syntax 

Field
Description
Validation Rule

SNMPEnabled

Indicates whether SNMP is to be enabled for the new VNE:

•True—SNMP is enabled on the VNE.

•False—SNMP is disabled on the VNE.

If the value is false, you do not need to configure any of the remaining SNMP fields.

Text.

SNMPVersionEnum

The version of SNMP to use for the VNE:

•0—SNMPv1

•1—SNMPv2

•2—SNMPv3

Integer.

SNMPReadCommunity

The SNMP read community string.

Text.

Required if the value for SNMPVersionEnum is 0 or 1.

SNMPWriteCommunity

The SNMP write community string.

Text.

Required if the value for SNMPVersionEnum is 0 or 1.

SnmpV3AuthenticationEnum

The authentication method for SNMPv3:

•0—No authentication is required.

•1—MD5 or SHA without encryption.

•2—MD5 or SHA with encryption.

Integer.

Required if the value for SNMPVersionEnum is 2.

SnmpV3AuthenticationProtocolEnum

The authentication protocol to use:

•0—MD5

•1—SHA

Integer.

Required if the following are true:

•SNMPVersionEnum is 2.

•SnmpV3AuthenticationEnum is 1 or 2.

SnmpV3AuthenticationUserProfile

The authentication user for SNMPv3.

Text.

Required if the following are true:

•SNMPVersionEnum is 2.

•SnmpV3AuthenticationEnum is 1 or 2.

SnmpV3AuthenticationPassword

The authentication password for SNMPv3.

Text.

Required if the following are true:

•SNMPVersionEnum is 2.

•SnmpV3AuthenticationEnum is 1 or 2.

SnmpV3EncryptionTypeEnum

The type of encryption to be used:

0—DES

1—AES-128

2—AES-192

3—AES-256

Integer.

Required if the following are true:

•SNMPVersionEnum is 2.

•SnmpV3AuthenticationEnum is 1 or 2.

SnmpV3EncryptionPassword

The encryption password to be used.

Text.

Required if the following are true:

•SNMPVersionEnum is 2.

•SnmpV3AuthenticationEnum is 1 or 2.


Telnet

The Telnet section of the command enables you to define Telnet or SSH attributes for the new VNE. The Telnet section of the command uses the following format: 

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

            <TelnetPortNumber type="Integer">23</TelnetPortNumber>

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

            <TelnetSequence type="">Null</TelnetSequence>

Table 26-7 Creating a VNE - Telnet Section Syntax 

Field
Description
Validation Rule

TelnetEnabled

Indicates whether Telnet is to be enabled for the VNE:

•True—Telnet is enabled for the new VNE.

•False—Telnet is disabled for the new VNE.

If the value is false, you do not need to configure any of the remaining Telnet fields.

Text.

TelnetPortNumber

Telnet port number, usually 23 for Telnet and 22 for SSH.

Integer.

TelnetProtocolEnum

Telnet protocol to be used:

•0—Telnet

•1—SSHv1

•2—SSHv2

Integer.

TelnetSequence

The Telnet login sequence.

Entries must be separated by commas and end with a comma. To indicate a right angle bracket ( > ), enter &gt.

See Telnet Login Sequence for an example entry and more information.

Text.

SshUsername

The SSH username.

This field is required if the value for TelnetProtocolEnum is 1 or 2.

Text.

SshPassword

The SSH password.

Text.

Required if one of the following statements is true:

•TelnetProtocolEnum is 1.

•TelnetProtocolEnum is 2 and ClientAuthEnum is 0.

SshCipherEnum

The SSH cipher option to be used:

•0—DES

•1—3DES

•2—Blowfish

Integer.

Required if TelnetProtocolEnum is 1.

SshAuthenticationEnum

Authentication type for SSHv1.

A value of 0 (zero) indicates password authentication. The value 0 is the only supported option.

Integer.

Required if TelnetProtocolEnum is 1.

ClientAuthEnum

Type of client authentication for SSHv2:

•0—Password

•1—Public key

Integer.

Required if TelnetProtocolEnum is 1.

ClientPrivateKey

The client private key for SSHv2.

An example of a client private key entry is: 

<ClientPrivateKey 
type="String">-----BEGIN RSA PRIVATE 
KEY-----MIIByQIBAAJhAKJ2lzDLZ8XlVamb
QfMXn3LRGKOD5o6lMIgulclWjZwP56LRqdg5
ZX15bhc/GsvW8xW/R5Sh1NnkJNyL/cqY1a+G
zzL47t7EXzVc+nRLWT1kwTvFNGIoAUsFUq+J
6+OprwIDAQABAmBOX0UaLdWWusYzNol++nNZ
0RLAtr1/LKMX3tk1MkLH+Ug13EzB2RZjjDOW
lUOY98yxW9/hX05Uc9V5MPo+q2Lzg8wBtyRL
qlORd7pfxYCnKapi2RPMcR1CxEJdXOkLCFEC
MQDTO0fzuShRvL8q0m5sitIHlLA/L+0+r9Ka
SRM/3WQrmUpV+fAC3C31XGjhHv2EuAkCMQDE
5U2nP2ZWVlSbxOKBqX724amoL7rrkUewti9T
EjfaBndGKF2yYF7/+g53ZowRkfcCME/xOJr5
8VN17pejSl1T8Icj88wGNHCsFDWGAH4EKNwD
SMnfLMG4WMBqd9rzYpkvGQIwLhAHDq2CX4hq
2tZAt1zT2yYH7tTbweiHAQxeHe0RK+x/UuZ2
pRhuoSv63mwbMLEZAjAP2vy6Yn+f9SKw2mKu
j1zLjEhG6ppw+nKD50ncnPoP322UMxVNG4Ea
h0GYJ4DLP0U=-----END RSA PRIVATE 
KEY-----</ClientPrivateKey>

Text.

Required if both of the following statements are true:

•TelnetProtocolEnum is 2.

•ClientAuthEnum is 1.

ClientPublicKey

The client public key for SSHv2.

An example of a client public key entry is: 

<ClientPublicKey 
type="String">ssh-rsa 
AAAAB3NzaC1yc2EAAAADAQABAAAAYQCidpcw
y2fF5VWpm0HzF59y0Rijg+aOpTCILpXJVo2c
D+ei0anYOWV9eW4XPxrL1vMVv0eUodTZ5CTc
i/3KmNWvhs8y+O7exF81XPp0S1k9ZME7xTRi
KAFLBVKvievjqa8= generated by CMP 
from privateKey</ClientPublicKey>

Text.

Required if both of the following statements are true:

•TelnetProtocolEnum is 2.

•ClientAuthEnum is 1.

ServerAuthEnum

The server authentication type for SSHv2:

•0—None

•1—save-first-auth

Upon the first connection with the server, the connection is established and the public key is saved.

•2—preconfigured

The server public key or fingerprint is configured in the application event before the first connection is attempted.

Integer.

Required if TelnetProtocolEnum is 2.

ServerAuthDataTypeEnum

For preconfigured SSHv2 authentication, the kind of preconfigured authentication:

•0—Fingerprint

•1—Public key

Integer.

Required if both of the following statements are true:

•TelnetProtocolEnum is 2.

•ServerAuthEnum is 2.

FingerPrint

The fingerprint string for preconfigured server authentication.

Text.

Required if all of the following statements are true:

•TelnetProtocolEnum is 2.

•ServerAuthEnum is 2.

•ServerAuthDataTypeEnum is 0.

ServerPublicKey

The server public key for preconfigured SSHv2 authentication.

An example of a server public key entry is: 

<ServerPublicKey 
type="String">ssh-rsa 
AAAAB3NzaC1yc2EAAAADAQABAAAAYQCidpcw
y2fF5VWpm0HzF59y0Rijg+aOpTCILpXJVo2c
D+ei0anYOWV9eW4XPxrL1vMVv0eUodTZ5CTc
i/3KmNWvhs8y+O7exF81XPp0S1k9ZME7xTRi
KAFLBVKvievjqa8= 
OK</ServerPublicKey>

Text.

Required if all of the following statements are true:

•TelnetProtocolEnum is 2.

•ServerAuthEnum is 2.

•ServerAuthDataTypeEnum is 1.

KeyExchange

The key exchange algorithm types, entered as comma-separated values:

•diffie-hellman-group1-sha1

•diffie-hellman-group1-exchange-sha1

Text.

Required if TelnetProtocolEnum is 2.

MAC

MAC algorithms, entered as comma-separated values:

•SHA1

•MD5

•SHA1-96

•MD5-96

Text.

Required if TelnetProtocolEnum is 2.

Cipher

Cipher algorithms, entered as comma-separated values:

•3DES

•AES-128

•AES-192

•AES-256

Text.

Required if TelnetProtocolEnum is 2.

HostKeyAlgo

Host key algorithm:

•DSA

•RSA

Text.

Required if TelnetProtocolEnum is 2.


Telnet Login Sequence

The following is an example of an entry for a Telnet login sequence: 

<TelnetSequence 
type="String">P:,[mask]loginPassword,R&gt;,enable,P:,[mask]enablePassword,R#,</TelnetSeque
nce>

where:

•loginPassword is the initial password.

•enablePassword is the enable password.

•&gt produces > (right angle bracket).

Figure 26-8 shows the resulting login sequence as it appears in ANA Manage.

Figure 26-8 Telnet Login Sequence

ICMP

The ICMP section of the command enables you to configure ICMP polling to ensure that the device is reachable.

The ICMP section uses the following format: 

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

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

Table 26-9 Creating a VNE - ICMP Section Syntax

Field
Description
Validation Rule

ICMPEnabled

Enables or disables ICMP:

•True—ICMP is enabled.

•False—ICMP is disabled.

Text.

ICMPPollingRate

ICMP polling rate in milliseconds.

If the value for ICMPEnabled is false, enter 0 (zero).

Integer. Mandatory.


Polling

The polling section of the command enables you to associate the new VNE with a previously created polling group and to customize polling intervals. The polling group is inside the field <PollingGroup type="management.IPollingGroupManagement"> and can use either of the following two formats:

•Default Polling Group

•Nondefault Polling Group

Default Polling Group

The default polling group uses the following format: 

<PollingGroup type="management.IPollingGroupManagement">

   <ID type="Oid">

         {[MCNetwork][MCVM(IP=unit-ip)][Avm(AvmNumber=AVM-number)]

         [ElementManagement(Key=NewVNEName)]

         [PollingGroupManagement(Name=default)]}

   </ID>

</PollingGroup>

Table 26-10 Creating a VNE - Default Polling Group Syntax 

Field
Description
Validation Rule

ID

OID of the unit, AVM number, and VNE name in the following format:

{[MCNetwork][MCVM(IP=unit-ip)][Avm(AvmNumber=AVM-number)] [ElementManagement(Key=NewVNEName)]
[PollingGroupManagement(Name=default)]}

Mandatory.


Nondefault Polling Group

A nondefault polling group contains the following sections:

•An initial ID entry that uses the following format: 

        <ID type="Oid">{[MCNetwork]

                [MCVM(IP=unit-ip)]

                [Avm(AvmNumber=AVM-number)]

                [ElementManagement(Key=VNEName)]

                [PollingGroupManagement]}

        </ID>

For nondefault polling groups, PollingGroupManagement is not given a name.

•Five mandatory PollingInterval sections (<PollingIntervals type="IMObjects_Array">) that use the following format: 

                <management.IPollingInterval>

                        <ID type="Oid">{[MCNetwork]

                                [MCVM(IP=unit-ip)]

                                [Avm(AvmNumber=AVM-number)]

                                [ElementManagement(Key=VNEName)]

                                [PollingGroupManagement]

                                [PollingInterval(Name=FieldName)]}

                        </ID>

                        <Interval type="Long">FieldValue</Interval>

                </management.IPollingInterval>

Each PollingInterval section uses one of the following names and its related value. All field names and values are required.

Table 26-11 Creating a VNE - Polling Interval Sections 

Field Name
Value
Validation Rule

status

Status polling interval in milliseconds.

Integer. Mandatory.

configuration

Configuration polling interval in milliseconds.

Integer. Mandatory.

system

System polling interval in milliseconds.

Integer. Mandatory.

topo_l1

Topology Layer 1 interval in milliseconds.

Integer. Mandatory.

topo_l2

Topology Layer 2 interval in milliseconds.

Integer. Mandatory.


The following is an example of a nondefault polling group with an initial ID entry and the five PollingInterval entries: 

<PollingGroup type="management.IPollingGroupManagement">

        <ID type="Oid">{[MCNetwork]

                [MCVM(IP=172.20.68.122)]

                [Avm(AvmNumber=208)]

                [ElementManagement(Key=nnn)]

                [PollingGroupManagement]}

        </ID>

        <PollingIntervals type="IMObjects_Array">

                <management.IPollingInterval>

                        <ID type="Oid">{[MCNetwork]

                                [MCVM(IP=172.20.68.122)]

                                [Avm(AvmNumber=208)]

                                [ElementManagement(Key=nnn)]

                                [PollingGroupManagement]

                                [PollingInterval(Name=status)]}

                        </ID>

                        <Interval type="Long">180000</Interval>

                </management.IPollingInterval>

                <management.IPollingInterval>

                        <ID type="Oid">{[MCNetwork]

                                [MCVM(IP=172.20.68.122)]

                                [Avm(AvmNumber=208)]

                                [ElementManagement(Key=nnn)]

                                [PollingGroupManagement]

                                [PollingInterval(Name=configuration)]}

                        </ID>

                        <Interval type="Long">900000</Interval>

                </management.IPollingInterval>

                <management.IPollingInterval>

                        <ID type="Oid">{[MCNetwork]

                                [MCVM(IP=172.20.68.122)]

                                [Avm(AvmNumber=208)]

                                [ElementManagement(Key=nnn)]

                                [PollingGroupManagement]

                                [PollingInterval(Name=system)]}

                        </ID>

                        <Interval type="Long">86400000</Interval>

                </management.IPollingInterval>

                <management.IPollingInterval>

                        <ID type="Oid">{[MCNetwork]

                                [MCVM(IP=172.20.68.122)]

                                [Avm(AvmNumber=208)]

                                [ElementManagement(Key=nnn)]

                                [PollingGroupManagement]

                                [PollingInterval(Name=topo_l1)]}

                        </ID>

                        <Interval type="Long">30000</Interval>

                </management.IPollingInterval>

                <management.IPollingInterval>

                        <ID type="Oid">{[MCNetwork]

                                [MCVM(IP=172.20.68.122)]

                                [Avm(AvmNumber=208)]

                                [ElementManagement(Key=nnn)]

                                [PollingGroupManagement]

                                [PollingInterval(Name=topo_l2)]}

                        </ID>

                        <Interval type="Long">30000</Interval>

                </management.IPollingInterval>

        </PollingIntervals>

</PollingGroup>

Footer

The footer closes the command. When creating a VNE using the Create command, you must enter the footer exactly as follows: 

         </management.IElementManagement>

      </value>

   </param>

</command>

VNE Example

The following is an example of a file that can be used to create a VNE. If you use this example in your environment, you must customize the variables to suit you network. 

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

<command name="Create">

   <param name="imobject">

      <value>

         <management.IElementManagement>

            <ID type="Oid">

               {[MCNetwork][MCVM(IP=unit-ip)][Avm(AvmNumber=AVM-number)] 

               [ElementManagement(Key=NewVNEName)]}

            </ID>

            <ElementName type="String">NewVNEName</ElementName>

            <IP type="com.sheer.types.IPAddress">AVM-ip-addr</IP>

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

            <SchemeName type="String">ipcore</SchemeName>

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

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

            <SNMPReadCommunity type="String">public</SNMPReadCommunity>

            <SNMPWriteCommunity type="String">private</SNMPWriteCommunity>

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

            <SnmpV3AuthenticationPassword type="String" />

            <SnmpV3AuthenticationUserProfile type="String" />

            <SnmpV3EncryptionPassword type="String" />

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

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

            <TelnetPortNumber type="Integer">23</TelnetPortNumber>

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

            <TelnetSequence type="">Null</TelnetSequence>

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

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

            <PollingGroup type="management.IPollingGroupManagement">

               <ID type="Oid">

                     {[MCNetwork][MCVM(IP=172.20.68.122)][Avm(AvmNumber=208)]

                     [ElementManagement(Key=NewVNEName)]

                     [PollingGroupManagement(Name=default)]}

               </ID>

            </PollingGroup>

         </management.IElementManagement>

      </value>

   </param>

</command>

A dot (.) indicates success. In the event of a failure, an error message is displayed.

Delete Command

Description

The Delete command deletes an existing IMO object. The deleted IMO is identified by its OID. Not all data elements in the system can be deleted.

Syntax

Table 26-12 BQL Delete Command Syntax 

Element
Details

DELETE_COMMAND:

<command name="Delete">

<param name="oid">

<value> OID </value>

</param>

</command>

OID:

OID format as explained in the IMO OIDs, page 25-1 section


Output

A dot (.) indicates success. In the event of a failure, an error message is displayed.

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 an RS 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

Table 26-13 BQL Find Command Syntax 

Element
Details

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:

RS format as explained in Format and Syntax of a Retrieval Specification, page 25-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 RS. The output is IMObject_Array, where each element in the array is the IMO that matches the RS.

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 an RS 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.

Output

A dot (.) indicates success. In the event of a failure, an error message is displayed.

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 BQL error messages format, which presents the error message 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 following example: 

<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 following sections display example error messages in the XML format.

For detailed descriptions of BQL error messages, see Chapter 28, "Detailed BQL Errors Catalog and Examples."

BQL Error Example 1 

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

BQL Error Example 2 

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

BQL Error Example 3 

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

BQL Error Example 4 

<?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, contact the Cisco Project Manager or Cisco Account Team.

You can switch between two modes during each BQL session:

1. To enable the old non-XML error message format, enter xmlerrorreporting off.

The server responds with the following:

XML Error Reporting was set to OFF.

2. To enable the new XML error message format, enter xmlerrorreporting on.

The server responds with the following:

XML Error Reporting was set to ON.

To check the current XML error message format, enter xmlerrorreporting. The server response is one of the following:

•XML Error Reporting is : ON

•XML Error Reporting is : OFF