DOCUMENT INSERT

Description

DOCUMENT INSERT allows the application to insert document objects at insertion points in the document. The insertion points (bookmarks) define relative positions in the document. Bookmarks must be defined before being referenced. Data is always inserted after the position identified by the bookmark.

Options

AT(name)

specifies the 16-byte symbolic name of a bookmark which identifies the position of the insertion point in the document. Data is inserted after the bookmark, and any data following the bookmark is shifted down. The application can use a combination of the AT and TO options to perform an overlay operation. If the AT operand is not specified, the data is inserted at the end of the document. A pre-defined bookmark of TOP is provided to allow the application to insert data at the beginning of the document.

BINARY(data-area)

specifies a buffer of data to be inserted into the document. The data is copied unchanged to the insertion point in the document, and no attempt is made to parse the data for symbol substitution. The BINARY option allows the application to insert blocks of data that must not undergo conversion to a client code page when the data is sent. Use the LENGTH option to specify the length of this buffer.

BOOKMARK(name)

specifies a bookmark to be inserted into the document. A bookmark is a symbolic name which identifies an insertion point in the document. The name can be up to 16 characters in length, and must not contain any imbedded spaces.

DOCSIZE(data-value)

specifies a binary fullword area to be updated with the current size of the document in bytes. This is the maximum size of the buffer needed to contain a copy of the document when a RETRIEVE command is issued.

DOCTOKEN(data-area)

specifies the 16-byte binary token of the document into which data is to be inserted.

FROM(data-area)

specifies that a buffer of data supplied by the application is to be inserted into the document. The data content can be a template or a document that was previously created and retrieved. If the data is a template, symbol substitution takes place where the symbols exist in the symbol table. If the data is a previously retrieved document, the conversion and bookmark tags which were inserted during the retrieval will be removed from the content and stored in the internal form required by the API commands. Note that symbol substitution will not be attempted on any unresolved symbols contained in a retrieved document. Use the LENGTH option to specify the length of this buffer.

FROMDOC(data-area)

specifies the binary token of a document (see the DOCTOKEN option) whose contents are copied to the insertion point of the target document. All bookmarks and conversion tags are copied to the target document. The symbol table is not copied.

HOSTCODEPAGE(name)

specifies the symbolic name (see the DOCTOKEN option) of the host code page that the data being added is encoded in. This option applies to the TEXT, SYMBOL and TEMPLATE options only. The name must be eight characters long; if it is shorter than eight characters, it must be padded on the right with blanks.

The standard CICS® form of a host code page name consists of the code page number (or more generally CCSID) written using 3 to 5 decimal digits as necessary then padded with trailing spaces to 8 characters. For code page 37, which is fewer than 3 digits, the standard form is 037. CICS now also accepts any decimal number of up to 8 digits (padded with trailing spaces) in the range 1 to 65535 as a code page name, even if it is not in the standard form.

Note that the HOSTCODEPAGE parameter must specify an EBCDIC-based code page if any symbol processing will be required, as the delimiters used for symbol and symbol list processing are assumed to be in EBCDIC.

LENGTH(data-value)

specifies the length, as a fullword binary value, of the buffer containing the TEXT, BINARY or FROM data.

When the DOCUMENT INSERT command follows a DOCUMENT RETRIEVE command, without the use of the DATAONLY option, and the retrieved document is being inserted using the FROM option, the LENGTH specified must be equal to the length of the retrieved document.

SYMBOL(name)

specifies the 32-byte name of a symbol in the symbol table. The data associated with the symbol in the symbol table is inserted, but not the symbol itself. Note that when data associated with a symbol has been inserted into a document, you cannot change that data 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.

TEMPLATE(name)

specifies the 48-byte name of a template. The template must be defined to CICS using RDO. If the name is less than 48 bytes, it must be padded on the right with blanks. The current values of any symbols are substituted into the template.

Note: When a template containing symbols has been inserted into a document, you cannot change the substituted values of those symbols in the document that is being composed. If you set different values for the symbols, the new values will be used the next time that the template is inserted into a document. Your changes will not affect the values that have already been inserted into the document.

TEXT(data-area)

specifies a buffer of data to be inserted into the document. The data is copied unchanged to the insertion point in the document, and no attempt is made to parse the data for symbol substitution. When the document is sent, it is marked as requiring conversion to the client code page. Use the LENGTH option to specify the length of this buffer.

TO(name)

specifies the symbolic name of a bookmark identifying the end position of an overlay operation. Data between the bookmarks identified by the AT and TO operands is deleted, and new data is inserted in its place. It is possible to delete data between two bookmarks by specifying a null string on the TEXT or BINARY option with a LENGTH of zero.

Conditions

14 DUPREC

The bookmark has already been defined.

16 INVREQ

RESP2 values are:

0

The bookmark specified on the TO option appears before the bookmark specifed on the AT bookmark.

1

The retrieved document specified on the FROM option is not in a valid RETRIEVE format.

2

The bookmark name on the BOOKMARK option is invalid.

LENGERR

RESP2 value:

1

The value specified for LENGTH is invalid. The value is negative.

70 NOTAUTH

The command has failed a resource security check. (If the NOTAUTH condition is not handled, applications that receive it may abend with code AEY7.)

Note that the EXEC CICS DOCUMENT commands reference document templates using the 48-character name of the template (as specified in the TEMPLATENAME attribute of the DOCTEMPLATE resource definition). However, security checking for the commands uses the name of the DOCTEMPLATE resource definition that corresponds to the TEMPLATENAME attribute. If resource security checking is in place, the user ID for the transaction must have READ access to this DOCTEMPLATE resource definition.

RESP2 value:

101

The user ID for the transaction does not have READ access to the DOCTEMPLATE resource definition for the document template named by the TEMPLATE option.

13 NOTFND

One of the following documents or templates could not be found, or its name was incorrect.

RESP2 values:

1

The document specified on the DOCUMENT option.

2

The document specified on the FROMDOC option.

3

The template specified on the TEMPLATE option.

4

The document specified on the SYMBOL option.

5

The document specified on the AT option.

6

The document specified on the TO option.

7

The document specified on the HOSTCODEPAGE option.

117 TEMPLATERR

An invalid #set, #include or #echo command has been encountered while processing the supplied template data, or the CICS region does not have the correct level of authority to access the zFS file of this template. RESP2 contains either a zero (if the maximum of 32 levels of embedded templates is exceeded), or the offset of the invalid command.