<atom:entry> element

The <atom:feed> element in an Atom configuration file contains a single prototype <atom:entry> element. CICS® generates an Atom entry document by populating the child elements of this element with data supplied by the CICS resource described in the <cics:resource> element, repeating this process for as many Atom entries as the client requests.

Contained by:

<atom:feed> element

Child elements

The child elements of the <atom:entry> element are as defined by the Atom format specification in RFC 4287, except that CICS does not support the optional <atom:source> element. Some of the child elements are required for the Atom entry, and some of them are optional.

Most of the child elements of the <atom:entry> element contain default metadata to provide any data items for an individual Atom entry that are not supplied by the CICS resource or service routine.

If your CICS resource or service routine always supplies data for one of these child elements, you can typically omit it from the <atom:entry> element in your configuration file. The exception is the <atom:title> element, which CICS requires, although you may use an empty element if your Atom entries all have a title and no default would be suitable.
If your Atom entries are held in a resource whose records are lacking fields for some or all of the possible items of metadata, you can supply these items of metadata by specifying them in the Atom configuration file. When you provide metadata in the <atom:entry> element, CICS uses this metadata whenever the corresponding item of data is not supplied by the CICS resource or service routine.
You can omit any items of metadata that are optional, if you do not want to provide a default for these items.

Some of the child elements of the <atom:entry> element correspond to the attributes of the <cics:fieldnames> element. If a child element has a corresponding attribute in the <cics:fieldnames> element, CICS can deliver that item of data from the resource, or a service routine can deliver it, if it is present. If a child element has no corresponding attribute in the <cics:fieldnames> element, you can only specify it in the Atom configuration file.

RFC 4287 permits plain text, HTML, or XHTML content for child elements that are defined as "text constructs", such as the <atom:title> element. CICS only supports plain text content for these elements, so you cannot use a "type" attribute to specify an alternative content type. You must supply plain text content with no child elements. CICS does permit HTML, XHTML, and other text media types (such as XML) in the <atom:content> element as content for Atom entries, which you specify in the CICS resource that provides data for the Atom entries.

The child elements for the <atom:entry> element are as follows:

<app:edited>

The time when the Atom entry was last edited. This element applies only to Atom entries that are part of a collection, and in that case it is required (as a SHOULD requirement). You cannot specify the <app:edited> element in your prototype Atom entry in the configuration file. The element corresponds to the edited attribute of the <cics:fieldnames> element. If the CICS resource or service routine does not provide this data, CICS supplies the current date and time as a default. Although CICS supports the use of the <app:edited> element, for reasons of performance CICS does not automatically order Atom entries in a collection by this element when returning them to a client as a list. For more information about ordering Atom entries in a collection, see Sequence for Atom entries.

<atom:author>

The personal details of the principal author of the Atom element, which might be an individual person or an organization. You can have more than one <atom:author> element in the configuration file. The data is provided in child elements as follows:

<atom:name>: The name of the person. This child element is required if you are specifying the <atom:author> element, and CICS checks that you include it.
<atom:uri>: An URL associated with the person, such as a blog site or a company website. This child element is optional. CICS checks that you do not specify more than one <atom:uri> element in an <atom:author> element. CICS does not attempt to verify that the URL is valid, so you must ensure that it is correct.
<atom:email>: The e-mail address of the person. This child element is optional. CICS checks that you do not specify more than one <atom:email> element in an <atom:author> element.

The <atom:author> element is optional. If you choose not to specify the <atom:author> element anywhere in your configuration file, you must ensure that all the Atom entries in your resource include this data, to be compliant with RFC 4287.

<atom:category term=" ">

The name of a category that classifies the Atom entry. This element is optional. CICS only supports a single instance of this element. The term attribute specifies the name of the category. The element corresponds to the category attribute of the <cics:fieldnames> element, so you can omit the element if your CICS resource always provides suitable data.

