Handling PUT requests for Atom collections
When a web client makes a PUT request for an Atom collection, your service routine must update the entry and indicate whether or not the request was successful.
About this task
Procedure
- 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.
- 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.
- Use the EXEC CICS GET CONTAINER command to retrieve the data in the DFHREQUEST container, which contains the updated Atom entry. The sample service routine DFH$W2S1 shows you how to do this.
- Use the ATMP_SELECTOR parameter to select, from the resource that holds the data for your Atom entries, the record that contains the data for the Atom entry which the client wants to update.
- Use the EXEC CICS BIF DIGEST command to calculate the SHA-1 digest of the current record in your resource that contains the data for the Atom entry, or calculate the entity tag using your service routine's alternative method, and compare this to the entity tag provided in ATMP_ETAGVAL. If the tags do not match, indicating that the data for the Atom entry has been changed by another agent since the web client obtained its copy, reject the request with the response code atmp_resp_etag_no_match. If the entity tag is an asterisk, the web client has chosen to override this process, and you should accept the request.
- Using the CICS functions for transforming XML into application data, or another suitable
facility, parse the XML markup for the Atom entry to identify all the elements of the Atom entry for
which CICS provides support and the resource that holds the data for your Atom entries has a
suitable field to store data. For a listing and description of all the elements of Atom entries for which CICS provides
support, see <atom:entry> Atom configuration file element. Ignore any elements that CICS does not support, or that your service routine does not
recognize, or that you cannot store in a field in a record in the resource that holds the data for
your Atom entries. Your Atom configuration file should already be set up to provide suitable
defaults for any required elements for which your resource is not able to store data.Tip: If you find that the web client has submitted a request containing invalid XML markup or data, reject the request with the response code atmp_resp_invalid_request.
- Update the record in your resource that contains the data for the Atom entry, using the content of the elements that you have identified to make modifications to the fields in the record. In the body of a PUT request, the client is expected to provide the complete Atom entry including the changed and unchanged elements, so in theory you can update all the fields in the resource record without comparing them to see which ones have changed. However, depending on the nature of your client and the sensitivity of your resource, you might want to carry out error checking for any fields that have particular requirements for the format of their content, and check that the client has not changed the content of any fields where a change is not logical, such as the Atom ID or the time of first publication. If you have to override any of the data provided by the client, you may do this, but check your action against RFC 4287 and RFC 5023 to verify that your override is valid.
- If your resource stores data for the time when the entry was last edited (<app:edited> element) and when it was last updated (<atom:updated> element), use the EXEC CICS ASKTIME and EXEC CICS FORMATTIME commands to produce a date and time stamp in the RFC 3339 format for the current date and time, and use this time stamp to populate those fields. If the client provides date and time stamps in the <atom:updated> or <app:edited> elements, ignore these, because they might simply be the previous date and time stamps returned unchanged. For more information about handling date and time stamps, see Date and time stamps for Atom entries.
- If the client request is successful, return the updated
entry as you would for an ordinary Atom feed, supplying the data from
the updated resource record, but with the following exceptions to
the normal process:
- Do not return an ATMP_NEXTSEL parameter.
- Use the EXEC CICS BIF DIGEST command to calculate the SHA-1 digest of the updated resource record, or use another suitable method to produce an entity tag that complies with the HTTP/1.1 protocol requirements. Use the ATMP_ETAGVAL parameter in the DFHATOMPARMS container to return the result as a new entity tag for the Atom entry, followed by its length.
- For the ATMP_EDITED parameter, you may either return the date and time stamp that you stored in your resource, or return spaces to allow CICS to provide the current date and time (provided that you did not specify an alternative default in your Atom configuration file).
- If the client request is unsuccessful, use the ATMP_RESPONSE parameter in the DFHATOMPARMS container to return a suitable response code. When you return an error response, CICS produces a suitable default HTTP error response to send to the web client. DFHATOMPARMS container lists the response codes that you can use and the HTTP error response that CICS sends in each case.
dfhtl_atom_coll_servroutine_put.html |
Last updated: Sunday, 4 June 2017