Retrieving, storing and reusing a document

Documents created by an application exist only for the length of the CICS® task in which they are created. To reuse a document, the application needs to retrieve a copy and save it.

About this task

This sequence of commands shows how an application can use EXEC CICS DOCUMENT commands to create a document, retrieve it, store it on a temporary storage queue, and reuse it as a document in the same or another application.

Java applications can retrieve documents that were created by applications written in other programming languages, and work with the documents using the JCICS classes. For the class documentation, see the Javadoc in JCICS class reference.

Procedure

In the application program, define and initialize the following variables:
- A 16-byte field ATOKEN to hold the document token.
- A 20-byte buffer DOCBUF to hold the retrieved document.
- A fullword binary field called FWORDLEN to hold the length of the data retrieved.
- A halfword binary field called HWORDLEN to hold the length for the temporary storage WRITE command.
Create the initial document using the DOCUMENT CREATE command:
```
EXEC CICS DOCUMENT CREATE
          DOCTOKEN(ATOKEN)
          TEXT('A sample document.')
          LENGTH(18)
```
To help the application calculate the size of the buffer needed to hold a retrieved document, the document commands which alter the size of the document (the DOCUMENT CREATE and DOCUMENT INSERT commands) have a DOCSIZE option available. This value is the maximum size of the buffer needed to contain a copy of the document in its original code page (including control information), when the RETRIEVE command is issued. However, when the CHARACTERSET option specifies an encoding that requires more bytes than the original EBCDIC data (for example, UTF-8), the maximum size might not be large enough to store the converted document. You can determine the actual document length before allocating the buffer by issuing a DOCUMENT RETRIEVE with a dummy buffer and a MAXLENGTH of zero, then handling the LENGERR condition and using the returned LENGTH value.
In the same task, issue the DOCUMENT RETRIEVE command to obtain a copy of the document in the application's own buffer.
```
EXEC CICS DOCUMENT RETRIEVE
          DOCTOKEN(ATOKEN)
          INTO(DOCBUF)
          LENGTH(FWORDLEN)
          MAXLENGTH(20)
```
By default, when the document is retrieved, the data that is delivered to the application buffer is stored in a form which contains control information necessary to reconstruct an exact replica of the document. CICS inserts tags into the document contents to identify the bookmarks and to delimit the blocks that do not require code page conversion. A document that you create from the retrieved copy is therefore identical to the original document. If you do not need to re-create the original document, you can modify the DOCUMENT RETRIEVE command as follows:
1. To request a copy without control information, specify the DATAONLY option.
  With this option, CICS omits all the imbedded tags. The retrieved document contains no bookmarks, and there are no markings to delimit blocks that do not require code page conversion.
2. To convert the whole of the copy into a single client code page, specify the CHARACTERSET option.

Store the document on the temporary storage queue:

EXEC CICS WRITEQ TS
          QUEUE('AQUEUE')
          FROM(DOCBUF)
          LENGTH(HWORDLEN)

In the same or another application, read the stored data into the application's buffer:

EXEC CICS READQ TS
          QUEUE('AQUEUE')
          INTO(DOCBUF)
          LENGTH(HWORDLEN)

Use the DOCUMENT CREATE command with the FROM option to create a new document using the contents of the data buffer, that is, the retrieved document:
```
EXEC CICS DOCUMENT CREATE
          DOCTOKEN(ATOKEN)
          FROM(DOCBUF)
          LENGTH(FWORDLEN)
```

What to do next

You can also use the DOCUMENT RETRIEVE and DOCUMENT INSERT commands to insert a whole document into an existing document. The following variables must first be defined and initialized in the application program:

A 16-byte field RTOKEN which contains the document token of the document to be retrieved
A buffer DOCBUF of sufficient length to hold the retrieved document
A fullword binary field called RETRIEVLEN to hold the length of the data retrieved
A fullword binary field called MAXLEN to hold the maximum amount of data the buffer can receive, i.e. the length of DOCBUF
A 16-byte field ITOKEN which contains the document token of the document that is being inserted into

The following sequence of commands shows a document indicated by RTOKEN being inserted into another document indicated by ITOKEN:

 EXEC CICS DOCUMENT RETRIEVE       
           DOCTOKEN(RTOKEN)        
           INTO(DOCBUF)            
           LENGTH(RETRIEVLEN)      
           MAXLENGTH(MAXLEN)       
                                   
 EXEC CICS DOCUMENT INSERT         
           DOCTOKEN(ITOKEN)        
           FROM(DOCBUF)            
           LENGTH(RETRIEVLEN)

The retrieved document is inserted at the end of the document specified in the DOCUMENT INSERT command, and all the control information of the retrieved document will be present in the second document. The LENGTH parameter of the DOCUMENT INSERT command must be equal to the value returned from the DOCUMENT RETRIEVE command into the field RETRIEVLEN.