Adding more data to a document

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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)
  7. 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.


dfhp3_doc_construct.html | Timestamp icon Last updated: Monday, 5 June 2017