<atom:content type=" " cics:resource=" " cics:type=" "/>

The content of the Atom entry. This element is required.

The <atom:content> element as specified in the configuration file does not contain any data, because CICS supplies the data from the resource when it issues the feed document. You must ensure that your resource provides content for every Atom entry. CICS does not support the delivery of Atom entries that contain no data, such as Atom entries that use the "src" attribute to reference remote content.

type=" ": The type attribute specifies the type of content that CICS expects for the Atom entry, which can be "text", "html", "xhtml", or an IANA media type. If this attribute is not present, CICS uses a default media type of "application/xml". As in RFC 4287, use the media type "text" for plain text instead of the IANA media type "text/plain", "html" instead of "text/html", and "xhtml" instead of "application/xhtml+xml". If your content is in any other format, specify the IANA media type that you would normally use for that format on the Internet. A listing of media types is available at http://www.iana.org/assignments/media-types/media-types.xhtml. Note that CICS does not provide support for nontext media types.
When CICS delivers Atom entries directly from your resource, the media type or the default must be appropriate for the data in the resource, because CICS labels the content with this media type when the Atom document is issued. When you use a service routine to provide content for the Atom entries, this media type or the default is supplied to the service routine. The service routine can override it and specify an alternative media type, or allow CICS to label the content with the media type from the Atom configuration file.
" cics:resource=" and " cics:type=" ": The attributes cics:resource and cics:type state the name and type of the CICS resource that provides the data for the Atom feed. The values of these attributes must match the values of the name and type attributes stated for the <cics:resource> element. For a description of the values of these attributes, see <cics:resource> element.

The <atom:content> element corresponds to the content and content_type attributes of the <cics:fieldnames> element.

<atom:contributor>

The personal details of a subsidiary author of the Atom entry. This element is optional. The data is provided in the <atom:name>, <atom:uri>, and <atom:email> child elements as in the <atom:feed> element. You cannot specify data for <atom:contributor> elements in individual resources, so the <cics:fieldnames> element has no corresponding attribute, and the data that you provide applies to all Atom entries. Because the data applies to all Atom entries, you might prefer to specify contributors under the <atom:feed> element.

<atom:id>

The unique identifier for the Atom entry. The Atom format specification requires one <atom:id> element for each Atom entry. Atom IDs for Atom entries explains the requirements for the use of Atom IDs.

CICS can generate tag URIs to use as unique Atom IDs for Atom entries. The tag URIs include the attributes that you specify in the <cics:authority> element in the Atom configuration file, the resource type and resource name that you specify in the <cics:resource> element, and the selector value for the individual Atom entry. If this format meets your needs, omit the <atom:id> element in the prototype Atom entry.

Instead of using the tag URI format that is generated by CICS, you may use the <atom:id> element in the prototype Atom entry to specify a prototype Atom ID in an alternative format. CICS appends the selector value or a suitable unique identifier to produce a unique Atom ID. If you use an alternative Atom ID format, make sure that the Atom IDs are unique and meet the requirements of the Atom format specification in RFC 4287.

<atom:link>

A standard URL that identifies an Atom entry and enables web clients to retrieve it. URLs for Atom feeds from CICS explains how to construct this URL.

For CICS, you must have a single <atom:link rel="self"> element as a child element of the <atom:entry> element. For an Atom entry in a collection, the Atom format specification requires a link relation of "edit" instead of "self", and CICS supplies this link relation automatically when sending out Atom entries in a collection. You must specify <atom:link rel="self"> in the Atom configuration file, whether the Atom entries are in an Atom feed or a collection.

