DFH0W2F1 - COBOL sample service routine for Atom feeds

The sample service routine DFH0W2F1 is a COBOL program that handles GET, POST, PUT, and DELETE requests for Atom entries that use data from the CICS® sample file FILEA. You can use these interactions as a model for handling resources in your own service routine.

About DFH0W2F1 - COBOL sample service routine for Atom feeds

You can run DFH0W2F1 to handle web client requests and supply data from the FILEA sample file for test or demonstration purposes.

The DFH0W2F1 sample program performs the following tasks:

Working-Storage section
  • Copies the copybook DFHW2CNO which has the constants for the response codes.
  • Sets up local variables in the working storage.
  • Includes the definition of the FILEA record layout, which is described in copybook DFH0CFIL which is shipped with CICS.
  • Sets up a prototype that contains XML tagging and fields to hold the content of the Atom entry. A carriage return line feed (X'0D25') is used between each XML element. The service routine will produce the content of the Atom entry by reading a record in the FILEA file, inserting the data from the fields in the record into this prototype, and returning it in the DFHATOMCONTENT container.
  • Sets up a prototype Atom entry title and summary that will be used in the DFHATOMTITLE and DFHATOMSUMMARY container. The records in the FILEA file do not contain titles and summaries, but the service routine will compose them using information from the file records. The title and summary that the service routine supplies replace the default title and summary that are specified in the Atom configuration file.
  • Sets up content to return for an Atom entry to indicate an error if FILEA cannot be read. This is for demonstration purposes and is not appropriate for a production Atom feed.
  • Sets up an XML stack that will be used when parsing Atom entries.
  • Sets up storage to contain the entity tag (ETag) for the Atom entry.
Linkage section
  • Copies the copybook DFHW2APO which describes the layout of the DFHATOMPARMS container.
  • Defines a variable length string that can be used for any parameter in the DFHATOMPARMS container.
  • Describes the storage that contains the request body from the web client which was passed in the DFHREQUEST container.
  • Defines storage to contain the selector values for the first, last, next, and previous records in the file, which CICS uses to create additional navigation links for collections.
Main program
  • Uses the EXEC CICS GET CONTAINER command to obtain the parameters from the DFHATOMPARMS container.
  • Obtains the selector value from the ATMP_SELECTOR parameter. The selector value is the key for a record in FILEA that contains the data for the requested Atom entry. In FILEA, the key for the records is a unique customer number. The key for FILEA must be exactly six digits, and DFH0W2F1 does not pad the key value to the correct length. If CICS does not supply a selector value, the service routine reads the first record in the file and copies its key to the ATMP_SELECTOR parameter storage. The service routine is returning the records in increasing order of their key, as CICS does for KSDS files.
  • Saves the entity tag (Etag) value from the If-Match header, if an entity tag value was provided.
  • Obtains the HTTP method for the request. The service routine uses the HTTP method to determine the subsequent action:
    • For a GET request, the service routine reads the record whose key is equal to the selector value, and returns its contents as an Atom entry using the RETURN-FILE-CONTENT procedure.
    • For a PUT request, the service routine reads the record whose key is equal to the selector value, using a read for update function. It calculates the ETag value for the record that was just read, and compares it with the one that was received from the If-Match header. If these are not equal, the file is unlocked from the read for update, and the service returns an error response. If the ETags match, the service routine uses the PARSE-REQUEST-BODY procedure to parse the updated Atom entry that was supplied by the web client, and uses this data to update the record in FILEA. The file record is rewritten with a REWRITE function. The service routine then uses the RETURN-FILE-CONTENT procedure to return a copy of the updated Atom entry to the web client.
    • For a POST request, the service routine uses the PARSE-REQUEST-BODY procedure to parse the updated Atom entry that was supplied by the web client, and uses the data to write a new file record. The customer number that is provided by the web client in the POST request becomes the key value for the new file record, and the service routine returns an error if a record with that number already exists. The service routine then uses the RETURN-FILE-CONTENT procedure to return a copy of the new Atom entry to the web client.
    • For a DELETE request, the record whose key is equal to the selector value is deleted.
PARSE-REQUEST-BODY and XML-HANDLER procedures
In the PARSE-REQUEST-BODY procedure, the service routine uses an EXEC CICS GET CONTAINER command to get the content of the DFHREQUEST container, which is the Atom entry that was supplied by the web client in the body of a POST or PUT request. It then parses the Atom entry using the XML PARSE function.

