Constructing a document

Once a document has been created, the contents can be extended by issuing one or more DOCUMENT INSERT commands. The options on the DOCUMENT INSERT command work in the same way as the equivalent commands on the DOCUMENT CREATE command.

The following sequence of commands shows an empty document being created followed by two INSERT commands:

EXEC CICS DOCUMENT CREATE
         DOCTOKEN(ATOKEN)

EXEC CICS DOCUMENT INSERT
         DOCTOKEN(ATOKEN)
         TEXT('Sample line 1. ')
         LENGTH(15)

EXEC CICS DOCUMENT INSERT
         DOCTOKEN(ATOKEN)
         TEXT('Sample line 2. ')
         LENGTH(15)

The document resulting from the above commands will contain:

Sample line 1. Sample line 2.

You can 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.

The DOCUMENT INSERT command allows an operand called SYMBOL to be used to add blocks of data to the document. SYMBOL must contain the name of a valid symbol whose value has been set. The Document Handler inserts the value that is associated with the symbol into the document.

Note that when a value associated with a symbol has been inserted into a document, you cannot change that value in the document that is being composed. If you set a different value for the symbol, the new value will be used the next time that symbol is inserted into a document. Your change will not affect the value that has already been inserted into the document.