When you have created a document, you can extend its
contents by
issuing one or more DOCUMENT INSERT commands. You can insert text, binary
data, a buffer of data, a document template, or the value of a symbol.
You
can also insert bookmarks in a document, and use these to position later
insertions.
About this task
You can specify options on the DOCUMENT INSERT command to:
- Insert a character string (TEXT option).
- Insert a block of binary data (BINARY option).
- Insert a document template, specified by its template name
(TEMPLATE option).
- Insert the contents of a buffer of data (FROM option).
- Insert the value of a named symbol from the symbol table
(SYMBOL option).
By default, the objects that you specify are added to the end
of the document. To insert data in the middle of a document, you can
set up
one or more bookmarks. Bookmarks allow the application to insert blocks
of
data in any order yet still control the sequence of the data in the
document.
A
bookmark is a label placed between blocks of data - it cannot be placed in
the middle of a block of data. You can use the DOCUMENT INSERT
command to
place a bookmark in a document during its construction, and then use the
AT
option to specify the bookmark when you insert a subsequent object. A
special
bookmark of 'TOP' is already defined, which you can use to insert data at
the top of the document.
Procedure
- Use the TEXT option to insert a character string specified by
your
application program.
For example:
EXEC CICS DOCUMENT INSERT
DOCTOKEN(MYDOC)
TEXT('Sample line 1.')
LENGTH(15)
This string is added to the
document unchanged, and CICS does not carry out any symbol substitution for
it.
- Use the BINARY option to insert a block of binary data, which
does
not undergo code page conversion when the data is sent. For
example:
EXEC CICS DOCUMENT INSERT
DOCTOKEN(MYDOC)
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 insert a document template. If
you want to set values for the symbols in the document template, use
the DOCUMENT
SET command to specify individual symbols or a symbol list,
before
you
issue the DOCUMENT INSERT command.
Defining symbol values
explains how to do this.
- Use the FROM option to insert 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.
- Use the SYMBOL option to insert the value of a symbol. SYMBOL
specifies the name of a valid symbol whose value has been set in the symbol
table (using the DOCUMENT SET or DOCUMENT CREATE command). The
document handler
inserts the value that is associated with the symbol into the document. Note that after you have inserted a value associated with a
symbol into
a document, you cannot change that value in the document that is
being composed.
If you subsequently 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.
- Use the BOOKMARK option to insert a bookmark into the document. Bookmarks are placed during the construction of a document,
and they
provide an insertion point for the application to insert data that is
obtained
at a later stage.
The name of a bookmark must be 16 characters
long. It must not contain any imbedded spaces, and if your chosen name
is
less than 16 characters long, it must be padded on the right with
blanks. For example, this sequence of commands creates a document with two
blocks of text and a bookmark:
EXEC CICS DOCUMENT CREATE
DOCTOKEN(MYDOCBOOK)
TEXT('Pre-bookmark text. ')
LENGTH(19)
EXEC CICS DOCUMENT INSERT
DOCTOKEN(MYDOCBOOK)
BOOKMARK('ABookmark ')
EXEC CICS DOCUMENT INSERT
DOCTOKEN(MYDOCBOOK)
TEXT('Post-bookmark text. ')
LENGTH(20)
- Use the AT option with any of the other insertion options to
place
the object at a previously inserted bookmark, or at the special TOP
bookmark. For example, this command inserts text at the example bookmark
ABookmark:
EXEC CICS DOCUMENT INSERT
DOCTOKEN(MYDOCBOOK)
TEXT('Inserted at a bookmark. ')
LENGTH(25)
AT('ABookmark ')
The completed document reads as
follows:
Pre-bookmark text. Inserted at a bookmark. Post-bookmark
text.