The READ stored procedure reads a specified amount of data from an internal LOB starting from a specified offset position and returns the data in the buffer parameter. The offset is calculated from the start of the LOB.
The number of bytes or characters actually read is returned in the amount parameter. If the offset is beyond the end of the LOB, amount is set to 0, and a NO_DATA_FOUND exception is thrown.
Syntax
DBMS_LOB.READ (
lob_loc IN BLOB,
amount IN OUT NOCOPY INTEGER,
offset IN INTEGER,
buffer OUT RAW);
DBMS_LOB.READ (
lob_loc IN CLOB CHARACTER SET ANY_CS,
amount IN OUT NOCOPY INTEGER,
offset IN INTEGER,
buffer OUT VARCHAR2 CHARACTER SET ANY_CS);
Parameters
| Parameter | Description |
|---|---|
| lob_loc | The locator of the LOB to read from. For more information, see Usage notes. |
| file_loc | The file locator of the LOB to examine. |
| amount | The amount of data to read or already read. The value is in bytes for BLOBs, and in characters for CLOBs. |
| offset | The offset position from which LOB data starts to be read. |
| buffer | The output buffer for the read operation. |
Exceptions
| Exception | Description |
|---|---|
| VALUE_ERROR | Any of the lob_loc, mount, and offset parameters is NULL. |
| INVALID_ARGVAL | Several possibilities:
|
| NO_DATA_FOUND | The end of the LOB is reached and no more bytes or characters need to be read from the LOB, that is, the amount parameter has a value of 0. |
Usage notes
The form of the
VARCHAR2buffer must match the form of theCLOBparameter. That is, if the type of the inputLOBparameter isCLOB, the data in the buffer must be of theCHARtype.When you call
DBMS_LOB.READfrom the client, data in the buffer returned must use the client's character set. Before the database returns the buffered data to you, it converts the value of theLOBfrom the character set of the server to that of the client.When necessary,
READcan obtain theLOBbefore it reads data from it.