Cisco XML and Native Data Access Techniques

This chapter describes the various techniques or strategies you can use to structure native data operation requests to access the information needed within the XML schema object class hierarchy.

Available Set of Native Data Access Techniques

The available native data access techniques are:

•Request all data in the configuration hierarchy. See the "XML Request for All Configuration Data" section.

•Request all configuration data for a component. See the "XML Request for All Configuration Data per Component" section.

•Request all data within a container. See the "XML Request for Specific Data Items" section.

•Combine object class hierarchies within a request. See the "XML Request with Combined Object Class Hierarchies" section.

•Use wildcards in order to apply an operation to a set of entries within a table (Match attribute). See the "XML Request Using Wildcarding (Match Attribute)" section.

•Repeat naming information in order to apply an operation to multiple instances of an object. See the "XML Request for Specific Object Instances (Repeated Naming Information)" section.

•Perform a one-level <Get> in order to "list" the naming information for each entry within a table (Content attribute). See the "XML Request Using Operation Scope (Content Attribute)" section.

•Specify the maximum number of table entries to be returned in a response (Count attribute). See the "Limiting the Number of Table Entries Returned (Count Attribute)" section.

•Use custom filters to filter table entries (Filter element). See the "Custom Filtering (Filter Element)" section.

•Use the Mode attribute. See the "XML Request Using the Mode Attribute" section

The actual data returned in a <Get> request depends on the value of the Source attribute.

Note The term "container" is used in this document as a general reference to any grouping of related data, for example, all of the configuration data for a particular Border Gateway Protocol (BGP) neighbor. The term "table" is used more specifically to denote a type of container that holds a list of named homogeneous objects. For example, the BGP neighbor address table contains a list of neighbor addresses, each of which is identified by its IP address. All table entries in the XML API are identified by the unique value of their <Naming> element.

XML Request for All Configuration Data

Use the empty <Configuration/> tag to retrieve the entire configuration object class hierarchy.

This example shows how to get the entire configuration hierarchy by specifying the empty <Configuration/> tag:

Sample XML Client Request to <Get> the Entire Configuration Object Class Hierarchy 

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

<Request MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration/>

  </Get>

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

            .

            .

            .

        response data goes here

            .

            .

            .

    </Configuration>

  </Get>

  <ResultSummary ErrorCount="0"/>

</Response>

XML Request for All Configuration Data per Component

All the configuration data for a component is retrieved by specifying the highest level tag for the component.

In this example, all the configuration data for BGP is retrieved by specifying the empty <BGP/> tag:

Sample XML Client Request for All BGP Configuration Data 

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

<Request MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="24" MinorVersion="0"/>

    </Configuration>

  </Get>

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="24" MinorVersion="0">

            .

            .

            .

          response data goes here

            .

            .

            .

      </BGP>

    </Configuration>

  </Get>

  <ResultSummary ErrorCount="0"/>

</Response>

XML Request for All Data Within a Container

All data within a container is retrieved by specifying the configuration or operational object class hierarchy down to the containers of interest, including any naming information as appropriate.

This example shows how to retrieve the configuration for the BGP neighbor with address 10.0.101.6:

Sample XML Client Request to Get All Address Family-Independent Configuration Data Within a BGP Neighbor Container 

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

