Writing a program to supply Atom entry data

You can write a service routine to provide an Atom feed from any data that can be accessed by a CICS program, such as records from a DB2 database, records in a file, or a COMMAREA. These instructions tell you how to write a program that responds to HTTP GET requests for an Atom feed.

About this task

Web clients might request a number of Atom entries from a feed, or request a specific entry. CICS receives the requests from web clients, and links to the program with information about each client request. CICS links to the program once for each Atom entry that the client requests, and the program returns a single entry each time.

The program supplies the Atom entry using data that it has extracted from a record in the resource, such as a database or file, that holds the data for the Atom entries for this feed. For an overview of this process, see Data processing for Atom feeds from CICS.

CICS uses a container interface to communicate with the service routine. Use the EXEC CICS GET CONTAINER and EXEC CICS PUT CONTAINER commands to interact with the containers. The C language sample service routine DFH$W2S1 shows you how to use the containers to respond to HTTP GET requests. The COBOL sample service routine DFH0W2F1 also shows you how to use the containers, but be aware that the DFH0W2F1 sample is more complex because it responds to HTTP PUT, POST, and DELETE requests as well as GET requests.

Because the web client request is an HTTP request, you can also interact with it using the CICS web API commands, such as the WEB READ HTTPHEADER and WEB READ QUERYPARM commands. If you know how to use these commands, you may use them in the service routine to obtain information directly from the web client request, including any information that CICS does not provide in the DFHATOMPARMS container.

If you can create an XML binding for the resource that contains the data for your Atom entries, you can pass information from CICS to the program in the DFHATOMPARMS container about the name and length of fields in the resource records that contain data for the Atom entries. Your program can use this information to locate the metadata fields in the resource records. By using these resource handling parameters, you can create a generic service routine that can handle multiple resources. However, you do not have to use the resource handling parameters; if you prefer, you can code information about the resource structure directly in the program.

To respond to a GET request, your service routine must perform these tasks:

Procedure

  1. Use the EXEC CICS GET CONTAINER command to retrieve the data in the DFHATOMPARMS container.
    CICS uses this container to provide the service routine with information about the request.
    The sample service routine DFH$W2S1 shows you how to read the parameters in DFHATOMPARMS.
    DFHATOMPARMS container has the full documentation for the parameters that CICS passes in this container.
  2. Check the value of the ATMP_HTTPMETH parameter to verify that the request method is GET.
    CICS returns an error or makes an appropriate response for methods other than GET, POST, PUT, and DELETE. For instructions on responding to HTTP PUT, POST, or DELETE requests to an Atom collection, see Handling Atom collection editing requests in your service routine.
  3. Use the values of the ATMP_ATOMTYPE and ATMP_SELECTOR parameters from the DFHATOMPARMS container to identify the record in the resource that contains the data for the Atom entry that the program must return to CICS.
    The ATMP_SELECTOR parameter might contain a selector value that identifies a particular Atom entry. Selector value for Atom entries explains what the selector value can be, and how CICS and the service routine use it.
    1. If ATMP_SELECTOR is null and ATMP_ATOMTYPE has the value "feed", the client did not specify a particular Atom entry, so locate the record in the resource that holds the most recent Atom entry that was added to the feed.
      For example, if the data for your Atom entries is held in a database, use the newest record that was added to the database.
    2. If ATMP_SELECTOR contains a selector value and ATMP_ATOMTYPE has the value "feed", locate the record in the resource that is identified by the selector value.
      This combination of values might indicate that CICS needs a second or subsequent Atom entry from the feed to complete a client request, and CICS is requesting one of these Atom entries using a selector value that the service routine supplied in a previous iteration. This combination of values is also used for the first Atom entry in a request when the client has requested a feed document containing a specific range of Atom entries, such as a partial list.
    3. If ATMP_SELECTOR contains a selector value and ATMP_ATOMTYPE has the value "entry", locate the record in the resource that is identified by the selector value.
      This combination of values indicates that the client is requesting a single, known Atom entry from the feed.
  4. If you have an XML binding for the resource that contains the data for your Atom entries, and you want to use the resource handling parameters to pass information about the fields in the resource, code the service routine to use the values of the ATMP_TITLE_FLD parameter and the other parameters ending in _FLD to identify the name and length of each field that contains data for an element of an Atom entry.
    When you set up an Atom configuration file for the Atom feed that uses data from the resource, you will need to specify the names of these fields in the <cics:fieldnames> element of the Atom configuration file, and CICS will pass them to the service routine using the resource handling parameters.
    DFHATOMPARMS container documents the resource handling parameters.
  5. Use the PUT CONTAINER command to create a container named DFHATOMCONTENT, with DATATYPE(CHAR), that contains the content for the Atom entry, as stated in the record that you have identified from the resource.
    This container is required. The sample service routine DFH$W2S1 shows you how to update the container, and DFHATOMCONTENT container explains what to put in the container.
  6. If the record that you have identified from the resource includes any fields that supply metadata for the Atom entry, such as a title, use optional containers to return this metadata to CICS, following the steps in Returning Atom entry metadata in containers.
  7. If the record that you have identified from the resource includes any fields that supply date and time stamps for the point when the data was created or updated, return them as new values for the ATMP_PUBLISHED and ATMP_UPDATED parameters in the DFHATOMPARMS container.
    The sample service routine DFH$W2S1 shows you how to return new values for these parameters.
    For information about the format of these date and time stamps, see Date and time stamps for Atom entries.
  8. If the ATMP_SELECTOR parameter in the DFHATOMPARMS container was null on input to the service routine, meaning that the web client did not request a specific Atom entry, replace the null value with a suitable selector value for the present entry that you are returning.
    The sample service routine DFH$W2S1 shows you how to return a selector value if the ATMP_SELECTOR parameter is null.
    Selector value for Atom entries explains how to choose a selector value.
    If the ATMP_SELECTOR parameter contained a selector value on input to the service routine, do not change it.
  9. If the ATMP_ATOMTYPE parameter in the DFHATOMPARMS container had the value "feed", indicating that the client wants multiple entries, check whether the resource contains any more, older, data that can be used to provide further Atom entries.
    1. If older data is present, locate the next data item that provides an Atom entry and return a suitable selector value for this data item to be used in the ATMP_NEXTSEL parameter.
      Sequence for Atom entries explains the order in which you should return the Atom entries.
    2. If no more data is available, set the current length of the data in the ATMP_NEXTSEL parameter to zero to return a null value.
  10. Read the ATMP_ATOMID parameter in the DFHATOMPARMS container to see the prototype Atom ID for the entry. The prototype Atom ID must be completed by appending the selector value for the Atom entry, as specified in the ATMP_SELECTOR parameter. If you prefer, your service routine can ignore the prototype Atom ID and substitute its own valid Atom ID for the Atom entry.
    For more information about the requirements for Atom IDs, see Atom IDs for Atom entries.
    1. If you have stored a complete Atom ID in the resource record for this Atom entry, return this Atom ID followed by its length in the ATMP_ATOMID parameter.
      If you are using the resource handling parameters in the DFHATOMPARMS container, the ATMP_ID_FLD parameter has the name and length of the relevant field in the resource.
    2. If the resource does not store Atom IDs, set the current length of the data for the ATMP_ATOMID parameter to zero.
      CICS appends the selector value to produce the complete Atom ID.
  11. Return a suitable response code to be used in the ATMP_RESPONSE parameter in the DFHATOMPARMS container.
    The sample service routine DFH$W2S1 shows you how to do this.
    The code is initialized to zero, indicating successful completion.
    If an error response is returned, CICS produces a suitable default HTTP error response to send to the web client. ATMP_RESPONSE parameter in DFHATOMPARMS container lists the available response codes and the HTTP error response that CICS sends in each case.
    The sample service routine DFH$W2S1 returns control to CICS after setting the response code.

What to do next

When you have written your service routine, create and install a suitable PROGRAM resource definition in CICS to describe the service routine. In your PROGRAM resource definition, use the EXECKEY(USER) attribute. The PROGRAM resource must be defined locally. You will need to name this PROGRAM resource in the ATOMSERVICE resource definition for your Atom feed.

When you have set up CICS definitions that use your service routine to provide data for an Atom feed, you can use the CEDX transaction to monitor and debug your service routine as it responds to HTTP requests. CW2A is the default alias transaction for Atom feeds, and your service routine runs under this transaction unless you set up an alternative alias transaction. CEDX monitors the next instance of the transaction that you specify, so if other users are working with Atom feeds in this CICS region using the same alias transaction, set up an alternative alias transaction to use while you are debugging your service routine.