READ_TEXT Procedure

This procedure reads the HTTP response body in text form and returns the output in the caller-supplied buffer. The end_of_body exception will be raised if the end of the HTTP response body is reached. Text data is automatically converted from the response body character set to the database character set.

Syntax

UTL_HTTP.read_text(

r  IN OUT NOCOPY resp,
data  OUT NOCOPY VARCHAR2,
len  IN PLS_INTEGER DEFAULT NULL);

Parameters

Table 78-43 shows the parameters for the READ_TEXT procedure.

Table 78-43 READ_TEXT Procedure Parameters

Parameter	Description
r (IN/OUT)	The HTTP response.
data (OUT)	The HTTP response body in text form
len (IN)	The maximum number of characters of data to read. If len is NULL, this procedure will read as much input as possible to fill the buffer allocated in data. The actual amount of data returned may be less than that specified if little data is available before the end of the HTTP response body is reached or the transfer_timeout amount of time has elapsed. The default is NULL.

Usage Notes

The UTL_HTTP package supports HTTP 1.1 chunked transfer-encoding. When the response body is returned in chunked transfer-encoding format as indicated in the response header, the package automatically decodes the chunks and returns the response body in de-chunked format.

If transfer timeout is set in the request of this response, read_text waits for each data packet to be ready to read until timeout occurs. If it occurs, this procedure stops reading and returns all the data read successfully. If no data is read successfully, the transfer_timeout exception is raised. The exception can be handled and the read operation can be retried later.

If a partial multi-byte character is found at the end of the response body, read_text stops reading and returns all the complete multi-byte characters read successfully. If no complete character is read successfully, the partial_multibyte_char exception is raised. The exception can be handled and the bytes of that partial multi-byte character can be read as binary by the read_raw procedure. If a partial multi-byte character is seen in the middle of the response body because the remaining bytes of the character have not arrived and read timeout occurs, the transfer_timeout exception is raised instead. The exception can be handled and the read operation can be retried later.