Handling POST requests for Atom collections

When a web client makes a POST request for an Atom collection, your service routine must create the new entry in the collection and return a copy of it to the client.

About this task

The web client supplies a complete Atom entry document in the body of their HTTP POST request, and CICS passes this request body to the service routine in the DFHREQUEST container.

If the resource that holds the data for your Atom entries has an XML binding with an associated XMLTRANSFORM resource, you can use the CICS functions for transforming XML into application data to parse the markup of the Atom entry document that the web client supplies. If an XMLTRANSFORM resource is available, CICS provides its name in the ATMP_XMLTRANSFORM parameter in the DFHATOMPARMS container. For more information about the TRANSFORM XMLTODATA command and instructions for using the data mapping functions, see Mapping and transforming application data and XML.

If you do not have an XML binding for the resource that holds the data for your Atom entries, other facilities are available depending on the language of your service routine:
  • If your program is written in C or Assembler, you can use the z/OS XML System Services parser to parse the markup of the entry.
  • If your program is written in Enterprise COBOL, use the XML PARSE verb, as in the DFH0W2F1 COBOL sample service routine.
  • If your program is written in Enterprise PL/I, use the PLISAXA library function.

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 EXEC CICS GET CONTAINER command to retrieve the data in the DFHREQUEST container, which contains the new Atom entry. The sample service routine DFH$W2S1 shows you how to do this. CICS does not support other media types in Atom feeds, and rejects with a 415 status code any client request that is not described as an Atom entry, with the media type application/atom+xml, with or without the type=entry parameter.
  4. 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.
  5. Create a new record in the resource that holds the data for your Atom entries, and populate its fields with the content of the elements that you have identified. Your service routine can include whatever level of error checking you feel is appropriate, depending on the nature of your client and the sensitivity of the resource that holds the data for your Atom entries. 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. CICS ignores Atom IDs provided by web clients, and your service routine should also do this. Substitute an Atom ID produced by completing the prototype Atom ID passed by CICS in the ATMP_ATOMID parameter in the DFHATOMPARMS container, or use another valid format. For more information about the format of Atom IDs, see Atom IDs for Atom entries
  6. If your resource stores data for the time when the entry was last edited (<app:edited> element), when it was last updated (<atom:updated> element), or when it was first published (<atom:published> 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>, <atom:published>, or <app:edited> elements, you might want to generate a new date and time stamp to ensure accuracy and validity. For more information about handling date and time stamps, see Date and time stamps for Atom entries.
  7. If the client request is successful, return the new entry as you would for an ordinary Atom feed, supplying the data that you just placed in the new resource record, but with the following exceptions to the normal process:
    1. Do not return an ATMP_NEXTSEL parameter.
    2. Use the EXEC CICS BIF DIGEST command to calculate the SHA-1 digest of the new 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 an entity tag for the Atom entry, followed by its length.
    3. 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).
    The sample service routine DFH$W2S1 shows you how to return an Atom entry to CICS. CICS creates the response with an HTTP status code of 201 and supplies a Location header to give the client the URI of the new Atom entry, and a matching Content-Location header so that the client knows the response is a complete representation of the Atom entry. The client can examine the entry in the body of the message to see any modifications that you made to the data supplied in its request.
  8. 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_post.html | Timestamp icon Last updated: Sunday, 4 June 2017