read_text Function

This function receives text data from a service on an open connection.

Syntax

UTL_TCP.READ_TEXT (c    IN OUT NOCOPY connection,
                   data IN OUT NOCOPY VARCHAR2,
                   len  IN            PLS_INTEGER DEFAULT 1,
                   peek IN            BOOLEAN     DEFAULT FALSE) RETURN PLS_
INTEGER;

Table 83-8 read_text Function Parameters

Parameter	Description
c (IN OUT NOCOPY)	The TCP connection to receive data from.
data (IN OUT NOCOPY)	The data received.
len (IN)	The number of characters of data to receive.
peek (IN)	Normally, users want to read the data and remove it from the input queue, i.e. consuming it. In some situations, users may just want to look ahead at the data, i.e. peeking it, without removing it from the input queue so that it is still available for reading (or even peeking) in the next call. To keep the data in the input queue, set this flag to TRUE and an input buffer must be set up when the connection is opened. The amount of data that can be peeked (i.e. read but kept in the input queue) must be less the size of input buffer.
return value	The actual number of characters of data received.

Usage Notes

The connection must have already been opened via a call to open_connection(). This function does not return until the specified number of characters has been read, or the end of input has been reached. Text messages will be converted from the on-the-wire character set, specified when the connection was opened, to the database character set before they are returned to the caller.

Unless explicitly overridden, the size of a VARCHAR2 buffer is specified in terms of bytes, while the parameter len refers to the maximum number of characters to be read. When the database character set is multi-byte, where a single character may consist of more than 1 byte, you should ensure that the buffer can hold the maximum of characters. In general, the size of the VARCHAR2 buffer should equal the number of characters to be read, multiplied by the maximum number of bytes of a character of the database character set.

If transfer time-out is set when the connection is opened, this function waits for each data packet to be ready to read until time-out occurs. If it occurs, this function 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 input, this function 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 function. If a partial multi-byte character is seen in the middle of the input because the remaining bytes of the character have not arrived and read time-out occurs, the transfer_timeout exception is raised instead. The exception can be handled and the read operation can be retried later.

Related Functions

read_raw(), read_line(), available()