DOCUMENT RETRIEVE

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 code page conversion. To request a copy without tags, specify DATAONLY. The extracted document can also be converted into a single client code page by using the CHARACTERSET option.

The DOCUMENT CREATE and DOCUMENT INSERT commands return a DOCSIZE value. This value is the maximum size of the buffer needed to contain a copy of the document in its original code page (including control information), when the RETRIEVE command is issued. However, when the CHARACTERSET option specifies an encoding that requires more bytes than the original EBCDIC data (for example, UTF-8), the maximum size might not be large enough to store the converted document. If the DOCSIZE value is used for the buffer size in this case, the program should be prepared to handle a LENGERR condition and acquire a new buffer using the size returned in the LENGTH parameter. Alternatively, you can determine the actual document length before allocating the buffer by issuing a DOCUMENT RETRIEVE with a dummy buffer and a MAXLENGTH of zero, then handling the LENGERR condition and using the returned LENGTH value.

Options

CHARACTERSET(name)

specifies the name of the client character set 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).

This parameter replaces the CLNTCODEPAGE parameter, which is supported for upgrade purposes only.

CLNTCODEPAGE(name)

This option is supported for upgrade purposes only. CHARACTERSET replaces it. The action taken by CICS is the same for both keywords.

DATAONLY

specifies that the data should be retrieved without any imbedded tags.

DOCTOKEN(data-area)

specifies the 16-byte binary token 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. If the document is truncated, this is the exact length required to return the whole document.

MAXLENGTH(data-value)

specifies the length, as a fullword binary value, of the maximum amount of data the buffer can receive.

Conditions

16 INVREQ

RESP2 values:

11

An invalid or unsupported combination of code pages was specified.

12

An error occurred during CCSID conversion and the conversion could not be completed. For example, a piece of text or a symbol value ended part of the way through a multi-byte character.

22 LENGERR

RESP2 values:

1

MAXLENGTH is less than zero. The document size is not returned in the LENGTH field.

2

The length of the receiving buffer is zero, or is too short to contain the document contents. The document is truncated and the exact length required is returned in the LENGTH field.

13 NOTFND

RESP2 values:

1

The document has not been created, or the name is incorrectly specified.

7

The specified character set cannot be found.