In your Atom configuration file, specify the URL in an <atom:link rel="self"> element as a standard path that can be extended to apply to any Atom entry document. The beginning of the path must match the partial path that you stated in the URIMAP resource definition for the Atom feed or collection. The remainder of the standard path must be different from the complete path that you specified in the <atom:link rel="self"> element for the Atom feed. For example, if you specified /myatomfeed/* as the path component in the URIMAP resource definition, and <atom:link rel="self" href="/myatomfeed/feed.atom"> as the link for the whole Atom feed in the Atom configuration file, you could specify <atom:link rel="self" href="/myatomfeed/entries/"> as the standard path for Atom entries. The limits on URL length listed in URLs for CICS Web support apply also to URLs for Atom feeds.

When CICS returns an Atom entry document to the client, CICS appends the selector value for the Atom entry to this path to create a complete link.Selector value for Atom entries explains what the selector value is. You use the <cics:selector> element in the Atom configuration file to specify the way in which the selector value is appended to the path. When you select the default "segment" style or omit the element, CICS creates links such as <atom:link rel="self" href="/myatomfeed/entries/23">. The alternative "query" style produces a format that is compatible with applications developed for the CA8K SupportPac. You can also use the <cics:selector> element if you need to specify that your selector value is hexadecimal.

In the Atom configuration file, you may omit the scheme and host components of the URL, and specify only the path component. CICS adds the scheme and host components to the URL when it returns the Atom feed or Atom entry document to the client, to comply with the Atom format specification.

<atom:published>

The time when the Atom entry was first created or published. This element is optional. This element corresponds to the published attribute of the <cics:fieldnames> element. If the CICS resource does not provide this data, CICS supplies the current date and time as a default. You can specify the <atom:published> element in your Atom configuration file with an alternative default timestamp in the XML dateTime format, as described in RFC 3339.

<atom:rights>

A text string that contains the claimed intellectual property rights, such as copyright. CICS only supports plain text for this element. This element is optional, and if it is not provided, the <atom:rights> element for the Atom feed applies. The <cics:fieldnames> element has no corresponding attribute, so the data that you provide applies to all Atom entries.

<atom:summary>

A short description of the content of the Atom entry. CICS only supports plain text for summaries. This element corresponds to the summary attribute of the <cics:fieldnames> element. This element is required if the content of the Atom entry is not text, HTML, XHTML or XML, so if you plan to provide any content that does not fit these categories, and the CICS resource does not always provide a summary, use this element to provide a default summary. You can also use this element if the CICS resource does not provide a summary and you want the same summary to appear on all your Atom entries. Otherwise, you can omit the element. CICS checks that you do not specify more than one <atom:summary> element for the Atom entry.

<atom:title>

The title for the Atom entry. CICS only supports plain text for titles. This element corresponds to the title attribute of the <cics:fieldnames> element. You must include an <atom:title> element in the prototype Atom entry, even if your CICS resource always provides a title for Atom entries, to comply with RFC 4287. Use a suitable default title that could apply to any of your Atom entries, or use an empty element if your Atom entries all have a title and no default would be suitable. CICS checks that you do not specify more than one <atom:title> element.

<atom:updated>

The time when the Atom entry was last updated in a significant way. This element is required by the Atom specification, but you cannot specify it in the prototype Atom entry in your Atom configuration file. The element corresponds to the updated attribute of the <cics:fieldnames> element. If the CICS resource does not provide this data, CICS supplies the current date and time as a default.

Example

      <atom:entry>
          <atom:title>An entry from my feed</atom:title>
          <atom:summary>DEFAULT --- This is the default summary</atom:summary>
          <atom:link rel="self" href="/web20/sample_atom_feed/entry" /> 
          <atom:author>
                <atom:name>Joe Bloggs</atom:name>
                <atom:uri>http://myzos.example.com/JBloggs/</atom:uri>
                <atom:email>JBloggs@uk.ibm.com</atom:email>
          </atom:author>
          <atom:contributor>
                <atom:name>John Doe</atom:name>
          </atom:contributor>
          <atom:category term="Comments" />
          <atom:published>2008-12-02T15:41:00</atom:published>
          <atom:content type="text" cics:resource="WB20TSQ" cics:type="tsqueue" />
       </atom:entry>