More OCI Relational Functions, 40 of 106

OCILobRead()

Purpose

Reads a portion of a LOB/FILE, as specified by the call, into a buffer.

Syntax

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 );

Parameters

svchp (IN/OUT)

The service context handle.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

locp (IN)

A LOB/FILE locator that uniquely references the LOB/FILE. This locator must be a locator that was obtained from the server specified by svchp.

amtp (IN/OUT)

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
`BLOBs` and `BFILEs`	bytes	bytes	bytes
`CLOBs` and `NCLOBs`	characters	characters	bytes (1)

(1) The input amount refers to the number of characters to be read from the server-side CLOB/NCLOB. The output amount indicates how many bytes were read into the buffer bufp.

*amtp is the total amount of data read if:

data is not read in streamed mode (only one piece read and there is no polling or callback)
data is read in streamed mode with a callback

*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 bufp.

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.

offset (IN)

On input, this is the absolute offset from the beginning of the LOB value. For character LOBs (CLOBs, 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.

bufp (IN/OUT)

The pointer to a buffer into which the piece will be read. The length of the allocated memory is assumed to be bufl.

bufl (IN)

The length of the buffer in octets. This value will differ from the amtp value for CLOBs and for NCLOBs (csfrm=SQLCS_NCHAR) if the amtp parameter is specified in terms of characters, while the bufl parameter is specified in terms of bytes.

ctxp (IN)

The context pointer for the callback function. Can be null.

cbfp (IN)

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.

ctxp (IN)
The context for the callback function. Can be null.
bufp (IN/OUT)
A buffer pointer for the piece.
len (IN)
The length in bytes of the current piece in bufp.
piece (IN)
Which piece: OCI_FIRST_PIECE, OCI_NEXT_PIECE or OCI_LAST_PIECE.
csid (IN)

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.

csfrm (IN)

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:

SQLCS_IMPLICIT - database character set ID
SQLCS_NCHAR - NCHAR character set ID

The default value is SQLCS_IMPLICIT. If csfrm is not specified, the default is assumed.

Comments

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 NULL LOB/FILE.

Note:

When reading or writing LOBs, the character set form (csfrm) specified should match the form of the locator itself.

For FILEs, the operating system file must already exist on the server, and it must have been opened by OCILobFileOpen() or 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 offset and amtp, but on subsequent polling calls to OCILobRead(), the user need not specify these values.

If the LOB is a BLOB, the csid and csfrm parameters are ignored.

Note:

To abort an OCILobRead() operation and free the statement handle, use the OCIBreak() call.

The following apply to client-side varying-width character sets for CLOBs and NCLOBs:

When using polling mode, be sure to specify the amtp and offset parameters only in the first call to OCILobRead(). On subsequent polling calls, these parameters are ignored.
When using callbacks, the len parameter, which is input to the callback, indicates how many bytes are filled in the buffer. Check the len parameter 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 CLOBs and NCLOBs:

When reading a CLOB or NCLOB value, look at the amtp parameter 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 len parameter 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.

See Also:

For additional information on Unicode format, see "PL/SQL REF CURSORs and Nested Tables"
For more information about BFILEs, refer to the description of BFILEs in the Oracle8i Application Developer's Guide - Large Objects (LOBs)
For a code sample showing the use of LOB reads and writes, see the demonstration programs included with your Oracle installation. For additional information, refer to Appendix B, "OCI Demonstration Programs"
For general information about piecewise OCI operations, refer to "Runtime Data Allocation and Piecewise Operations"

Related Functions

OCIErrorGet(), OCILobWrite(), OCILobFileSetName(), OCILobWriteAppend()