|Oracle Call Interface Programmer's Guide
Release 2 (9.2)
Part Number A96584-01
More OCI Relational Functions, 40 of 106
Reads a portion of a LOB/FILE, as specified by the call, into a buffer.
sword OCILobRead ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub4 *amtp, ub4 offset, dvoid *bufp, ub4 bufl, dvoid *ctxp, OCICallbackLobRead (cbfp) ( dvoid *ctxp, CONST dvoid *bufp, ub4 len, ub1 piece ) ub2 csid, ub1 csfrm );
The service context handle.
An error handle you can pass to
OCIErrorGet() for diagnostic information in the event of an error.
A LOB/FILE locator that uniquely references the LOB/FILE. This locator must be a locator that was obtained from the server specified by
The value in
amtp is the amount in either bytes or characters, as shown in this table:
|LOB/FILE||Input||Output with fixed-width client-side character set||Output with varying-width client-side character set|
(1) The input amount refers to the number of characters to be read from the server-side
NCLOB. The output amount indicates how many bytes were read into the buffer
*amtp is the total amount of data read if:
*amtp is the length of the last piece read if the data is read in streamed mode using polling.
If the amount to be read is larger than the buffer length it is assumed that the LOB is being read in a streamed mode from the input offset until the end of the LOB, or until the specified number of bytes have been read, whichever comes first. On input if this value is 0, then the data shall be read in streamed mode from the input offset until the end of the LOB.
The streamed mode (implemented with either polling or callbacks) reads the LOB value sequentially from the input offset.
If the data is read in pieces,
*amtp always contains the length of the piece just read.
If a callback function is defined, then this callback function will be invoked each time
bufl bytes are read off the pipe. Each piece will be written into
If the callback function is not defined, then the OCI_NEED_DATA error code will be returned. The application must call
OCILobRead() over and over again to read more pieces of the LOB until the OCI_NEED_DATA error code is not returned. The buffer pointer and the length can be different in each call if the pieces are being read into different sizes and locations.
On input, this is the absolute offset from the beginning of the LOB value. For character LOBs (
NCLOBs) it is the number of characters from the beginning of the LOB, for binary LOBs/FILEs it is the number of bytes. The first position is 1.
If you use streaming (by polling or a callback), then, specify the offset in the first call and in subsequent polling calls the offset parameter is ignored. When using a callback there is no offset parameter.
The pointer to a buffer into which the piece will be read. The length of the allocated memory is assumed to be
The length of the buffer in octets. This value will differ from the
amtp value for
CLOBs and for
csfrm=SQLCS_NCHAR) if the
amtp parameter is specified in terms of characters, while the
bufl parameter is specified in terms of bytes.
The context pointer for the callback function. Can be null.
A callback that may be registered to be called for each piece. If this is null, then OCI_NEED_DATA will be returned for each piece.
The callback function must return OCI_CONTINUE for the read to continue. If any other error code is returned, the LOB read is aborted.
The character set ID of the buffer data. If this value is 0 then
csid is set to the client's NLS_LANG or NLS_CHAR value, depending on the value of
csfrm. It is never assumed to be the server's character set, unless the server and client have the same settings.
The character set form of the buffer data. The
csfrm parameter must be consistent with the type of the LOB.
csfrm has two possible nonzero values:
The default value is SQLCS_IMPLICIT. If
csfrm is not specified, the default is assumed.
Reads a portion of a LOB/FILE as specified by the call into a buffer. It is an error to try to read from a
When reading or writing LOBs, the character set form (
For FILEs, the operating system file must already exist on the server, and it must have been opened by
OCILobOpen() using the input locator. Oracle must have permission to read the operating system file, and the user must have read permission on the directory object.
When using the polling mode for
OCILobRead(), the first call needs to specify values for
amtp, but on subsequent polling calls to
OCILobRead(), the user need not specify these values.
If the LOB is a
csfrm parameters are ignored.
The following apply to client-side varying-width character sets for
offsetparameters only in the first call to
OCILobRead(). On subsequent polling calls, these parameters are ignored.
lenparameter, which is input to the callback, indicates how many bytes are filled in the buffer. Check the
lenparameter during your callback processing since the entire buffer may not be filled with data.
The following applies to client-side fixed-width character sets and server-side varying-width character sets for
NCLOBvalue, look at the
amtpparameter after every call to
OCILobRead()to see how much of the buffer is filled. When the return value is in characters (as when the client-side character set is fixed-width) then convert this value to bytes and determine how much of the buffer is filled. When using callbacks, always check the
lenparameter to see how much of the buffer is filled. This value is always in bytes.
To read data in UTF-16 format, set the
csid parameter to OCI_UTF16ID. If the
csid parameter is set, it overrides the NLS_LANG environment variable.