Input-output parameters in DFHATOMPARMS container

Each of the input-output parameters in the DFHATOMPARMS container is the address of a triple word containing a pointer to an area, the current length of the data in the area, and the maximum length of the area.

ATMP_ATOMID

The Atom ID for the entry. An Atom ID is a unique identifier for the Atom entry. For more information about the format of Atom IDs, see Atom IDs for Atom entries.

On input, CICS uses this area to send the prototype Atom ID for the entry to the service routine. You determine the format of the prototype Atom ID by including either the <cics:authority> element or the <atom:id> element in the Atom configuration file, depending on whether you want to use the tag URI format or an alternative format to produce a unique identifier. CICS ignores Atom IDs that are supplied by web clients, and does not pass these to the service routine.

The Atom format specification in RFC 4287 recommends that you store an Atom ID in the resource record for the Atom entry. For a POST request, if your resource can store Atom IDs, your service routine must complete the prototype Atom ID by appending the selector value for the Atom entry, as specified in the ATMP_SELECTOR parameter, and then store the complete Atom ID in the appropriate field in the resource record, as specified in the ATMP_ID_FLD parameter. If you prefer, your service routine can ignore the prototype Atom ID and substitute its own valid Atom ID for the Atom entry. The service routine can use the values of the ATMP_TAG_AUTHORITY and ATMP_TAG_DATE parameters as input to construct an Atom ID.

Note that if you are using the tag URI format, the resulting Atom ID is unique for Atom entries provided by a user-written service routine that deals with a single Atom feed, but it is not unique if the user-written service routine provides more than one feed. If your user-written service routine provides multiple feeds, either choose an alternative format for your Atom IDs, or use a different authority name or date in the <cics:authority> element of the Atom configuration file for each of the feeds.

On output, the service routine must use the ATMP_ATOMID parameter as follows:

• If you have stored a complete Atom ID in the resource record for the Atom entry, the service routine must return the complete Atom ID from the field in the resource record, as specified in the ATMP_ID_FLD parameter, followed by the length of the Atom ID.
• If your resource does not store Atom IDs, the service routine must set the current length of the data for the ATMP_ATOMID parameter to zero. In this case, CICS appends the selector value to the prototype Atom ID to produce a complete Atom ID.

ATMP_ETAGVAL

An entity tag (or Etag) value for the selected resource record. To produce an entity tag, a service routine can use the EXEC CICS BIF DIGEST command to calculate the SHA-1 digest of the record, or use another suitable method to produce an entity tag that complies with the HTTP/1.1 protocol requirements.

On input, CICS uses the ATMP_ETAGVAL parameter to provide any entity tag for the Atom entry to the service routine. When a web client makes a PUT or DELETE request to edit an Atom entry, CICS requires the client to supply an If-Match HTTP header on the request containing an entity tag. If CICS provides an entity tag using this parameter, the service routine must calculate the entity tag for the existing record and compare it to the web client's entity tag. If the tags do not match, indicating that the entry has been changed by another agent, the service routine must reject the request with the response code atmp_resp_etag_no_match. A web client might supply an asterisk in place of an entity tag to indicate that the entry should be edited or deleted even if it has been changed by another agent, and the service routine should comply with this request.

On output, the service routine must use the ATMP_ETAGVAL parameter as follows:

• Entity tags are not used for entries in an Atom feed. If the current Atom entry is part of an Atom feed, the service routine must set the current length of the data to zero.
• CICS requires entity tags for entries in a collection. If the current Atom entry is part of a collection, the service routine must calculate and return the entity tag. Do not store entity tags in resource records; calculate them when they are needed.

ATMP_PUBLISHED

The service routine can use this parameter to return the date and time at which the returned Atom entry was first published. "Published" means the point when the data was first created or first made available. If your resource does not store this data, the service routine must indicate this by setting the current length of the data to zero, and in this case CICS provides the default of the current time. If the service routine returns a date and time stamp, it must be in the RFC 3339 format, also known as the XML dateTime datatype. You can use the EXEC CICS FORMATTIME command to provide a date and time stamp in this format, or if your service routine can use the TRANSFORM DATATOXML command, you can convert a CICS ABSTIME value into a date and time stamp in this format.

ATMP_UPDATED

The service routine can use this parameter to return the date and time at which the returned Atom entry was last updated. "Updated" means a point when the data was changed in a way that you consider to be significant. If your resource does not store this data, the service routine must indicate this by setting the current length of the data to zero, and in this case CICS provides the default of the current time. If the service routine returns a date and time stamp, it must be in the RFC 3339 format.

ATMP_EDITED

The service routine can use this parameter to return the date and time at which the returned Atom entry was last edited. If your resource does not store this data, the service routine must indicate this by setting the current length of the data to zero, and in this case CICS provides the default of the current time. If the service routine returns a date and time stamp, it must be in the RFC 3339 format.

ATMP_SELECTOR

A selector value for the Atom entry that the service routine must provide. Selector value for Atom entries explains what a selector value is.

• When a client is making a general request for a feed, on input, CICS sends a null value for the ATMP_SELECTOR parameter, and the input parameter ATMP_ATOMTYPE has the value "feed". On receiving this combination of values, the service routine must take the following actions:
  • Return the data for the most recent Atom entry that was added to the feed.
  • Use the ATMP_SELECTOR parameter to return a selector value identifying that entry. If your resource does not hold Atom IDs for entries, CICS uses this selector value in the generated Atom ID for the entry.
  • Use the ATMP_NEXTSEL parameter to return a selector value for the next entry in the feed.
