Sequence for Atom entries

CICS, or your service routine, must determine the order in which multiple Atom entries are arranged in an Atom feed document.

RFC 5023, The Atom Publishing Protocol, which is available from http://www.ietf.org/rfc/rfc5023.txt, states that entries in an Atom collection should be returned to a web client according to the order in which they were edited, as shown by the <app:edited> element in the entry. The Atom entry that was most recently edited should be returned first, so that it is the first Atom entry to appear in the Atom feed document. The next most recently edited Atom entry should be returned next, and so on, with the entry that was least recently edited being returned last. This function is a SHOULD requirement in RFC 5023 for a full list of Atom entries, where the whole collection is returned in a single feed document, but a MUST requirement for a partial list of Atom entries. RFC 5023 and RFC 4287 do not make any requirement for the ordering of Atom entries in an Atom feed that is not defined as a collection, so for entries in an Atom feed, servers can choose any order that is consistent and logical.

For reasons of performance, CICS does not automatically return Atom entries in a collection in the order in which they were most recently edited. CICS deviates from this requirement in order to maintain acceptable response times while still providing the useful function of partial lists. For both Atom feeds and collections, when CICS is extracting data directly from a resource to produce Atom documents, CICS returns Atom entries ordered by the time when they were written as records in the resource, as far as CICS can determine. The Atom entry that was written most recently is returned first, the next most recently written Atom entry is returned next, and so on. CICS determines the order of writing as follows:
  • For temporary storage queues, the Atom entry that has the highest record number is returned first.
  • For ESDS and extended ESDS files, the Atom entry that has the highest RBA (relative byte address) or XRBA (extended relative byte address) is returned first.
  • For RRDS and VRRDS files, the Atom entry that has the highest RRN (relative record number) is returned first.
  • For KSDS and AIX files, which do not have a concept of the order of writing, the Atom entries are returned in order of their record key, and the Atom entry with the lowest record key is returned first.
If you use a service routine to supply the data for your Atom entries, you can choose the order in which you return the Atom entries. If you want to return Atom entries in a collection according to when they were edited, in compliance with RFC 5023, a service routine can do this for Atom entries that are stored in a file. To return Atom entries in order of editing, take the following actions:
  1. In your file, include a field in the records that contains a time stamp in ABSTIME format showing when the entry was last edited. You can output this information in your Atom entries as the <app:edited> element.
  2. Define the field containing the time stamp as an alternate index for the file.
  3. In your service routine, use the alternate index to locate the records containing the data for the Atom entries, and return them with the most recently edited entry first, as indicated by the most recent timestamp.
You can also use this method if you want to return Atom entries in a feed according to when they were updated, rather than when they were first written. If you cannot store a suitable time stamp in the file that holds the data for your Atom entries, or if you find that ordering the entries using that information produces unacceptable response times, return the Atom entries in any order that is consistent and logical, such as the order used when CICS extracts data directly from a resource.
The values that your service routine supplies for the ATMP_PREVSEL, ATMP_NEXTSEL, ATMP_FIRSTSEL, and ATMP_LASTSEL parameters in the DFHATOMPARMS container depend on the order that you have chosen for returning your Atom entries. If you are returning the Atom entries according to when they were edited or updated, as indicated by a time stamp, then the values for the parameters are as follows:
  • The previous Atom entry is the Atom entry that was edited after the present entry was edited.
  • The next Atom entry is the Atom entry that was edited just before the present entry was edited.
  • The first Atom entry is the Atom entry that was edited the most recently.
  • The last Atom entry is the Atom entry that was edited the least recently.
If you are returning the Atom entries according to when they were first written, then the values for the parameters are as follows:
  • The previous Atom entry is the Atom entry that was written after the present entry was written.
  • The next Atom entry is the Atom entry that was written just before the present entry was written.
  • The first Atom entry is the Atom entry that was written the most recently.
  • The last Atom entry is the Atom entry that was written the least recently.



dfhtl_atom_returnorder.html | Timestamp icon Last updated: Sunday, 4 June 2017