<Request MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="24" MinorVersion="0">

        <AS>

          <Naming> 

            <AS>0</AS>

          </Naming>

          <FourByteAS>

             <Naming>

               <AS>3</AS>

             </Naming>

             <DefaultVRF>

               <BGPEntity>

                 <NeighborTable>

                   <Neighbor>

                     <Naming>

                       <NeighborAddress>

                         <IPV4Address>10.0.101.6</IPV4Address>

                       </NeighborAddress>

                     </Naming>

                   </Neighbor>

                 </NeighborTable>

               </BGPEntity>

             </DefaultVRF>

           </FourByteAS>

         </AS>

       </BGP>

     </Configuration>

   </Get>

 </Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="35" MinorVersion="2">

        <AS>

          <Naming>

            <AS>0</AS>

          </Naming>

          <FourByteAS>

           <Naming>

            <AS>3</AS>

            <DefaultVRF>

             <BGPEntity>

              <NeighborTable>

                <Neighbor>

                  <Naming>

                   <NeighborAddress>

                    <IPV4Address>10.0.101.6</IPV4Address>

                   </NeighborAddress>

                  </Naming>

                  <RemoteAS>

                   <AS XX>0</AS XX>

                   <AS YY>6</AS YY>

                  </RemoteAS>

                  <EBGPMultihop>

                      <MaxHopCount>255</MaxHopCount>

                      <MPLSDeactivation>false</MPLSDeactivation> 

                  </EBGPMultihop>

                  <NeighborAFTable>

                    <NeighborAF>

                      <Naming>

                        <AFName>IPv4Unicast</AFName>

                      </Naming>

                      <Activate>true</Activate>

                      <PrefixORFPolicy>oBGP_pass_all</PrefixORFPolicy>

                      <AdvertiseORF>Both</AdvertiseORF>

                     </NeighborAF>

                     <NeighborAF>

                      <Naming>

                        <AFName>IPv4Multicast</AFName>

                      </Naming>

                      <Activate>true</Activate>

                      <PrefixORFPolicy>BGP_pass_all</PrefixORFPolicy>

                    </NeighborAF>

                  </NeighborAFTable>

                </Neighbor>

              </NeighborTable>

            </BGPEntity>

          </DefaultVRF>

         </FourByteAS>

        </AS>

      </BGP>

    </Configuration>

  </Get>

  <ResultSummary ErrorCount="0"/>

</Response>

XML Request for Specific Data Items

The value of a specific data item (leaf object) can be retrieved by specifying the configuration or operational object class hierarchy down to the item of interest, including any naming information as appropriate.

This example shows how to retrieve the values of the two data items <RemoteAS> and <EBGPMultihop> for the BGP neighbor with address 10.0.101.6:

Sample XML Client Request for Two Specific Data Items: RemoteAS and EBGPMultihop 

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

<Request MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="35" MinorVersion="2">

        <AS>

          <Naming><AS>0</AS></Naming>

          <FourByteAS>

            <Naming><AS>3</AS></Naming>

            <DefaultVRF>

              <BGPEntity>

                <NeighborTable>

                  <Neighbor>

                    <Naming>

                      <NeighborAddress>

                        <IPV4Address>10.0.101.6</IPV4Address>

                      </NeighborAddress>

                    </Naming>

                    <RemoteAS/>

                    <EBGPMultihop/>

                  </Neighbor>

                </NeighborTable>

              </BGPEntity>

            </DefaultVRF>

          </FourByteAS>

        </AS>

      </BGP>

    </Configuration>

  </Get>

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

     <BGP MajorVersion="35" MinorVersion="2">

       <AS>

        <Naming>

         <AS>0</AS>

        </Naming>

        <FourByteAS>

         <Naming>

          <AS>3</AS>

         </Naming>

         <DefaultVRF>

          <BGPEntity>

           <NeighborTable>

            <Neighbor>

             <Naming>

              <NeighborAddress>

               <IPV4Address>10.0.101.6</IPV4Address>

              </NeighborAddress>

             </Naming>

           <EBGPMultihop>

               <MaxHopCount>255</MaxHopCount>

           </EBGPMultihop>

            </Neighbor>

           </NeighborTable>

          </BGPEntity>

         </DefaultVRF>

        </FourByteAS>

       </AS>

     </BGP>

    </Configuration>

  </Get>

  <ResultSummary ErrorCount="0"/>

</Response>

XML Request with Combined Object Class Hierarchies

Multiple object class hierarchies can be specified in a request. For example, a portion of the hierarchy can be repeated, and multiple instances of a child object class can be included under a parent.

The object class hierarchy may also be compressed into the most "efficient" XML. In other words, it is not necessary to repeat hierarchies within a request.

Before combining multiple operations inside one <Get> tag, these limitations should be noted for Release 3.0. Any operations that request multiple items of data must be sent in a separate XML request. They include:

•An operation to retrieve all data beneath a container. For more information, See the"XML Request for All Data Within a Container" section.

•An operation to retrieve the list of entries in a table. For more information, See the "XML Request Using Operation Scope (Content Attribute)" section.

•An operation which includes a wildcard. For more information, See the "XML Request Using Wildcarding (Match Attribute)" section.

If an attempt is made to make such an operation followed by another operation within the same request, this error is returned: 

