Chapter 7 Cisco Crs-1 Series Xml And Large Data Retrieval (Iterators) - Cisco CRS-1 - Carrier Routing System Router Api Manual

Cisco CRS-1 Series XML and Large Data
Retrieval (Iterators)
The extensible markup language (XML) for the Cisco CRS-1 Series Carrier Routing System (Cisco
CRS-1 Series) supports the retrieval of large XML responses in blocks (that is, in chunks or sections).
Note The XML 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
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 will know that all of the data has been 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 applying the block size
and IteratorID is 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 will be
rejected. The rejected operations will need to be re-sent 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 will be
constant between <GetNext> operations.
In order to reduce memory overhead and avoid memory starvation of the router, the following limitations
have been placed on the number of allowed iterators:
OL-4596-01
C H A P T E R
section"Terminating an Iterator"
Cisco CRS-1 Series Carrier Routing System XML API Guide
7
for
7-81