• When CICS needs a second or subsequent Atom entry from a feed to complete a client request, or a client has requested a feed document containing a specific range of Atom entries, on input, CICS uses the ATMP_SELECTOR parameter to send a selector value for one of the Atom entries in the feed document, and the input parameter ATMP_ATOMTYPE has the value "feed". On receiving this combination of values, the service routine must take the following actions:
  • Return the data for the Atom entry that is represented by the selector value.
  • Do not change the data or length that CICS supplied for the ATMP_SELECTOR parameter.
  • Use the ATMP_NEXTSEL parameter to return a selector value for the next entry in the feed.
• When a client is requesting a specific entry from a feed, CICS uses the ATMP_SELECTOR parameter to send the selector value extracted from the URL for the entry, and the input parameter ATMP_ATOMTYPE has the value "entry". On receiving this combination of values, the service routine must take the following actions:
  • Return the data for the Atom entry that is represented by the selector value.
  • Do not change the data or length that CICS supplied for the ATMP_SELECTOR parameter.
  • For the ATMP_NEXTSEL parameter, return a null value by setting the current length of the data to zero.

Note: For a collection, CICS uses the value "collection" for the ATMP_ATOMTYPE parameter in the situations where the value "feed" would be used for an Atom feed. The value "entry" is the same for an entry from a collection or an entry from an Atom feed.

ATMP_NEXTSEL

The service routine must use this parameter to return a selector value for the next Atom entry that is available, if any. Sequence for Atom entries explains the order in which you should return your Atom entries.

This value must be supplied whether the service routine is handling a feed or a collection. It is not required when the client requests a single specific entry (with the value "entry" for ATMP_ATOMTYPE), or when no more data is available to provide Atom entries. When the value is not required, the service routine must return a null value for this parameter by setting the current length of the data to zero.

CICS uses the value supplied by the service routine to request further Atom entries from the service routine to complete the Atom document. If the Atom document is complete, CICS uses this value to produce the <atom:link rel="next"> link in the Atom document, which web clients can use to retrieve the next window of Atom entries from the feed or the next partial list of Atom entries from the collection.

ATMP_PREVSEL

A service routine that is handling a collection must use this parameter to return a selector value for the previous Atom entry in the collection, if any. Sequence for Atom entries explains the order in which you should return your Atom entries.

This value must be supplied when the ATMP_ATOMTYPE parameter has the value "collection". It is not required when the client requests a single specific entry (with the value "entry" for ATMP_ATOMTYPE), or when there is no previous Atom entry. When the value is not required, the service routine must return a null value for this parameter by setting the current length of the data to zero.

When the Atom document is complete, CICS uses this value to carry out a chain of requests to the service routine to produce the <atom:link rel="previous"> link in the Atom document, which web clients can use to retrieve the previous partial list of Atom entries from the collection.

This value is not required from a service routine that is handling an ordinary Atom feed. You may specify it if the <atom:link rel="previous"> link would be useful to your web clients in order to retrieve the previous window of Atom entries from the feed. However, the processing to produce this link increases response times, so only specify this value for a feed if your web clients are set up to use this form of navigation.

ATMP_FIRSTSEL

A service routine that is handling a collection must use this parameter to return a selector value for the first Atom entry in the collection. Selector value for Atom entries explains the order in which you should return your Atom entries.

This value must be supplied when the ATMP_ATOMTYPE parameter has the value "collection". On subsequent calls relating to the same web client request, CICS uses the ATMP_FIRSTSEL parameter to supply this selector value to the service routine, so the service routine does not need to provide it again.

The value is not required when the client requests a single specific entry (with the value "entry" for ATMP_ATOMTYPE). When the value is not required, the service routine must return a null value for this parameter by setting the current length of the data to zero.

When the Atom document is complete, CICS uses this value to produce the <atom:link rel="first"> link in the Atom document, which web clients can use to retrieve the first (newest) partial list of Atom entries from the collection.

This value is not required from a service routine that is handling an ordinary Atom feed. You may specify it if the <atom:link rel="first"> link would be useful to your web clients in order to retrieve the first (newest) window of Atom entries from the feed. CICS does not carry out any additional processing to produce this link.

ATMP_LASTSEL

A service routine that is handling a collection must use this parameter to return a selector value for the last Atom entry in the collection. Sequence for Atom entries explains the order in which you should return your Atom entries.

This value must be supplied when the ATMP_ATOMTYPE parameter has the value "collection". On subsequent calls relating to the same web client request, CICS uses the ATMP_LASTSEL parameter to supply this selector value to the service routine, so the service routine does not need to provide it again.

The value is not required when the client requests a single specific entry (with the value "entry" for ATMP_ATOMTYPE). When the value is not required, the service routine must return a null value for this parameter by setting the current length of the data to zero.

When the Atom document is complete, CICS uses this value to produce the <atom:link rel="last"> link in the Atom document, which web clients can use to retrieve the last (oldest) partial list of Atom entries from the collection. CICS issues this last partial list containing only a single entry, that is, the last entry in the feed. web clients can use the <atom:link rel="previous"> links to retrieve all the previous partial lists.

This value is not required from a service routine that is handling an ordinary Atom feed. You may specify it if the <atom:link rel="last"> link would be useful to your web clients in order to retrieve the last (oldest) Atom entry from the feed. CICS does not carry out any additional processing to produce this link.