XML Service Library detected the `fatal' condition. The XML document which led to this 
response contained a request for a potentially large amount of data, which could return a 
set of iterators. The document also contained further requests for data, but these must be 
sent in a separate XML document, in order to ensure that they are serviced.

The error indicates that the operations must be separated out into separate XML requests.

These two examples illustrate two different object class hierarchies that retrieve the same data: the value of the leaf object <RemoteAS> and <EBGPMultihop> for the BGP neighbor with the address 10.0.101.6 and all of the configuration data for the BGP neighbor with the address 10.0.101.7:

Example 1: Verbose Form of a Request Using Duplicated Object Class Hierarchies

Sample XML Client Request for Specific Configuration Data Values 

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

<Request MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP>

        <AS>

          <Naming><AS>0</AS></Naming>

          <FourByteAS>

          <Naming>

             <AS>3</AS>

          </Naming> 

          <DefaultVRF>

            <BGPEntity>

              <NeighborTable>

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                       <IPV4Address>10.0.101.6</IPV4Address>

                     </NeighborAddress>

                  </Naming>

                  <!-- Gets the following two leaf objects for this neighbor -->

                  <RemoteAS/>

                  <EBGPMultihopMaxHopCount/>

                </Neighbor>

              </NeighborTable>

            </BGPEntity>

          </DefaultVRF>

        </FourByteAS>

      </AS>

    </BGP>

  </Configuration>

</Get>

<Get>

  <Configuration>

    <BGP>

      <AS>

        <Naming><AS>0</AS></Naming>

        <FourByteAS>

          <Naming>AS>3</AS</Naming>

          <DefaultVRF>

            <BGPEntity>

              <NeighborTable>

                <Neighbor>

                 <Naming>

                   <NeighborAddress>

                     <IPV4Address>10.0.101.7</IPV4Address>

                   </NeighborAddress>

                 </Naming>

                </Neighbor>

              </NeighborTable>

            </BGPEntity>

          </DefaultVRF>

        </FourByteAS>

      </AS>

    </BGP>

   </Configuration>

  </Get>

 </Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

            .

            .

            .

        response data returned here for

        neighbor 10.0.101.6

            .

            .

            .

    </Configuration>

  </Get>

  <Get>

    <Configuration>

            .

            .

            .

        response data returned here

        neighbor 10.0.101.7

            .

            .

            .

    </Configuration>

  </Get>

  <ResultSummary ErrorCount="0"/>

</Response>

Example 2: Compact Form of a Request Using Compressed Object Class Hierarchies

Sample XML Client Request 

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

<Request MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="35" MinorVersion="2">

        <AS>

          <Naming><AS>0</AS></Naming>

          <FourByteAS>

            <Naming><AS>3</AS></Naming>

            <DefaultVRF>

              <BGPEntity>

                <NeighborTable>

                  <Neighbor>

                    <Naming>

                     <NeighborAddress>

                       <IPV4Address>10.0.101.6</IPV4Address>

                     </NeighborAddress>

                   </Naming>

                  <!-- Gets the following two leaf objects for this neighbor -->

                  <RemoteAS/>

                  <EBGPMultihop/>

                </Neighbor>

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                       <!-- Gets all configuration data for this neighbor -->

                       <IPV4Address>10.0.101.7</IPV4Address>

                     </NeighborAddress>

                  </Naming>

                </Neighbor>

                </NeighborTable>

            </BGPEntity>

          </DefaultVRF>

         </FourByteAS>

       </AS>

     </BGP>

   </Configuration>

  </Get>

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

            .

            .

            .

        response data returned here for both

        neighbors

            .

            .

            .

    </Configuration>

  </Get>

  <ResultSummary ErrorCount="0"/>

</Response>

XML Request Using Wildcarding (Match Attribute)

Wildcarding of naming information is provided by means of the Match attribute. Match="*" can be used on any Naming attribute within a <Get> or <Delete> operation to effectively specify a wildcarded value for that attribute. The operation applies to all instances of the requested objects.

If no match is found, the response message contains MatchFoundBelow="false" in the <Get> class, and MatchFound="false" in the class that specified Match="*" and no match found. These attributes are not added (with a value of true) in the response if a match is found.

Note Although partial wildcarding of NodeIDs is not available in XML, each element of the NodeID has to be wildcarded, similar to the support on the CLI of */*/* as the only wildcards supported for locations.

This example shows how to use the Match attribute to get the <RemoteAS> value for all configured BGP neighbors:

Sample XML Client Request Using the Match Attribute Wildcarding 

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

<Request MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="35" MinorVersion="2">

        <AS>

          <Naming><AS>0</AS></Naming>

          <FourByteAS>

            <Naming><AS>3</AS></Naming>

            <DefaultVRF>

              <BGPEntity>

                <NeighborTable>

                  <Neighbor>

                    <Naming>

                      <NeighborAddress Match="*"/>

                    </Naming>

                    <RemoteAS/>

                  </Neighbor>

                 </NeighborTable>

              </BGPEntity>

            </DefaultVRF>

          </FourByteAS>

        </AS>

      </BGP>

    </Configuration>

  </Get>

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="35" MinorVersion="2">

        <AS>

          <Naming><AS>0</AS></Naming>

          <FourByteAS>

            <Naming><AS>3</AS></Naming>

            <DefaultVRF>

              <BGPEntity>

                <NeighborTable>

                  <Neighbor>

                    <Naming>

                      <NeighborAddress>

                        <IPV4Address>10.0.101.1</IPV4Address>

                      </NeighborAddress>

                    </Naming>

                   <RemoteAS>1</RemoteAS>

                 </Neighbor>

                 <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>10.0.101.2</IPV4Address>

                    </NeighborAddress>

                  </Naming>

                  <RemoteAS>2</RemoteAS>

                </Neighbor>

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>10.0.101.3</IPV4Address>

                    </NeighborAddress>

                  </Naming>

                  <RemoteAS>3</RemoteAS>

                </Neighbor>

                ...

                  data for more neighbors

                  returned here

                ...

                </NeighborTable>

              </BGPEntity>

            </DefaultVRF>

          </FourByteAS>

        </AS>

      </BGP>

    </Configuration>

  </Get>

  <ResultSummary ErrorCount="0"/>

</Response>

This example shows the response message when there is no match found for the request with wildcarding:

Sample XML Client Request for No Match Found with Wildcarding 

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

<Request MajorVersion="1" MinorVersion="0"> 

  <Get>  
    <Configuration> 

      <BGP MajorVersion="35" MinorVersion="2"> 

        <AS> 

          <Naming><AS>3</AS>

          <FourByteAS>

           <Naming><AS>3</AS></Naming>

           <DefaultVRF> 

             <BGPEntity> 

               <NeighborTable> 

                <Neighbor> 

                  <Naming>

                    <NeighborAddress Match="*"/> 

                  </Naming>

                  <RemoteAS/> 

                </Neighbor> 

               </NeighborTable> 

             </BGPEntity> 

           </DefaultVRF> 

          </FourByteAS>

        </AS> 

      </BGP> 

    </Configuration> 

  </Get> 

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0"> 

   <Get VersionMismatchExistsBelow="true" MatchFoundBelow="false" \ ItemNotFound="true">

    <Configuration>  
      <BGP MajorVersion="35" MinorVersion="2">  
        <AS>  
          <Naming>  
            <AS>3</AS>  
          </Naming> 

         <FourByteAS> 

            <Naming> 

               <AS>3</AS>

           </Naming> 
            <DefaultVRF>  
              <BGPEntity>  
                <NeighborTable>  
                  <Neighbor>  
                    <Naming> 

                    <NeighborAddress> 
                       <Address Match="*" MatchFound="false"/> 

                    <NeighborAddress> 
                    </Naming> 

                  <RemoteAS NotFound="true"/>  
                  </Neighbor>  
                </NeighborTable>  
              </BGPEntity>  
            </DefaultVrF> 

         </FourByteAS> 
        </AS>  
      </BGP>  
    </Configuration>  
  </Get> 

  <ResultSummary ErrorCount="0" ItemNotFound="true"/> 
</Response>

Regular expression matching of naming information is provided by means of the Match attribute. Match="<regular expression>" can be used on any Naming attribute within a <Get> operation to specify a filtering criteria to filter table entries.

These rules apply to the filtering criteria:

•The character, `*' , is treated same as the `.*' character. (matches everything)

