A web client can create a new Atom entry in a collection
by making an HTTP POST request to the URL of the collection.
Before you begin
If you do not know the URL of the collection that you want
to edit, or you are writing an application that can handle multiple
collections, first make an HTTP GET request for the Atom service document
that you set up in
Creating an Atom service document.
The Atom service document lists the URLs of the collections that are
available on the server.
Procedure
- Begin your HTTP POST request with a request line consisting of the POST method, followed by the
path component of the URL of the collection, followed by HTTP/1.1, which is
the HTTP version for the request. You may also include the scheme (HTTP or HTTPS) and the host name in the URL.
- Write HTTP headers for the request as follows, each on
a new line:
- The Host header, giving the host name from the URL of the collection,
if you did not already include the host name in the request line.
- The Authorization header, with any security information required
to access your collection, such as a user ID and password for basic
authentication.
- The Content-Type header, with the value application/atom+xml;type=entry.
- The Content-Length header, stating the length of your message
body in bytes (octets). Specify the value for this header when you
have finished writing the message body.
Put an additional carriage return line feed (CRLF)
after the last HTTP header to give an empty line.
- Set up a message body containing the XML markup for the
Atom entry that you want to post.
- If you already have Atom entries in your collection,
make a GET request to obtain a feed or entry document for the collection,
and copy an existing Atom entry from the collection into your message
body.
- If you do not have any Atom entries in your collection
yet, write the XML markup for your first Atom entry based on the examples
in these topics.
- Check that the <entry> tag at the start of your Atom
entry contains the namespace declaration xmlns="http://www.w3.org/2005/Atom",
and add that namespace declaration if it is not present. In
Atom documents sent from CICS, the elements typically do not include
the atom: namespace prefix. The Atom namespace is defined as the default
namespace in the element at the beginning of the Atom document, so
you do not have to use the atom: prefix for the child elements. In
the CICS documentation, the prefix is used in the element names for
clarity. If you prefer to use the atom: namespace prefix in the elements
in your request, change the namespace declaration to xmlns:atom="http://www.w3.org/2005/Atom".
- Add the element <?xml version="1.0" ?> before your
Atom entry.
- Specify the appropriate elements of your Atom entry with
the data that you require, and delete any elements that you do not
use. You do not need to provide data for all the elements
that are present in an Atom entry document sent out by CICS. When
you post an entry to a collection managed by CICS, you can omit any
elements that are not stored in the CICS resource, and also any elements
that are stored in the CICS resource but are generated by CICS or
the service routine. Typically, you can omit at least the following
elements:
- Elements containing time stamps, such as the <atom:updated>
element (unless your service routine accepts user input for these)
- The <atom:id> element
- The <atom:contributor> element
- The <atom:link> element
- The <atom:rights> element
If in doubt, include the element, and CICS or the service routine
will ignore it if it is not wanted. RFC 5023 has the complete
list of possible elements in Atom entries. For a summary of the elements
that are required, allowed, or not used in Atom entries, see Atom element reference for CICS. For a description of the
content of each element, see <atom:entry> Atom configuration file element.
- Send your request to the server.
Results
The server sends an HTTP response with the status code
200, indicating successful completion of the request, or a suitable
error response. If the request is successful, the response contains
a copy of the new Atom entry. Check the Atom entry in the response
from the server against your original submission, to make sure that
you are satisfied with the new entry.
If you receive an error response, read the message body for the response, and refer to the list
of status codes that CICS® provides to web clients in HTTP status code reference for CICS web support. If the error response
indicates that there might be a problem with your request, such as the HTTP status code 400 (Bad
Request or Invalid Request), check to see whether the CICS region has issued message DFHML0100. CICS
uses the z/OS XML System Services parser to parse the XML markup of your Atom entry. If the parser
finds a problem with the markup, CICS issues message DFHML0100 containing the return code and reason
code from the parser. For an explanation of the return code and reason code, see the z/OS XML System Services User's Guide and Reference.
Example
This is a request to create a new Atom entry in a collection
with the URL
http://www.example.com:80/web20/myfeed :
POST /web20/myfeed HTTP/1.1
Host: www.example.com:80
Content-Type: application/atom+xml;type=entry
Content-Length: 763
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>This is my posted entry</title>
<summary>
This is my new posted entry
</summary>
<category term="Test Feeds"/>
<author>
<name>Joe Bloggs</name>
<email>JBloggs@example.com</email>
<uri>http://www.example.com/JBloggs/</uri>
</author>
<content type="text/xml">
<SAMPBIND xmlns="http://www.ibm.com/xmlns/prod/cics/atom/bindfile/sampbind">
<data_field>
Here is content for my posted entry
</data_field>
</SAMPBIND >
</content>
</entry>
This is the response that CICS sends:
HTTP/1.1 201 Created
Content-Type: application/atom+xml;type=entry
Content-Length: 1029
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app">
<generator uri="http://www.ibm.com/cics/" version="6.6.0">
CICS Transaction Server Version 4.1.0
</generator>
<link rel="self" href="http://www.example.com:80/web20/entry/10"/>
<link rel="edit" href="http://www.example.com:80/web20/entry/10"/>
<id>tag:http://www.example.com/web20/myfeed,2009-01-20:tsqueue:WB20TSQ:10</id>
<title>This is my posted entry</title>
<summary>
This is my new posted entry
</summary>
<category term="Test Feeds"/>
<rights>Copyright (c) 2009, Joe Bloggs</rights>
<published>2009-04-23T15:00:44+00:00</published>
<author>
<name>Joe Bloggs</name>
<email>JBloggs@example.com</email>
<uri>http://www.example.com/JBloggs/</uri>
</author>
<app:edited>2009-04-23T15:00:44+00:00</app:edited>
<updated>2009-04-23T15:00:44+00:00</updated>
<content type="text/xml">
<SAMPBIND xmlns="http://www.ibm.com/xmlns/prod/cics/atom/bindfile/sampbind">
<data_field>
Here is content for my posted entry
</data_field>
</SAMPBIND >
</content>
</entry>