Bookmarks

The sequence in which an application inserts data into a document might not reflect the desired sequence that the data should appear in the document. 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 that the application inserts between blocks of data. Note: a bookmark cannot be inserted in the middle of a block of data.

The following example creates a document with two blocks of text and a bookmark:

EXEC CICS DOCUMENT CREATE
         DOCTOKEN(ATOKEN)
         TEXT('Pre-bookmark text. ')
         LENGTH(19)
 
EXEC CICS DOCUMENT INSERT
         DOCTOKEN(ATOKEN)
         BOOKMARK('ABookmark       ')
 
EXEC CICS DOCUMENT INSERT
         DOCTOKEN(ATOKEN)
         TEXT('Post-bookmark text. ')
         LENGTH(20)
 

The document will now contain:

Pre-bookmark text. <ABookmark>Post-bookmark text.

Note that the text <ABookmark> does not appear in the document content but serves merely as a pointer to that position in the document. To add data to this document, you can insert text at the bookmark as follows:

EXEC CICS DOCUMENT INSERT
         DOCTOKEN(ATOKEN)
         TEXT('Inserted at a bookmark. ')
         LENGTH(25)
         AT('ABookmark       ')

Logically, the data of the document will contain the following (Note that in this instance, only the data is being shown and not the position of the bookmark).

Pre-bookmark text. Inserted at a bookmark. Post-bookmark text.

If the AT option is omitted, the data is always appended to the end of the document. A special bookmark of 'TOP' can be used to insert data at the top of the document, making it unnecessary to define a bookmark which will mark the top of the document.