Creating a document

You can use the DOCUMENT CREATE command to create either an empty document, or a document containing data. The data can be a character string, a block of binary data, a document template, or a buffer of data.

About this task

To create a document containing data, you can specify options on the EXEC CICS DOCUMENT CREATE command to:

Include a character string (TEXT option).
Include a block of binary data (BINARY option).
Use a document template, specified by its template name (TEMPLATE option).
Include the contents of a buffer of data (FROM option).
Give values to any symbols in the document template or the item specified by the FROM option (SYMBOLLIST option).

The DOCUMENT CREATE command has a DOCTOKEN option, which is mandatory and requires a 16–byte data-area. The document handler uses the DOCTOKEN operand to return a token, which is used to identify the document on subsequent calls.

These examples show the different ways in which an application can use EXEC CICS DOCUMENT commands to create a document. In Java™ applications, you can use the CICS® Java class library (JCICS) to access document services. The Document class provides the Java implementation of the EXEC CICS DOCUMENT commands. For the class documentation, see the Javadoc in JCICS class reference.

Procedure

To create an empty document and return its token, use the EXEC CICS DOCUMENT CREATE command with the DOCTOKEN option.
This example creates an empty document, and returns the token in the 16-character variable MYDOC:
```
EXEC CICS DOCUMENT CREATE
DOCTOKEN(MYDOC)
```
Use the TEXT option to create a document that contains a character string specified by your application program.
For example, if you define a character string variable called DOCTEXT and initialize it to This is an example of text to be added to a document , you can use the following command to create a document consisting of this text string:
```
EXEC CICS DOCUMENT CREATE
DOCTOKEN(MYDOC1)
TEXT(DOCTEXT)
LENGTH(53)
```
This string is added to the document unchanged, and CICS does not carry out any symbol substitution for it.
Use the BINARY option to create a document that contains binary data, which does not undergo code page conversion when the data is sent.
This example creates a document consisting of the contents of a data-area as binary data:
```
EXEC CICS DOCUMENT CREATE
DOCTOKEN(MYDOC2)
BINARY(DATA-AREA)
```
CICS does not carry out any symbol substitution for this data, and marks the data so that it is not converted to a client code page when you send the document to the recipient.
Use the TEMPLATE option to create a document using a document template that you have defined to CICS using a DOCTEMPLATE resource definition:
1. Define a 48-byte variable, such as TEMPLATENAME, and initialize it to the value of the 48-character name of the template, as specified in the TEMPLATENAME attribute of its DOCTEMPLATE resource definition.
2. If your document template contains no symbols, or you want to use the default values for the symbols, you can use the DOCUMENT CREATE command without the SYMBOLLIST option.
  For example:
```
EXEC CICS DOCUMENT CREATE
DOCTOKEN(MYDOC3)
TEMPLATE(TEMPLATENAME)
```
  It is important to note that you can only specify values for symbol substitution before, or at the time when, the document template is placed into the document. You cannot change the substituted values of the symbols after the template has been inserted.
3. If you want to set values for symbols in the document template, use the DOCUMENT CREATE command with the SYMBOLLIST option.
  For example:
```
EXEC CICS DOCUMENT CREATE
DOCTOKEN(MYDOC3)
TEMPLATE(TEMPLATENAME)
SYMBOLLIST('ORDER_NUMBER=0012345')
LISTLENGTH(20)
```
Use the FROM option to create a document using a buffer of data.
The buffer of data can contain symbol references that will be substituted in the same way as symbol references contained in document templates.
For example:
```
EXEC CICS DOCUMENT CREATE
DOCTOKEN(MYDOC4)
FROM(BUFFER)
SYMBOLLIST('ORDER_NUMBER=0012345')
LENGTH(LEN)
```