Handling Atom collection editing requests in your service routine

When you create a collection from an existing Atom feed that is provided by a service routine, update the program to take appropriate actions for POST, PUT, and DELETE requests, as well as GET requests, for the entries in the collection.

The interface between CICS and the service routine essentially works in the same way for a collection as it does for an ordinary Atom feed. CICS provides information about the client request to your program in the DFHATOMPARMS container. Your program must analyze the request and then respond by returning the DFHATOMPARMS container, and other character containers as needed, to CICS. The sample service routine DFH$W2S1 demonstrates how to do this.

The extra task involved for a collection is that the program might have to action the client request by modifying records in the resource (a database, file, or other resource) that holds the data for the Atom entries for this feed. Instead of simply returning the data for a single Atom entry taken from the resource, the program might need to respond as follows:
  • For a POST request, add a new record and populate it with the data for a new Atom entry that the client has supplied.
  • For a PUT request, edit an existing record according to changes requested by the client.
  • For a GET request, delete a record.

Depending on the request method, the response from the program might just be an HTTP status line to confirm the requested change, with no further data. The changes made by your service routine permanently modify the content of your resource, so you must make sure that appropriate security measures are in place.

For client requests using the POST and PUT methods, CICS supplies the request body in a container called DFHREQUEST. The client should send a request body containing a complete Atom entry document. Your program must parse the markup of the Atom entry document, match the elements in the Atom entry to the fields in the records in your resource, and use the content of the elements to create a new resource record or update an existing resource record. Your program must also provide content for some elements, such as date and time stamps.

The Atom Publishing Protocol (RFC 5023) allows servers much liberty to modify the metadata or content of entries that a client submits to them. Your service routine can usually ignore or override the content of elements in the client request if that is the best approach for your resource record, provided that the resulting entry meets the requirements for the Atom format. If you have a query about a specific element that you want to code your service routine to ignore or override, consult RFC 4287 and RFC 5023 to check that your proposed action is acceptable, and then go ahead.

When your service routine receives a client request relating to a collection, it must perform the tasks described in this section. The instructions assume that you have already written a service routine that responds to HTTP GET requests from web clients for an Atom feed, as explained in Writing a program to supply Atom entry data, and demonstrated in the sample service routine DFH$W2S1.

When you have coded your service routine to perform these tasks, if resource and command security are active in your CICS region and in use for the collection, ensure that the user IDs for web clients have the correct permissions to access the CICS resources and commands used by the service routine. For more information about security measures to protect Atom collections, see Security for Atom feeds.



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