Tutorial: Creating an Atom feed from structured data in a temporary storage queue

Follow this tutorial to understand how to create an Atom feed from structured data in a temporary storage queue.

Before you begin

You must complete Tutorial: Creating an Atom feed from unstructured data in a temporary storage queue before trying this tutorial.

About this task

In this tutorial, you can create a read-only Atom feed from a temporary storage queue that contains structured data for three Atom entries. The temporary storage queue records are described by the language structure DFH0W2TC. The copybook is located in SDFHSAMP and is as follows:

02		name			PIC(20)
02		val			PIC(20)
02		description		PIC(100)

In the first Atom feed scenario, these three fields appeared in a single Atom entry as unstructured data. In this scenario, you can structure the data in the XML.

This scenario does not use security. However, when you set up your own Atom feeds, use basic authentication to protect your Atom feeds and data.

Procedure

Use the language structure as input to the XML assistant job, DFHLS2SC.
1. Copy the TSQTEXT.jcl file from the samples/web2.0/atom directory to a suitable data set to edit the file.
  The sample JCL contains all of the parameters that are required to run the job.
2. Edit the values of the existing parameters and add additional parameters as required.
  The sample JCL has the following parameters:
```
//DFHLS2SC EXEC DFHLS2SC
//INPUT.SYSUT1 DD *
MAPPING-LEVEL=3.0
CCSID=1047
DATA-TRUNCATION=ENABLED
LANG=COBOL
PDSLIB=//PATH.TO.PDS.THAT.CONTAINS.THE.RECORD.COPYBOOK
PDSMEM=RECORD
XSDBIND=/tmp/tsqText.xsdbind
NAMESPACE=https://www.ibm.com/xmlns/prod/cics/atom/text
LOGFILE=/tmp/ls2sc.log
SCHEMA=/tmp/tsqText.xsd
*/
```
  - The sample specifies the latest mapping level. Use this mapping level to set additional parameters that control how CICS handles the data; for example, the formats of time stamps and data truncation.
  - If you want to run the sample in a different language, change the value for CCSID.
  - Change the value of DATA-TRUNCATION to DISABLED.
  - Change the value of PDSLIB to the location of SDFHSAMP in your CICS region.
  - Change the value of PDSMEM to DFH0W2TC.
  - Change the XSDBIND and SCHEMA parameters to write the XML binding and schema to a suitable zFS directory. CICS must have write access to this directory.
  All the parameters are explained in DFHLS2SC.
3. Submit the job.
The XML assistant generates an XML binding and a schema in the z/OS UNIX directory that you specified.

Edit the uss_directory/atomtxt1.xml file using an XML editor, where uss_directory is the location of the Atom configuration file from the first Atom feed scenario.

<?xml version="1.0"?>
  <cics:atomservice type="feed"
       xmlns:cics="https://www.ibm.com/xmlns/prod/cics/atom/atomservice"
       xmlns:atom="http://www.w3.org/2005/Atom">
     <cics:feed>
       <cics:resource name="DFHFEEDQ" type="tsqueue">
           <cics:bind root="RECORD"/> A 
       </cics:resource>
       <cics:authority name="example.com" date="2011-10-29"/> B 
       <cics:selector style="segment"/>
     </cics:feed>
     <atom:feed>
       <atom:link rel="self" href="/atom/scenario/tsq/dfhfeedq/feed"/>
       <atom:title>Sample CICS TS queue for unstructured data</atom:title> C 
       <atom:entry>
          <atom:link rel="self" href="/atom/scenario/tsq/dfhfeedq"/>
          <atom:title>TS queue unstructured record</atom:title> D 
          <atom:content cics:resource="DFHFEEDQ" cics:type="tsqueue"/>
       </atom:entry>
     </atom:feed>
  </cics:atomservice>

Change the value of the root attribute to DFH0W2TC to match the name of the copybook. This value matches the local name of the root XML element in the XML binding.
Change the date attribute to the current date, maintaining the same format.
Change the description of the feed to Sample CICS TS queue for structured data.
Change the description of the entry to TS queue structured record.