•Meta character `^' (beginning of line) and `$' (end of line) are always attached to the regular expression string specified by `Match' attribute.

•A regular expression string without any meta characters is treated as an exact match.

Sample Request of the Configured ACL Entries That End With `SAA': 

<Get>

      <Configuration>

        <IPV4_ACLAndPrefixList>

          <AccessListTable>

            <AccessList>

              <Naming>

                <AccessListName Match=".*SAA"/>

              </Naming>

            </AccessList>

          </AccessListTable>

        </IPV4_ACLAndPrefixList>

      </Configuration>

     </Get>

ACL entries that match this request: TCLSAA, 100SAA, SAA

ACL entries that do NOT match this request: TCLSAA1

Sample Request That Returns all of the Configured GigabitEthernet Ports in Slot 5: 

<Get>

      <Configuration>

        <Configuration>

          <InterfaceConfigurationTable>

           <InterfaceConfiguration>

             <Naming>

               <Active>act</Active>

               <InterfaceName Match="GigabitEthernet0/5/[0-9]+/[0-9]+"/>

             </Naming>

           </InterfaceConfiguration>

         </InterfaceConfigurationTable>

       </Configuration>

     </Get>

Interface names that match this request: GigabitEthernet0/5/0/0, GigabitEthernet0/5/0/1, and so forth.

Interface names that do not match this request: GigabitEthernet0/4/0/0

Sample Request That Returns the Configured Loopback Interfaces Between Loopback100 and Loopback199: 

<Get>

      <Configuration>

        <Configuration>

          <InterfaceConfigurationTable>

           <InterfaceConfiguration>

             <Naming>

               <Active>act</Active>

               <InterfaceName Match="Loopback1[0-9][0-9]"/>

             </Naming>

           </InterfaceConfiguration>

         </InterfaceConfigurationTable>

       </Configuration>

     </Get>

Interface names that match this request: Loopback100,...,Loopback199

Interface names that do not match this request: Loopback1000, Loopback1990

Sample Request That Returns Only Loopback1 (if it is configured): 

<Get>

      <Configuration>

        <Configuration>

          <InterfaceConfigurationTable>

           <InterfaceConfiguration>

             <Naming>

               <Active>act</Active>

               <InterfaceName Match="Loopback1"/>

             </Naming>

           </InterfaceConfiguration>

         </InterfaceConfigurationTable>

       </Configuration>

     </Get>

Interface names that match this request: Loopback1

Interface names that do not match this request: Loopback10, Loopback100, and so forth

The request above, thus, is equivalent to this request: 

<Get>

      <Configuration>

        <Configuration>

          <InterfaceConfigurationTable>

           <InterfaceConfiguration>

             <Naming>

               <Active>act</Active>

               <InterfaceName>Loopback1</InterfaceName>

             </Naming>

           </InterfaceConfiguration>

         </InterfaceConfigurationTable>

       </Configuration>

     </Get>

Limitation: Regular expression matching can only be specified in the first table of an XML request.

XML Request for Specific Object Instances (Repeated Naming Information)

Wildcarding allows the client application to effectively specify all instances of a particular object. Similarly, the client application might have a need to specify only a limited set of instances of an object. Specifying object instances can be done by simply repeating the naming information in the request.

This example shows how to retrieve the address independent configuration for three different BGP neighbors; that is, the neighbors with addresses 10.0.101.1, 10.0.101.6, and 10.0.101.8, by repeating the naming information, once for each desired instance:

Sample XML Client Request Using Repeated Naming Information for BGP <NeighborAddress> Instances 

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

<Request MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP>

        <AS>

          <Naming>

            <AS>0</AS>

          </Naming>

        <FourByteAS>

          <Naming><AS>3</AS></Naming>

            <DefaultVRF>

               <BGPEntity>

                 <NeighborTable>

                   <Neighbor>

                      <Naming>

                        <NeighborAddress>

                          <IPV4Address>10.0.101.1</IPV4Address>

                        </NeighborAddress>

                      </Naming>

                    </Neighbor>

                 </NeighborTable>

                 <NeighborTable>

                   <Neighbor>

                     <Naming>

                       <NeighborAddress>

                          <IPV4Address>10.0.101.6</IPV4Address>

                       </NeighborAddress>

                     </Naming>

                   </Neighbor>

                 </NeighborTable>

                 <NeighborTable>

                   <Neighbor>

                     <Naming>

                       <NeighborAddress>

                          <IPV4Address>10.0.101.8</IPV4Address>

                        </NeighborAddress>

                     </Naming>

                   </Neighbor>

                 </NeighborTable>

               </BGPEntity>

             </DefaultVRF>

          </FourByteAS>

        </AS>

      </BGP>

    </Configuration>

  </Get>

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="35" MinorVersion="2">

        <AS>

          <Naming>

            <AS>0</AS>

          </Naming>

          <FourByteAS>

            <Naming><AS>3</AS></Naming>

            <DefaultVRF>

             <BGPEntity>

              <NeighborTable>

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>10.0.101.1</IPV4Address>

                    </NeighborAddress>

                  </Naming>

                ...

                  data returned for 1st neighbor

                ...

                </Neighbor>

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>10.0.101.6</IPV4Address>

                    </NeighborAddress>

                  </Naming>

                  ...

                    data returned for 2nd neighbor

                  ...

                </Neighbor>

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>10.0.101.6</IPV4Address>

                    </NeighborAddress>

                  </Naming>

                  ...

                    data returned for 3rd neighbor

                  ...

                </Neighbor>

              </NeighborTable>

            </BGPEntity>

            </DefaultVRF>

          </FourByteAS>

        </AS>

      </BGP>

    </Configuration>

  </Get>

  <ResultSummary ErrorCount="0"/>

</Response>

XML Request Using Operation Scope (Content Attribute)

The Content attribute is used on any table element in order to specify the scope of a <Get> operation. Table 5-1 describes the content attribute values are supported.

Table 5-1 Content Attributes 

Content Attribute
Description

All

Used to get all leaf items and their values. All is the default when the Content attribute is not specified on a table element.

Entries

Used to get the Naming information for each entry within a specified table object class. Entries provides a one-level get capability.


If the Content attribute is specified on a nontable element, it is ignored. Also, note that the Content and Count attributes can be used together on the same table element.

This example displays the Content attribute that is used to list all configured BGP neighbors:

Sample XML Client Request Using the All Content Attribute 

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

<Request MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="35" MinorVersion="2">

        <AS>

          <Naming>

            <AS>0</AS>

          </Naming>

          <FourByteAS>

            <Naming><AS>3</AS></Naming>

            <DefaultVRF>

             <BGPEntity>

              <NeighborTable Content="Entries"/>

             </BGPEntity>

            </DefaultVRF>

          <FourByteAS>

        </AS>

      </BGP>

    </Configuration>

  </Get>

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="35" MinorVersion="2">

        <AS>

          <Naming>

            <AS>0</AS>

          </Naming>

          <FourByteAS>

            <Naming><AS>3</AS></Naming>

            <DefaultVRF>

             <BGPEntity>

              <NeighborTable Content="Entries">

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>10.0.101.1</IPV4Address>

                    </NeighborAddress>

                  </Naming>

                </Neighbor>

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>10.0.101.2</IPV4Address>

                    </NeighborAddress>

                  </Naming>

                </Neighbor>

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>10.0.101.3</IPV4Address>

                    </NeighborAddress>

                  </Naming>

                </Neighbor>

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>10.0.101.4</IPV4Address>

                    </NeighborAddress>

                  </Naming>

                </Neighbor>

                  ...

                    more neighbors returned here

                  ...

              </NeighborTable>

            </BGPEntity>

           </DefaultVRF>

         </FourByteAS>

        </AS>

      </BGP>

    </Configuration>

  </Get>

  <ResultSummary ErrorCount="0"/>

</Request>

Limiting the Number of Table Entries Returned (Count Attribute)

The Count attribute is used on any table element within a <Get> operation to specify the maximum number of table entries to be returned in a response. When the Count attribute is specified, the naming information within the request is used to identify the starting point within the table, that is, the first table entry of interest. If no naming information is specified, the response starts at the beginning of the table.

For a table whose entries are containers, the Count attribute can be used only if the Content attribute is also specified with a value of Entries. This restriction does not apply to a table whose children are leaf nodes.

As an alternative to the use of the Count attribute, the XML interface supports the retrieval of large XML responses in blocks through iterators.

This example shows how to use the Count attribute to retrieve the configuration information for the first five BGP neighbors starting with the address 10.0.101.1:

Sample XML Client Request Using the Count Attribute 

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

<Request MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="35" MinorVersion="2">

        <AS>

          <Naming>

            <AS>0</AS>

          </Naming>

          <FourByteAS>

            <Naming><AS>3</AS></Naming>

            <DefaultVRF>

             <BGPEntity>

              <NeighborTable Count="5">

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>10.0.101.1</IPV4Address>

                    </NeighborAddress>

                  </Naming>

                </Neighbor>

              </NeighborTable>

            </BGPEntity>

           </DefaultVRF>

          <FourByteAS>

        </AS>

      </BGP>

    </Configuration>

  </Get>

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

  <Get>

    <Configuration>

      <BGP MajorVersion="24" MinorVersion="0">

        <AS>

          <Naming>

            <AS>0</AS>

          </Naming>

          <FourByteAS>

            <Naming><AS>3</AS></Naming>

             <DefaultVRF>

             <BGPEntity>

              <NeighborTable Count="5">

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>

                        10.0.101.1

                      </IPV4Address>

                    </NeighborAddress>

                  </Naming>

                </Neighbor>

                <Neighbor>

                  <Naming>

                    <NeighborAddress>

                      <IPV4Address>

                        10.0.101.2

                      </IPV4Address>

                    </NeighborAddress>

                  </Naming>

                </Neighbor>

                    ...

                   data returned for remaining

                   neighbors here

                    ...

              </NeighborTable>

            </BGPEntity>

           </DefaultVRF>

         </FourByteAS>

        </AS>

      </BGP>

    </Configuration>

  </Get>

  <ResultSummary ErrorCount="0"/>

</Response>

Custom Filtering (Filter Element)

Some of the tables from the operational namespace support the selection of rows of interest based on predefined filtering criteria. Filters can be applied to such tables in order to reduce the number of table entries retrieved in a request.

Client applications specify filtering criteria for such tables by using the <Filter> tag and including the filter specific parameters as defined in the XML schema definition for that table. If no table entries match the specified filter criteria, the response contains the object class hierarchy down to the specified table, but does not include any table entries. The Content attribute can be used with a filter to specify the scope of a <Get> request.

In this example, the filter <BGP_ASFilter> is used to retrieve operational information for all neighbors in autonomous system 6:

Sample XML Client Request Using Filtering 

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

<Request MajorVersion="1" MinorVersion="0">

  <Get>

    <Operational>

      <BGP>

        <Active>

          <VRFTable>

            <VRF>

              <Naming>

                <VRFName>one<VRFName>

              </Naming>

              <NeighborTable>

                <Filter>

                  <BGP_ASFilter>

                    <AS>6</AS>

                  </BGP_ASFilter>

                <Filter>

              </NeighborTable>

            </VRF>

          </VRFTable>

        </Active>

      </BGP>

    </Operational>

  </Get>

</Request>

Sample Filtered XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

  <Get>

    <Operational>

      <BGP MajorVersion="23" MinorVersion="7">

        <Active>

          <VRFTable>

           <VRF>

            <Naming>

             <VRFName>one</VRFName>

            </Naming>

          <NeighborTable>

            <Filter>

              <BGP_ASFilter>

                <AS>6</AS>

              </BGP_ASFilter>

            </Filter>

            <Neighbor>

                ...

                data for 1st neighbor returned here

                ...

            </Neighbor>

            <Neighbor>

                ...

                data for 2nd neighbor returned here

                returned here

                ...

            </Neighbor>

                ...

                data for remaining neighbors 

                returned here

                ...

          </NeighborTable>

        </VRF>

       </VRFTable>

     </Active>

    </BGP>

   </Operational>

  </Get>

  <ResultSummary ErrorCount="0"/>

</Response>

XML Request Using the Mode Attribute

The client application modifies the target configuration as needed using the <Delete> and <Set> operations. The XML interface supports the combining of several operations into a single request. When multiple configuring operations are specified in a single request, they are performed on a "best effort" basis by default. For example, in a case where configuring operations 1 through 3 are in the request and even if operation 2 fails, operation 3 is attempted and operation 1 result remains in the target configuration.

To perform the request on an atomic basis, use the Mode attribute with the value Atomic in the <Request>. If any errors occur, the target configuration is cleared and the errors are returned to the client application.

Sample XML Client Request with the Attribute Mode="Atomic" 

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

<Request Version="1.0" Mode="Atomic">

  <Set>

    <Configuration>

      <SNMP>

        <Timeouts>

          <Subagent> 20 </Subagent>

        </Timeouts>

      </SNMP>

    </Configuration>

  </Set>

  <Commit/>

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

    <Set>

        <Configuration/>

    </Set>

    <Commit CommitID="1000000441"/>

 <ResultSummary ErrorCount="0"/>

</Response>

Sample XML Client Request with an Invalid Set Operation (Best-Effort) 

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

<Request Version="1.0">

  <Set>

    <Configuration>

      <SNMP>

        <Timeouts>

          <Subagent> 20 </Subagent>

        </Timeouts>

      </SNMP>

    </Configuration>

  </Set>

  <Set>

    <Configuration>

      <SNMP>

        <System>

          <Contact> </Contact> <--- This is an invalid XML set operation

        </System>

      </SNMP>

    </Configuration>

  </Set>

  <Commit/>

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

    <Set>

        <Configuration/>

    </Set>

    <Set ErrorCode="0x43679000" ErrorMsg="&apos;XML Service Library&apos; detected the 
&apos;warning&apos; condition &apos;An error was encountered in the XML beneath this 
operation tag&apos;">

        <Configuration>

            <SNMP MajorVersion="7" MinorVersion="3">

                <System>

                    <Contact ErrorCode="0x4368b000" ErrorMsg="&apos;XMLMDA&apos; detected 
the &apos;warning&apos; condition &apos;The XML request does not conform to the schema. 
The XML below the element on which this error appears is missing a required piece of data. 
Please check the request against the schema.&apos;"/>

                </System>

            </SNMP>

        </Configuration>

    </Set>

  <Commit CommitID="1000000443"/> 

<ResultSummary ErrorCount="1"/> 

</Response>

Note This request is performed on a best effort basis. The SNMP timeout configuration has no error and is committed.

Sample XML Request and Response of Commit Change for ForCommitID="1000000443" 

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

 <Request>

  <Get>

   <Configuration Source="CommitChanges" ForCommitID="1000000443"/>

  </Get>

</Request>



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

<Response MajorVersion="1" MinorVersion="0">

    <Get>

        <Configuration Source="CommitChanges" ForCommitID="1000000443" 
OperationType="Set">

            <SNMP MajorVersion="7" MinorVersion="3">

                <Timeouts>

                    <Subagent>

                        20

                    </Subagent>

                </Timeouts>

            </SNMP>

        </Configuration>

    </Get>

  <ResultSummary ErrorCount="0"/>

</Response>

Sample XML Client Request with the Attribute Mode="Atomic" and with an Invalid Set Operation 

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

<Request Version="1.0" Mode="Atomic">

  <Set>

    <Configuration>

      <SNMP>

        <Timeouts>

          <Subagent> 20 </Subagent>

        </Timeouts>

      </SNMP>

    </Configuration>

  </Set>

  <Set>

    <Configuration>

      <SNMP>

        <System>

          <Contact> </Contact>    <--- This is an invalid XML set operation

        </System>

      </SNMP>

    </Configuration>

</Set>

  <Commit/>

</Request>

Sample XML Response from the Router 

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

<Response MajorVersion="1" MinorVersion="0">

    <Set>

        <Configuration/>

    </Set>

    <Set ErrorCode="0x43679000" ErrorMsg="&apos;XML Service Library&apos; detected the 
&apos;warning&apos; condition &apos;An error was encountered in the XML beneath this 
operation tag&apos;">

        <Configuration>

            <SNMP MajorVersion="7" MinorVersion="3">

                <System>

                    <Contact ErrorCode="0x4368b000" ErrorMsg="&apos;XMLMDA&apos; detected 
the &apos;warning&apos; condition &apos;The XML request does not conform to the schema. 
The XML below the element on which this error appears is missing a required piece of data. 
Please check the request against the schema.&apos;"/>

                </System>

            </SNMP>

        </Configuration>

    </Set>

    <Commit ErrorCode="0x41864e00" ErrorMsg="&apos;CfgMgr&apos; detected the 
&apos;warning&apos; condition &apos;The target configuration buffer is empty.&apos;"/>

  <ResultSummary ErrorCount="1"/>

</Response>

Note The target configuration buffer is cleared and no configuration is committed.