Date and time stamps for Atom entries

The metadata for an Atom entry can include date and time stamps to show when the Atom entry was first published, when it was last updated, and when it was last edited.

The Atom Syndication Format and Atom Publishing Protocol define these date and time stamps as follows:

<atom:published>: The date and time when the Atom entry was first created or first made available. For example, if your Atom feed uses records in a database to provide the data for the Atom entries, this date and time would be the point when the record containing the data was added to the database.
<atom:updated>: The date and time when the Atom entry was last changed in a way that you consider to be significant. For example, you might record this date and time stamp if the value of a field in the record in the database was changed.
<app:edited>: The date and time when the Atom entry was last edited. This date and time stamp applies only to Atom entries that are part of a collection, and in that case it is required (as a SHOULD requirement).

If you are setting up a new resource to contain data for Atom entries, you can include fields in the records in the resource to hold the date and time stamps. A service routine can return this data by overwriting the ATMP_PUBLISHED, ATMP_UPDATED , and ATMP_EDITED parameters in the DFHATOMPARMS container. If you are using the resource handling parameters in the DFHATOMPARMS container, the ATMP_PUBLISHED_FLD, ATMP_UPDATED_FLD, and ATMP_EDITED_FLD parameters have the name and length of the relevant field in the records in your resource.

If the records in your resource do not contain any fields to hold metadata, CICS provides the current date and time as a default timestamp for all of these elements. In this case, a service routine returns spaces for the relevant parameters in the DHFATOMPARMS container. For the <atom:published> element, you can specify an alternative default timestamp in the prototype Atom entry in your Atom configuration file. You cannot specify alternative defaults for the <atom:updated> and <app:edited> elements in the prototype Atom entry in your Atom configuration file.

The date and time stamps that you use for these elements must be in the RFC 3339 format, also known as the XML dateTime datatype. RFC 3339, Date and Time on the Internet: Timestamps , is a format specification for date and time stamps in UTC (Coordinated Universal Time), taken from the ISO 8601 standard. You can read this specification at https://www.ietf.org/rfc/rfc3339.txt.

Use the EXEC CICS ASKTIME command followed by the EXEC CICS FORMATTIME command to produce a date and time stamp in the RFC 3339 format. Alternatively, if your service routine can use the TRANSFORM DATATOXML command, you can convert a CICS ABSTIME value held in your resource record into a date and time stamp in this format.

If you are populating a record in your resource with data for a new Atom entry supplied by a web client (a POST request), or editing the fields in a record in your resource at the request of a web client (a PUT request), the web client might provide date and time stamps in the <atom:updated>, <atom:published>, or <app:edited> elements. In the case of the <atom:updated> and <app:edited> elements, it is advisable to ignore these and generate a new date and time stamp to ensure accuracy and validity. For a PUT request in particular, the date and time stamps might just be the date and time stamps from the existing record in the resource, returned unchanged.