Insert document objects.

DOCUMENT INSERT
>>-DOCUMENT--INSERT--DOCTOKEN(data-area)------------------------>
>--+-+-TEXT(data-area)---+--LENGTH(data-value)-+---------------->
| +-BINARY(data-area)-+ |
| '-FROM(data-area)---' |
+-SYMBOL(name)------------------------------+
+-TEMPLATE(name)----------------------------+
+-FROMDOC(data-area)------------------------+
'-BOOKMARK(name)----------------------------'
>--+---------------------+--+--------------------+-------------->
'-DOCSIZE(data-value)-' '-HOSTCODEPAGE(name)-'
>--+------------------------+----------------------------------><
'-AT(name)--+----------+-'
'-TO(name)-'
Conditions: DUPREC, INVREQ, NOTFND, TEMPLATERR
This command is threadsafe.
Description
DOCUMENT INSERT allows the application to insert document objects at insertion
points within the document. The insertion points (bookmarks) define relative
positions within 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 symbolic name 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 symbolic name 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 codepage
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.
- 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
- DUPREC
- the bookmark has already been defined.
- 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.
- 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.
- TEMPLATERR
- an invalid #set, #include or #echo command has
been encountered while processing the supplied template data. RESP2 contains
either a zero (if the maximum of 32 levels of embedded templates is exceeded),
or the offset of the invalid command.