Atom IDs for Atom entries

Each Atom entry has a unique Atom ID that must remain the same for the lifetime of the Atom entry.

The Atom ID for an Atom entry is specified in the <atom:id> element. It must be in the form of a valid Internationalized Resource Identifier (IRI), but it does not need to relate to a real resource location.

Tag URIs

CICS can generate a unique Atom ID for each Atom entry in the tag URI format when it serves the Atom feed, using information that you specify in the <cics:authority> element in the Atom configuration file. The tag URI scheme is described in RFC 4151, The 'tag' URI Scheme.

To produce the tag URI for the Atom ID of an Atom entry, CICS uses the following items in order:

A scheme of "tag"
An authority name and date that you specify in the <cics:authority> element in the Atom configuration file
A specific consisting of the resource type and resource name that you specify in the <cics:resource> element in the Atom configuration file, and the selector value for the individual Atom entry

The authority name and date are separated by a comma, and the other elements are separated by a colon. An example of a tag URI produced by CICS is as follows:

tag:example.com,2009-01-08:tsqueue:WB20TSQ:23

The authority name in the tag URI is a domain name or email address that is registered to you or to your company, and the date is a date on which the authority name was owned by you or your company. cics:authority element has details of the requirements for the authority name and date.

For an Atom feed where CICS obtains data directly from a file or temporary storage queue, the resource type and resource name are those of the file or temporary storage queue. For an Atom feed where a user-written service routine provides the data, the resource type and resource name are those of the service routine.

The tag URIs that CICS produces as Atom IDs have the following characteristics:

The Atom ID remains the same for the lifetime of each Atom entry, as long as you do not change the name of the file, temporary storage queue, or service routine, change the relevant information in the Atom configuration file, or move the Atom entry to a different resource.
The Atom ID remains the same if the same resource is served in the same way from a different CICS region.
The Atom ID changes if you rename the file, temporary storage queue, or service routine. To be compliant with the Atom format, if you rename a resource, you must not continue to serve it as the same Atom feed (with the same URL), because its Atom IDs are different.
The Atom ID is unique within a CICS region, but it is not guaranteed to be unique across different CICS regions. In the situation where you want to set up Atom feeds from resources that have the same name and type but are in different CICS regions, you can specify a different authority name or a different date in the <cics:authority> element of the Atom configuration file for each of the feeds. Tag URIs that have different dates are not equivalent to each other, even if all the other information is the same.
The 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.

Alternative formats for Atom IDs

Instead of using the tag URI format that is generated by CICS, you may specify an alternative format for your Atom IDs using the <atom:id> element for the prototype Atom entry in the Atom configuration file. CICS appends the selector value to your alternative format, to produce a unique Atom ID for each Atom entry.

If you use an alternative Atom ID format, make sure that the resulting Atom IDs are unique and meet the requirements of the Atom format specification in RFC 4287.

To ensure correct formatting, CICS ignores any Atom IDs that are supplied by web clients, and instead uses the format that you specify in the Atom configuration file for the feed.

Storing Atom IDs

Because CICS can produce the same Atom ID for an Atom entry each time it serves the Atom entry, it is not essential to store the Atom ID with the Atom entry. This function enables you to provide Atom entry data from a resource that does not contain fields to store metadata, provided that you keep the Atom IDs the same and do not change the Atom ID in the configuration file, move the Atom entry to a different resource, or, for tag URIs, change the name of the resource or service routine.

However, RFC 4287 recommends that an Atom ID should be stored with the Atom entry. If you are able to store Atom IDs in the resource that holds the data for your Atom entries, you can follow this recommendation. If you are storing your Atom entries in a file, this field can be the unique key for the records. CICS, or your service routine, stores a complete Atom ID for the Atom entry in the field, and an Atom ID stored with an Atom entry can differ from and override the Atom ID that CICS would generate for that Atom entry.

For a service routine, CICS uses the ATMP_ATOMID parameter to send a prototype Atom ID for the Atom entry, using the information that you specified in either the <cics:authority> element or the <atom:id> element in the Atom configuration file. To produce a complete Atom ID, your service routine can either complete the prototype Atom ID by appending the selector value, or ignore it and substitute its own valid Atom ID. For example, you could generate a URI with the urn:uuid scheme using a hexadecimal Universally Unique Identifier (UUID), as described in RFC 4122, A Universally Unique IDentifier (UUID) URN Namespace. The service routine can store the Atom ID in the resource record, using the field named in the ATMP_ID_FLD parameter, and then return it using the ATMP_ATOMID parameter.

To ensure accuracy, CICS ignores Atom IDs that are supplied by web clients, and does not store these in the records in a file or temporary storage queue, or pass them to a service routine.

RFC 4287 requires that the Atom ID remain with the Atom entry if the entry is reused or moved to another location. If you store Atom IDs with your Atom entries, you can move the Atom entries to another location and still comply with this requirement. If you do not store Atom IDs with your Atom entries, do not move the Atom entry to another location.

Atom IDs for Atom feeds

An Atom feed also has a unique identifier. If you use the <cics:authority> element in the Atom configuration file to make CICS generate tag URIs as Atom IDs, CICS generates an Atom ID for the Atom feed in the same format as for the Atom entries, but without the selector value or unique identifier that is appended for the Atom entries. For example:

tag:example.com,2009-01-08:tsqueue:WB20TSQ

If you prefer an alternative Atom ID format, you can use the <atom:id> element for the Atom feed to specify a complete Atom ID for the Atom feed. Make sure that the Atom ID is unique and meets the requirements of the Atom format specification in RFC 4287.