Disable and discard the ATOMSERVICE resource, ATOMTXT1.
Edit the ATOMSERVICE resource definition to change the BINDFILE attribute to point to the XML binding that you generated.
Install the ATOMSERVICE resource in your CICS region.
Disable the URIMAP resource, ATOM1.
Edit the URIMAP resource to use the ATOMTXT1 ATOMSERVICE resource and reinstall the URIMAP in the CICS region.

Enter the Atom feed URL http://host:port/atom/scenario/tsq/dfhfeedq/feed in your feed reader or a Web browser that supports feeds.

host is the character host name, IPv4 address, or IPv6 address that is defined in the HOST attribute of the TCPIPSERVICE resource that you are using with the sample Atom feed.
port is the port number that is defined in the PORTNUMBER attribute of the TCPIPSERVICE resource that you are using with the sample Atom feed.

In a Web browser, the Atom feed might appear as follows:

Screen capture of a Web browser showing the sample structured data with three records.

You can view the page source to see the XML for the feed:

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<generator uri="https://www.ibm.com/cics/" version="6.6.0">CICS Transaction Server Version 4.1.0</generator>
<link rel="self" href="http://host:port/atom/scenario/tsq/dfhfeedq/feed"/>
<id>tag:example.com,2011-12-11:tsqueue:DFHFEEDQ</id>
<title>Sample CICS tsqueue for structured data</title>
<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
<link rel="first" href="http://host:port/atom/scenario/tsq/dfhfeedq/feed/3"/>
<link rel="last" href="http://host:port/atom/scenario/tsq/dfhfeedq/feed/1"/>
<updated>2011-12-14T13:05:38+00:00</updated>
<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
<entry>
<link rel="self" href="http://host:port/atom/scenario/tsq/dfhfeedq/3"/>

<id>tag:example.com,2011-12-11:tsqueue:DFHFEEDQ:3</id>
<title>TS queue structured record 3</title>
<updated>2011-12-14T13:05:38+00:00</updated>
<published>2011-12-14T13:05:38+00:00</published>
<content type="application/xml"><DFH0W2TC xmlns="https://www.ibm.com/xmlns/prod/cics/atom/text"><name>Name three</name><val>Value three</val><description>This is a description for the third item</description></DFH0W2TC></content>

</entry>
<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
<entry>
<link rel="self" href="http://host:port/atom/scenario/tsq/dfhfeedq/2"/>
<id>tag:example.com,2011-12-11:tsqueue:DFHFEEDQ:2</id>
<title>TS queue structured record 2</title>
<updated>2011-12-14T13:05:38+00:00</updated>
<published>2011-12-14T13:05:38+00:00</published>
<content type="application/xml"><DFH0W2TC xmlns="https://www.ibm.com/xmlns/prod/cics/atom/text"><name>Name two</name><val>Value two</val><description/></DFH0W2TC></content>

</entry>
<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
<entry>
<link rel="self" href="http://host:port/atom/scenario/tsq/dfhfeedq/1"/>
<id>tag:example.com,2011-12-11:tsqueue:DFHFEEDQ:1</id>
<title>TS queue structured record 1</title>
<updated>2011-12-14T13:05:38+00:00</updated>
<published>2011-12-14T13:05:38+00:00</published>
<content type="application/xml"><DFH0W2TC xmlns="https://www.ibm.com/xmlns/prod/cics/atom/text"><name>Name one</name><val>Value one</val><description>This is a description</description></DFH0W2TC></content>

</entry>
</feed>

Results

You have successfully created an Atom feed from structured data in a temporary storage queue. The <content> element contains a <DFH0W2TC> element, which is named from the copybook. The <DFH0W2TC> element contains three elements to structure the data, rather than containing the simple text or binary data from the first scenario.

What to do next

Following this tutorial, try creating an Atom feed from structured data in one of your own temporary storage queues. Follow the same process to create the XML binding and schema. You might find the generated schema useful if you are writing an application to consume Atom data.