Creating a CICS resource to store Atom entries

To store data as Atom entries, create a file or temporary storage queue in CICS®, and write a language structure in COBOL, C, C++, or PL/I to explain its structure.

1. Decide whether to use a temporary storage queue or a file as the resource to store the data for your Atom entries.
   • A temporary storage queue is suitable if you are experimenting with Atom feeds in CICS, because you do not have to define a temporary storage queue to CICS before you use it, although you will have to set up a CICS resource definition if you want to apply security measures. It is also suitable for an Atom feed where the Atom entries are not of long-term interest; for example, if you are issuing alerts for events in an application.
   • A file takes longer to set up than a temporary storage queue, because you must define a file to CICS before you can use it, and it normally requires a physical data set. However, a file provides suitable long-term storage for any Atom feed, including a feed that you might want to set up as an editable collection. A file that holds Atom entries must have a unique key for the records, and you cannot use an alternate index file that has been defined with the NONUNIQUEKEY attribute. You can use any type of VSAM file to hold Atom entries, but note that ESDS (entry-sequenced data set) files are not a good choice for a feed that you might want to set up as an editable collection, for the reasons mentioned in ESDS files with Atom feeds. You cannot use a BDAM file.
2. Plan the content of the records in your file or temporary storage queue.
   The content of the Atom entry is the only item that CICS requires in your records, because you can specify all the metadata in the Atom configuration file. However, when you are setting up a dedicated file or temporary storage queue to contain Atom entries, you can include fields for metadata in the records, which you can use to provide metadata specific to each Atom entry.
   The following list summarizes the items of data that you can include as fields in your records and whether they are required or optional:

   Atom ID

   A unique identifier for the Atom entry. For more information about the format of Atom IDs, see Atom IDs for Atom entries.

   Atom entries must have a unique Atom ID. CICS can generate a unique Atom ID for each entry when it serves the Atom feed, using information that you specify in the Atom configuration file. An Atom ID created by CICS remains the same for the lifetime of the Atom entry as long as you do not change the name of the file or temporary storage queue, change the relevant information in the Atom configuration file, or move the Atom entry to a different resource. You therefore do not have to include a field in your records to store the Atom ID.

   However, to comply fully with the Atom format, an Atom ID must remain with the entry if the entry is reused or moved to another location. If you think that you might use your Atom entries anywhere other than in this file or temporary storage queue, or if you just prefer to follow the recommendation in RFC 4287 that an Atom ID should be stored with the entry, include a field in your records to hold the Atom ID. If you are storing your Atom entries in a file, this field can be the unique key for the records.

   Author's details

   The personal name, email address, and website of the principal author of the Atom entry, in three separate fields. You must supply an author name either for the Atom feed or for all the Atom entries, but the other fields are optional. If your Atom entries have different authors, include a field in your records for the name, and fields for other details if you want. If the name and other details of the author are the same for all your Atom entries, specify the name and details in the Atom configuration file instead.

   Category

   A category term that classifies the entry. This field is optional. If you plan to set up this Atom feed as an editable collection, and to use categories to describe your collection, include this field. If you do not plan to set up this feed as a collection, you can still include the field if it might be helpful to consumers of your feed.

   Content

   The entire content to be published in the Atom entry. CICS requires content for every Atom entry. Your content can be plain text, or HTML, XHTML, XML, or another text media type. CICS does not support nontext content, or Atom entries with no content. If you are including any fields for metadata, you must have a field, or a substructure of nested fields in the record, that holds the content. If you are not including any fields for metadata, CICS publishes the whole of the record from the file or temporary storage queue as the content of the entry.

   Content type

   The media type for the content of the Atom entry, such as text or XML. This field is optional. If all your Atom entries have the same type of content, you can specify the media type in the Atom configuration file instead.

   Date last edited

   The time stamp that indicates when the record was last edited. You can use time stamps in the XML dateTime format, as described in RFC 3339, or a CICS ABSTIME value. For more information about date and time stamps, see Date and time stamps for Atom entries. If you plan to set up this Atom feed as an editable collection, including this field enables you to return the Atom entries according to when they were last edited, which is recommended by the Atom Publishing Protocol for a collection. If you do not plan to set up this feed as a collection, do not include this field.

   Date first published

   The time stamp or ABSTIME value that indicates when the record was first created or published as an Atom entry. This field is optional. If you think that it might be helpful to consumers of your feed, include the field.

   Title

   The title for the Atom entry. CICS only supports plain text for titles. A title is required for each Atom entry, so you normally need to include this field. If all your Atom entries have the same title, you can specify this title in the Atom configuration file instead.

   Summary

   A summary of the Atom entry. CICS only supports plain text for summaries. This field is optional unless the content of the entry is a nontext media type, in which case a summary is required. CICS does not provide any support for nontext content in Atom entries.

   Date last updated

   The time stamp or ABSTIME value that indicates when the record was last updated. An updated time stamp is required for each Atom entry, so you normally need to include this field. If you cannot include this time stamp or ABSTIME value in your file or temporary storage queue, you can omit the field and CICS can supply the current date and time when it issues the entry in an Atom feed document, or a suitable alternative default that you specify in the Atom configuration file.

3. Write a language structure, or copybook, in COBOL, C, C++, or PL/I for your file or temporary storage queue. A language structure describes the fields in a record in your file or temporary storage queue, stating the name, content type, and length of each field in the order in which they appear.
   If you plan to create records in your file or temporary storage queue using an application in COBOL, C, C++, or PL/I, the application uses this language structure to write to the file or temporary storage queue.
   You also need this language structure to produce an XML binding for the file or temporary storage queue, so it is required even if your application is in a different language, or if you are not using an application, for example, if you are experimenting with Atom feeds in CICS and your record structure is simple enough that you can use the CECI transaction to write to the file or temporary storage queue.
   Note: Make sure that fields that are used to provide metadata for Atom entries are not nested in your language structure. The metadata fields in your record must all be listed in your language structure at the same level. You may use structures of nested fields within the field that provides the content for the Atom entry.
   Store your language structure in a partitioned data set that has a fixed record length of 80 bytes.
   This example COBOL language structure declares alphanumeric fields of appropriate lengths to contain the data for each element:

         ******************************************************************
         * Name: SAMPBIND.cob                                             *
         *                                                                *
         *                                                                *
         * This is a COBOL copy book to describe the data record.         *
         * You can generate a binding file from this.                     *
         *                                                                *
         ******************************************************************
   
               03 TITLE-FIELD                        PIC X(50).
               03 SUMMARY-FIELD                      PIC X(500).
               03 ATOMID-FIELD                       PIC X(20).
               03 CONTENT-FIELD                      PIC X(500).
               03 AUTHOR-NAME-FIELD                  PIC X(30).
               03 AUTHOR-EMAIL-FIELD                 PIC X(256).
               03 AUTHOR-URI-FIELD                   PIC X(256).
               03 EDITED-FIELD                       PIC X(25).
               03 UPDATED-FIELD                      PIC X(25).
               03 PUBLISHED-FIELD                    PIC X(25).
               03 CATEGORY-FIELD                     PIC X(20).

4. Use your language structure as input to the CICS XML assistant to create an XML binding, following the steps in Generating mappings from language structures.
5. If you have decided to use a file to store your Atom entries:
   1. Set up a suitable VSAM data set, following the procedures in VSAM data sets.
   2. Define the file to CICS by creating and installing a FILE resource definition, using the information in FILE resource definitions.
6. If you have decided to use a temporary storage queue to store your Atom entries, and you want to specify security and recovery settings for it, define a temporary storage model (TSMODEL) using the information in TSMODEL resource definitions.