Handling GET requests for Atom collections

When a web client makes a GET request for an Atom collection, your service routine must respond with an entry or a series of entries from the collection.

Procedure

  1. Use the EXEC CICS GET CONTAINER command to retrieve the data in the DFHATOMPARMS container, which contains information about the request. The sample service routine DFH$W2S1 shows you how to do this. DFHATOMPARMS container describes all the parameters that CICS passes in this container.
  2. Check the value of the ATMP_HTTPMETH parameter to identify the request method. CICS returns an error or makes an appropriate response for methods other than GET, POST, PUT, and DELETE.
  3. Use the values of the ATMP_ATOMTYPE and ATMP_SELECTOR parameters in the DFHATOMPARMS container to identify the Atom entry that your program must return to CICS in this instance.
    1. If ATMP_SELECTOR is null and ATMP_ATOMTYPE has the value "collection", the client did not specify a particular Atom entry. If possible, return the Atom entry in the collection that was edited most recently. If your resource cannot store this data, return the Atom entry that was added to the collection most recently.
    2. If ATMP_SELECTOR contains a selector value and ATMP_ATOMTYPE has the value "collection", return the entry identified by the selector value. This combination of values indicates that the client is requesting a second or subsequent entry from the collection.
    3. If ATMP_SELECTOR contains a selector value and ATMP_ATOMTYPE has the value "entry", return the entry identified by the selector value. This combination of values indicates that the client is requesting a single, known Atom entry from the collection.
  4. When you have identified the Atom entry that is required for the GET request, return the entry from the collection as you would for an ordinary Atom feed, but take the following additional steps:
    1. Use the ATMP_EDITED parameter in the DFHATOMPARMS container to return the date and time at which this Atom entry was last edited. If you are using the resource handling parameters in the DFHATOMPARMS container, the ATMP_EDITED_FLD parameter has the name and length of the relevant field in the resource. If your resource does not store this data, return spaces, and CICS assumes the current date and time. DFHATOMPARMS container documents the required format for this field.
    2. Use the ATMP_ETAGVAL parameter in the DFHATOMPARMS container to return the entity tag for the Atom entry, followed by its length. To create an entity tag, you can use the EXEC CICS BIF DIGEST command to calculate the SHA-1 digest of the resource record, or use another suitable method to produce an entity tag that complies with the HTTP/1.1 protocol requirements.
    3. If ATMP_ATOMTYPE has the value "collection", meaning that the client wants multiple entries, and your resource stores data about when the entries were last edited, return the ATMP_NEXTSEL parameter as the selector value for the next Atom entry in the collection. Sequence for Atom entries explains the order in which you should return your Atom entries. Returning the entries in the order of editing helps your compliance with the Atom Publishing Protocol.
    4. If ATMP_ATOMTYPE has the value "collection", return the ATMP_PREVSEL, ATMP_FIRSTSEL, and ATMP_LASTSEL parameters as the selector values for the previous, first, and last Atom entries in the collection. CICS uses these values to construct <atom:link> elements containing links to other partial lists of entries in the collection. For more information about these parameters, see DFHATOMPARMS container.
    The steps to return an entry for an ordinary Atom feed are listed in Writing a program to supply Atom entry data.


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