Specifications

CHAPTER
7-85
Cisco CRS-1 Series Carrier Routing System XML API Guide
OL-4596-02
7
Cisco CRS-1 Series XML and Large Data
Retrieval (Iterators)
The extensible markup language (XML) for the Cisco CRS-1 Series router supports the retrieval of large
XML responses in blocks (that is, in chunks or sections).
Note The XML application programming interface (API) code is available for use on any Cisco platform that runs
Cisco IOS XR software.
This chapter provides information on large data retrieval. See the section“Terminating an Iterator” for
information on terminating an iterator.
When a client application makes a request, the resulting response data size is checked to determine if it
is larger than a predetermined block size. If it is not larger, then the complete data is returned in a normal
response. However, if the response data is larger than the block size, then the first set of data is returned
according to the block size along with an iterator ID included as the value of the IteratorID attribute. The
client must then send <GetNext> requests including the iterator ID until all the data is retrieved. The
client application knows that all of the data is retrieved when it receives a response that does not contain
an IteratorID attribute.
The following points should be noted by the client application when iterators are used:
• The block size is a fixed value specific to each transport mechanisms on the router, that is, the XML
agent for Common Object Request Broker Architecture (CORBA) and Secure Shell (SSH) or Telnet.
No mechanism is provided for the client application to specify a desired block size.
• The block size refers to the entire XML response, not just the payload portion of the response.
• Large responses are divided based on the requested block size, not on the contents. However, each
response is always a complete XML document.
• Requests containing multiple operations are treated as a single entity when the block size and
IteratorID are applied. As a result, the IteratorID is an attribute of the <Response> tag, never of an
individual operation.
• If the client application sends a request that includes an operation resulting in the need for an iterator
to return all of the response data, any further operations contained within that request are rejected.
The rejected operations are resent in another request.
• The IteratorID is an unsigned 32-bit value that should be treated as opaque data by the client
application. Furthermore, the client application should not assume that the IteratorID is constant
between <GetNext> operations.