The XML-HANDLER procedure analyzes the elements of the supplied Atom entry, and uses the XML stack to track whether or not each XML element is within the <atom:content> element in the supplied Atom entry ("IN-CONTENT" flag), and record the nesting level of each element. When an element is found that is "IN-CONTENT" and has a recognized name, the UPDATE-RECORD-FIELD procedure saves its data in the FILEA record. The service routine ignores metadata elements in the Atom entry that are outside the <atom:content> element, and also any elements within the <atom:content> element whose name it does not recognize, because it cannot store the data from these elements in the FILEA records.

The COBOL XML parser does not attempt rigorous analysis of XML namespace prefixes. If you are using this parser, the <atom:content> element in the supplied Atom entry must include the prefix "atom", and any XML elements within the content must not have namespace prefixes.

RETURN-FILE-CONTENT procedure
For GET, POST, and PUT requests, the RETURN-FILE-CONTENT procedure returns the data from a record in the FILEA file as the content of an Atom entry, and creates and returns a title and summary for the Atom entry. The procedure performs the following steps:
  • Places the data from the fields of the FILEA record into the prototype Atom entry content that was set up in the Working-Storage section. The resulting XML structure is placed into the DFHATOMCONTENT container with an EXEC CICS PUT CONTAINER command.
  • Completes the prototype Atom entry title and saves it in the DFHATOMTITLE container. A flag indicating this is set for the ATMP-OPTIONS-OUT parameter.
  • Creates a summary for the Atom entry and saves it in the DFHATOMSUMMARY container. A flag indicating this is set for the ATMP-OPTIONS-OUT parameter.
  • Uses the EXEC CICS BIF DIGEST command to produce an ETag for the FILEA record, and returns this value in the ATMP-ETAGVAL parameter in the DFHATOMPARMS container.
  • Calls
ADD-NAVIGATION-LINKS procedure
The ADD-NAVIGATION-LINKS procedure returns the selector values (that is, the key values) of the first, last, next, and previous records in the FILEA file. The selector values are saved in the temporary work area (TWA). CICS will use the selector values for creating additional navigation for Atom collection documents.

Prerequisites for DFH0W2F1

CICS supplies the components shown in the following table to run DFH0W2F1.

Table 1. Components to run DFH0W2F1
Component Purpose Location
URIMAP resource DFH$W2P1 Handles HTTP requests for an Atom feed using FILEA, with DFH0W2F1 as the service routine CICS group DFH$WEB2 or your copy
ATOMSERVICE resource DFH$W2P1 Names resources used to produce the Atom feed CICS group DFH$WEB2 or your copy
Atom configuration file dfh0w2f1.xml Provides metadata and structure for the Atom feed document and Atom entries USSHOME/samples/web2.0/atom
CICS provides sample URIMAP and ATOMSERVICE resources in the DFH$WEB2 group. The resources are both named DFH$W2P1. You can set up these resources in the same way as you set up the sample Atom collection, following the instructions in Atom feed sample programs. The URL for web client requests to access the FILEA sample as an Atom collection through DFH0W2F1 is 
http://host:port/atom/p/filea/feed
where:
  • host is the character host name, IPv4 address, or IPv6 address that is defined in the HOST attribute of the TCPIPSERVICE resource that you are using with this collection.
  • port is the port number that is defined in the PORTNUMBER attribute of the TCPIPSERVICE resource that you are using with this collection.

The ATOMSERVICE resource DFH$W2P1 names the Atom configuration file dfh0w2f1.xml, which provides metadata and structure for the Atom feed document and Atom entries. dfh0w2f1.xml is in the /samples/web2.0/ subdirectory of the root directory for CICS files on z/OS® UNIX, as specified by the CICS system initialization parameter USSHOME. The default value for USSHOME is /usr/lpp/cicsts/cicsts56 . The ATOMSERVICE resource DFH$W2P1 does not name an XML binding for the FILEA file, because FILEA does not contain any fields that can be used as metadata for Atom entries, so DFH0W2F1 does not make use of the <cics:fieldnames> element in the Atom configuration file.

Setting up DFH0W2F1

  1. Create and install an appropriate RDO definition for DFH0W2F1, which must specify EXECKEY(CICS).
  2. Create the FILEA VSAM file and install an appropriate RDO definition for it. An appropriate RDO definition is provided in the CICS-supplied sample RDO group DFH$FILA.
  3. Ensure that the FILEA file is enabled and open.