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, LENGERR, NOTAUTH, NOTFND, TEMPLATERR
This command is threadsafe.
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
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.
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.