Creating an Atom category document

Create an Atom category document if you want to supply a long list of categories for a collection or to reuse the same list of categories for different collections. For short or unique lists of categories, there is little value in defining a separate category document; specify the categories in the Atom service document instead.

About this task

An Atom category document is stored in z/OS UNIX System Services. An Atom category document is an XML document, and the file has the .xml extension. You can create the file using any XML editor or text editor.

As for an Atom service document, you can choose whether to create your Atom category documents as Atom configuration files, or as files delivered by CICS Web Support static content delivery. Choose the same approach as you took for your Atom service document in Creating an Atom service document. CICS does not validate the content of an Atom category document.

Apart from the <cics:atomservice type="category"> root element, if you use it, an Atom category document in CICS uses only the standard elements defined in RFC 5023 The Atom Publishing Protocol. Consult that document if you need any further reference information.

The categories that you specify in a category document do not affect the way CICS behaves. CICS accepts client requests that specify a category that is not included in your document. For this reason, for a request where CICS handles the resource directly, do not use the fixed="yes" attribute in your <app:categories> element, which indicates that the server does not allow any other categories. If you are using a service routine to make changes to the resource, you may code your service routine to reject client requests on the basis of categories, and indicate this in your <app:categories> element.

Note that for data held in a resource, CICS supports only a single category for each Atom entry.

Procedure

If you want to define your Atom category document as an Atom configuration file, begin the document with the root element <cics:atomservice type="category">, and add the <app:categories> element as a child element.
```
<?xml version="1.0"?>
<cics:atomservice type="category">
 <app:categories>
 </app:categories>
</cics:atomservice>
```
If you do not want to define the Atom category document as an Atom configuration file, use the <app:categories> element as the root element, as follows:
```
<?xml version="1.0"?>
<app:categories>
</app:categories>
```
Do not use the optional scheme attribute, because CICS does not support it. For a request where CICS handles the resource directly, do not use the fixed="yes" attribute, because CICS does not provide any support for disallowing categories. When you omit the fixed attribute, a value of "no" is assumed. For a request where you are using a service routine to handle the resource, you may use the fixed="yes" attribute if your service routine rejects requests on the basis of categories.
Include the namespace declarations for the Atom XML namespace and the namespace for the Atom Publishing Protocol in the root element of the Atom category document; that is, either the <cics:atomservice> element or the <app:categories> element.
If you have used the <cics:atomservice> element as the root element, also include the namespace declaration for the CICS Atom XML namespace.
For example:
```
<?xml version="1.0"?>
<cics:atomservice type="category"
      xmlns:cics="http://www.ibm.com/xmlns/prod/cics/atom/atomservice"
      xmlns:atom="http://www.w3.org/2005/Atom"
      xmlns:app="http://www.w3.org/2007/app">
 <app:categories>
 </app:categories>
</cics:atomservice>
```
With the <app:categories> element as the root element, the declarations look like this:
```
<?xml version="1.0"?>
<app:categories
      xmlns:atom="http://www.w3.org/2005/Atom"
      xmlns:app="http://www.w3.org/2007/app">
</app:categories>
```
Add one or more <atom:category> elements as child elements of the <app:categories> element, and give each <atom:category> element a term attribute that specifies the name of the category.
For example:
```
 <app:categories>        
    <atom:category term="Events" /> 
    <atom:category term="Comments" />
 </app:categories>
```
CICS does not support the optional scheme and label attributes, so do not use these attributes.
Include the full URL for your category document in your Atom service document, by specifying the <app:categories> element with the href attribute in each applicable collection.
This example shows how to specify the <app:categories> element as a child of the <app:collection> element in an Atom service document:
```
  <app:collection 
      href="http://www.example.com/events/eventcol.atom"> 
         <atom:title>Events collection</atom:title>
      <app:categories href="http://www.example.com/cat/eventcol"/>
  </app:collection>
```

Example

This Atom category document is defined as an Atom configuration file, with the root element <cics:atomservice type="category">.

<?xml version="1.0"?>
<cics:atomservice type="category"
      xmlns:cics="http://www.ibm.com/xmlns/prod/cics/atom/atomservice"
      xmlns:atom="http://www.w3.org/2005/Atom"
      xmlns:app="http://www.w3.org/2007/app">
 <app:categories>       
    <atom:category term="Events" /> 
    <atom:category term="Comments" />
 </app:categories>
</cics:atomservice>

What to do next

Follow the instructions in either Delivering an Atom service or category document as an Atom configuration file or Delivering an Atom service or category document as a static response to set up the resource definitions to deliver your Atom category document to web clients.