DOCUMENT RETRIEVE

Copy a document into the application's own buffer.

Read syntax diagramSkip visual syntax diagram
DOCUMENT RETRIEVE

>>-DOCUMENT--RETRIEVE--DOCTOKEN(data-area)--INTO(data-area)----->

>--LENGTH(data-value)--+-----------------------+---------------->
                       '-MAXLENGTH(data-value)-'   

>--+--------------------+--+----------+------------------------><
   '-CLNTCODEPAGE(name)-'  '-DATAONLY-'   

Conditions: LENGERR, NOTFND

This command is threadsafe.

 

Description

DOCUMENT RETRIEVE allows the application to obtain a copy of the document in its own buffer, which it can then manipulate directly. The document is managed by CICS®, and the application does not have direct access to the buffer containing the contents of the document. The document exists only for the duration of the current transaction, so the application must retrieve the document and store it if the document is to exist over transaction boundaries. The retrieved document can be used as a basis for a new document by using the FROM option of the DOCUMENT CREATE command.

When the document is retrieved, CICS inserts tags into the document contents to identify the bookmarks and to delimit the blocks that do not require codepage conversion. To request a copy without tags, specify DATAONLY. The extracted document can also be converted into a single client codepage by using the CLNTCODEPAGE option.

Options

CLNTCODEPAGE(name)
specifies the name of the client codepage to which the data should be converted. The name can be up to 40 characters in length; if it is shorter than 40 characters, it must be padded on the right with blanks.
DATAONLY
specifies that the data should be retrieved without any imbedded tags.
DOCTOKEN(data-area)
specifies the 16-byte symbolic name of the document to be retrieved.
INTO(data-area)
specifies the buffer that is to contain the copy of the document content.
LENGTH(data-value)
specifies the length, as a fullword binary value, of the amount of data being returned to the application.
MAXLENGTH(data-value)
specifies the length, as a fullword binary value, of the maximum amount of data the buffer can receive.

Conditions

LENGERR
RESP2 values:
1
MAXLENGTH is less than or equal to zero. The document is truncated.
2
The length of the receiving buffer is zero, or is too short to contain the document contents. The document is truncated.
NOTFND
RESP2 values:
1
The document has not been created, or the name is incorrectly specified.
7
The specified client codepage can not be found.