This section describes the LOB functions which use the LOB locator. Use functions that end in "2" for all new applications.
Note:
There is another way of accessing LOBs -- using the data interface for LOBs. You can bind or define character data for aCLOB
column or RAW
data for a BLOB
column, as described in these sections:See Also:
"Binding LOB Data" for usage and examples for both INSERT
and UPDATE statements
"Defining LOB Data" for usage and examples of SELECT
statements
Function | Purpose |
---|---|
Start user duration for temporary LOB |
|
End user duration for temporary LOB |
|
Append one LOB to another |
|
Read LOB data for multiple locators. |
|
Write LOB data for multiple locators. |
|
Assign one LOB locator to another |
|
Get character set form from LOB locator |
|
Get character set ID from LOB locator |
|
Close a previously opened LOB |
|
Copy all or part of one LOB to another |
|
Copy all or part of one LOB to another. |
|
Create a temporary LOB |
|
Turn LOB buffering off |
|
Turn LOB buffering on |
|
Erase a portion of a LOB |
|
Erase a portion of a LOB. |
|
Close a previously opened |
|
Close all previously opened files |
|
Check if a file exists on the server |
|
Get directory object and file name from the LOB locator |
|
Check if file on server is open using this locator |
|
Open a |
|
Set directory object and file name in the LOB locator |
|
Flush the LOB buffer |
|
Free a temporary LOB |
|
Get the chunk size of a LOB |
|
Get length of a LOB |
|
Get length of a LOB. |
|
Get the maximum length of an internal LOB (BLOB, CLOB, or NCLOB) in bytes. |
|
Compare two LOB locators for Equality |
|
Check to see if a LOB is open |
|
Determine if a given LOB is temporary |
|
Load a LOB from a |
|
Assign one LOB locator to another |
|
Check to see if a LOB locator is initialized |
|
Open a LOB |
|
Read a portion of a LOB |
|
Read a portion of a LOB. |
|
Truncate a LOB |
|
Truncate a LOB. |
|
Write into a LOB |
|
Wrie into a LOB. |
|
Write data beginning at the end of a LOB |
|
Write data beginning at the end of a LOB. |
Note the following for parameters in the OCI LOB calls:
For fixed-width client-side character sets, the offset and amount parameters are always in characters for CLOBs
and NCLOBs
, and in bytes for BLOBs
and BFILE
s.
For varying-width client-side character sets, these rules generally apply:
amount (amtp
) parameter - When the amount parameter refers to the server-side LOB, the amount is in characters. When the amount parameter refers to the client-side buffer, the amount is in bytes.
For more information, see individual LOB calls, such as OCILobGetLength(), OCILobRead(), and OCILobWrite().
offset (offset
) parameter - Regardless of whether the client-side character set is varying-width, the offset parameter is always in characters for CLOBs
and NCLOBs
and in bytes for BLOB
s and BFILE
s.
For many of the LOB operations, regardless of the client-side character set, the amount parameter is in characters for CLOBs
and NCLOBs
. These LOB operations include OCILobCopy()
, OCILobErase()
, OCILobGetLength()
, OCILobLoadFromFile()
, and OCILobTrim()
. All these operations refer to the amount of LOB data on the server.
A streaming operation means that the LOB is read or written in pieces. Streaming can be implemented using a polling mechanism or by registering a user-defined callback.
Starts a user duration for a temporary LOB.
sword OCIDurationBegin ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, OCIDuration parent, OCIDuration *duration );
Pass as a NULL
pointer.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
An OCI service context handle. Must be non-NULL
.
The duration number of the parent duration. One of these:
An identifier unique to the newly created user duration.
This function starts a user duration. In release 8.1 or later, user durations can be used when creating temporary LOBs. A user can have multiple active user durations simultaneously. The user durations do not have to be nested. The dur
parameter is used to return a number which uniquely identifies the duration created by this call.
See Also:
"Temporary LOB Durations"Terminates a user duration for a temporary LOB.
sword OCIDurationEnd ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, OCIDuration duration );
Pass as a NULL
pointer.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
OCI service context. This should be passed as NULL
for cartridge services.
A number to identify the user duration.
This function terminates a user duration. Temporary LOBs that are allocated for the user duration are freed.
See Also:
"Temporary LOB Durations"Appends a LOB value at the end of another LOB as specified.
sword OCILobAppend ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *dst_locp, OCILobLocator *src_locp );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
An internal LOB locator uniquely referencing the destination LOB. This locator must be a locator that was obtained from the server specified by svchp
.
An internal LOB locator uniquely referencing the source LOB. This locator must be a locator that was obtained from the server specified by svchp
.
Appends a LOB value at the end of another LOB as specified. The data is copied from the source to the end of the destination. The source and destination LOBs must already exist. The destination LOB is extended to accommodate the newly written data. It is an error to extend the destination LOB beyond the maximum length allowed (4 gigabytes) or to try to copy from a NULL LOB.
The source and the destination LOB locators must be of the same type (that is, they must both be BLOBs
or both be CLOBs
). LOB buffering must not be enabled for either type of locator. This function does not accept a BFILE
locator as the source or the destination.
It is not mandatory that you wrap this LOB operation inside the Open or Close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. If you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open or close statements.
OCILobTrim(), OCILobWrite(), OCILobCopy(), OCIErrorGet(), OCILobWriteAppend()
Reads LOB data for multiple locators in one round trip. This function can be used for LOBs of size greater than or less than 4 GB.
sword OCILobArrayRead ( OCISvcCtx *svchp, OCIError *errhp, ub4 *array_iter, OCILobLocator **locp_arr, oraub8 *byte_amt_arr, oraub8 *char_amt_arr, oraub8 *offset_arr, dvoid **bufp_arr, oraub8 bufl_arr, ub1 piece, dvoid *ctxp, OCICallbackLobArrayRead (cbfp) ( dvoid *ctxp, ub4 array_iter, CONST dvoid *bufp, oraub8 lenp, ub1 piecep dvoid **changed_bufpp, oraub8 *changed_lenp ) 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.
IN - This parameter indicates the size of the LOB locator array. For polling this is relevant only for the first call and is ignored in subsequent calls.
OUT - While in polling mode, it indicates the array index of the element read from.
An array of LOB or BFILE
locators.
An array of oraub8
variables. The array size must be the same as the locator array size. The entries correspond to the amount in bytes for the locators.
IN - The number of bytes to read from the database. Used for BLOB
and BFILE
always. For CLOB and NCLOB, it is used only when the corresponding value in char_amt_arr
is zero.
OUT - The number of bytes read into the user buffer.
An array of oraub8
variables. The array size must be the same as the locator array size. The entries correspond to the amount in characters for the locators.
IN - The maximum number of characters to read into the user buffer. Ignored for BLOB
and BFILE
.
OUT - The number of characters read into the user buffer. Undefined for BLOB
and BFILE
.
An array of oraub8
variables. The array size must be the same as the locator array size. For character LOBs (CLOBs
, NCLOBs
) it is the number of characters from the beginning of the LOB; for binary LOBs or BFILE
s it is the number of bytes. The first position is 1.
An array of pointers to buffers into which the piece will be read. The array size must be the same as the locator array size.
An array of oraub8
variables indicating the buffer lengths for the buffer array. The array size must be the same as the locator array size
OCI_ONE_PIECE
- The call never assumes polling. If the amount indicated is more than the buffer length then the buffer is filled as much as possible.
For polling, pass OCI_FIRST_PIECE
the first time and OCI_NEXT_PIECE
in subsequent calls. OCI_FIRST_PIECE
should be passed while using the callback.
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 terminated.
The context for the callback function. Can be NULL
.
The index of the element read from.
A buffer pointer for the piece.
The length in bytes of the current piece in bufp
.
Which piece: OCI_FIRST_PIECE
, OCI_NEXT_PIECE
, or OCI_LAST_PIECE
.
The callback function can put the address of a new buffer if it prefers to use a new buffer for the next piece to read. The default old buffer bufp
is used if this parameter is set to NULL
.
Length of the new buffer, if provided.
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 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.
It is an error to try to read from a NULL
LOB or BFILE
.
Note:
When reading or writing LOBs, the character set form (csfrm
) specified should match the form of the locator itself.For BFILE
s, the operating system file must already exist on the server, and it must have been opened by OCILobFileOpen()
or OCILobOpen()
using the input locator. The database 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 OCILobArrayRead()
, the first call needs to specify values for offset_arr
and amt_arr
, but on subsequent polling calls to OCILobArrayRead()
, the user need not specify these values.
If the LOB is a BLOB
, the csid
and csfrm
parameters are ignored.
Note:
To terminate anOCILobArrayRead()
operation and free the statement handle, use the OCIBreak()
call.The following points apply to reading LOB data in streaming mode:
When using polling mode, be sure to specify the char_amt_arr
and byte_amt_arr
and offset_arr
parameters only in the first call to OCILobArrayRead()
. On subsequent polling calls these parameters are ignored. If both byte_amt_arr
and char_amt_arr
are set to point to zero and OCI_FIRST_PIECE
is passed, then polling mode is assumed and data is read to the end of the LOB. On output, byte_amt_arr
gives the number of bytes read in the current piece. For CLOB
s and NCLOB
s, char_amt_arr
gives the number of characters read in the current piece.
When using callbacks, the lenp
parameter, which is input to the callback, indicates how many bytes are filled in the buffer. Check the lenp
parameter during your callback processing because the entire buffer may not be filled with data.
When using polling, look at the byte_amt_arr
parameter to see how much the buffer is filled for the current piece. For CLOB
s and NCLOB
s, char_amt_arr
returns the number of characters read in the buffer as well.
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 in OCI"
For more information about BFILEs
, refer to the description of BFILEs
in the Oracle Database Application Developer's Guide - Large Objects
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 in OCI"
OCIErrorGet(), OCILobWrite2(), OCILobFileSetName(), OCILobWriteAppend2(), OCILobArrayWrite()
Writes LOB data for multiple locators in one round trip. This function can be used for LOBs of size greater than or less than 4 GB.
sword OCILobArrayWrite ( OCISvcCtx *svchp, OCIError *errhp, ub4 *array_iter, OCILobLocator **locp_arr, oraub8 *byte_amt_arr, oraub8 *char_amt_arr, oraub8 *offset_arr, dvoid **bufp_arr, oraub8 *bufl_arr, ub1 piece, dvoid *ctxp, OCICallbackLobArrayWrite (cbfp) ( dvoid *ctxp, ub4 array_iter, dvoid *bufp, oraub8 *lenp, ub1 *piecep dvoid **changed_bufpp, oraub8 *changed_lenp ) 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.
IN - This parameter indicates the size of the LOB locator array. For polling this is relevant only for the first call and is ignored in subsequent calls.
OUT - While in polling mode it indicates the array index of the element just written to.
An array of LOB locators.
An array of pointers to oraub8
variables. The array size must be the same as the locator array size. The entries correspond to the amount in bytes for the locators.
IN - The number of bytes to write to the database. Always used for BLOB
. For CLOB
and NCLOB
it is used only when char_amt_arr
is zero.
OUT - The number of bytes written to the database.
An array of pointers to oraub8
variables. The array size must be the same as the locator array size. The entries correspond to the amount in characters for the locators.
IN - The maximum number of characters to write to the database. Ignored for BLOB
.
OUT - The number of characters written to the database. Undefined for BLOB
.
An array of pointers to oraub8
variables. The array size must be the same as the locator array size. Each entry in the array is the absolute offset from the beginning of the LOB value. For character LOBs (CLOB
s, NCLOB
s) it is the number of characters from the beginning of the LOB; for BLOB
s, it is the number of bytes. The first position is 1.
An array of pointers to buffers into which the pieces for the locators will be written. The array size must be the same as the locator array size.
An array of oraub8
variables indicating the buffer lengths for the buffer array. The array size must be the same as the locator array size.
Note:
This parameter assumes an 8-bit byte. If your operating system uses a longer byte, you must adjust the value ofbufl_arr
accordingly.Which piece of the buffer is being written. The default value for this parameter is OCI_ONE_PIECE
, indicating the buffer will be written in a single piece.
The following other values are also possible for piecewise or callback mode: OCI_FIRST_PIECE
, OCI_NEXT_PIECE
and OCI_LAST_PIECE
.
The context 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 write to continue. If any other error code is returned, the LOB write is terminated.
The callback takes the following parameters:
The context for the callback function. Can be NULL
.
The index of the element written to.
A buffer pointer for the piece. This is the same as the bufp
passed as an input to the OCILobArrayWrite()
routine.
The length, in bytes, of the data in the buffer (IN), and the length in bytes of current piece in bufp
(OUT).
Which piece: OCI_NEXT_PIECE
or OCI_LAST_PIECE
.
The callback function can put the address of a new buffer if it prefers to use a new buffer for next piece to read. The default old buffer bufp
is used if this parameter is set to NULL
.
Length of the new buffer, if provided.
The character set ID of the data in the buffer. 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
.
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:
If LOB data already exists it is overwritten with the data stored in the buffer. The buffers can be written to the LOBs in a single piece with this call, or it can be provided piecewise using callbacks or a standard polling method.
Note:
When reading or writing LOBs, the character set form (csfrm
) specified should match the form of the locator itself.
The parameters piece
, csid
, and csform
are the same for all locators of the array.
When using the polling mode for OCILobArrayWrite()
, the first call needs to specify values for offset_arr
, byte_amt_arr
, and char_amt_arr
, but on subsequent polling calls to OCILobArrayWrite()
, the user need not specify these values.
If the value of the piece
parameter is OCI_FIRST_PIECE
, data may need to be provided through callbacks or polling.
If a callback function is defined in the cbfp
parameter, then this callback function will be invoked to get the next piece after a piece is written to the pipe. Each piece will be written from bufp_arr
. If no callback function is defined, then OCILobArrayWrite()
returns the OCI_NEED_DATA
error code. The application must call OCILobArrayWrite()
again to write more pieces of the LOBs. In this mode, the buffer pointer and the length can be different in each call if the pieces are of different sizes and from different locations.
A piece
value of OCI_LAST_PIECE
terminates the piecewise write, regardless of whether the polling or callback method is used.
If the amount of data passed to the database (through either input mechanism) is less than the amount specified by the byte_amt_arr
or the char_amt_arr
parameter, an ORA-22993 error is returned.
This function is valid for internal LOBs only. BFILE
s are not valid, since they are read-only. If the LOB is a BLOB
, the csid
and csfrm
parameters are ignored.
If both byte_amt_arr
and char_amt_arr
are set to point to zero amount and OCI_FIRST_PIECE
is given as input, then polling mode is assumed and data is written until you specify OCI_LAST_PIECE
. For CLOB
s and NCLOB
s, byte_amt_arr
and char_amt_arr
return the data written by each piece in terms of number of bytes and number of characters respectively. For BLOB
s byte_amt_arr
returns the number of bytes written by each piece while char_amt_arr
is undefined on output.
To write data in UTF16 format, set the csid
parameter to OCI_UTF16ID
. If the csid
parameter is set, it overrides the NLS_LANG
environment variable.
It is not mandatory that you wrap this LOB operation inside the open or close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. If you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open or close statements.
See Also:
For additional information on Unicode format, see "PL/SQL REF CURSORs and Nested Tables in OCI"
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 in OCI"
OCIErrorGet(), OCILobRead2(), OCILobAppend(), OCILobCopy(), OCILobWriteAppend2(), OCILobArrayRead()
Assigns one LOB or BFILE
locator to another.
sword OCILobAssign ( OCIEnv *envhp, OCIError *errhp, CONST OCILobLocator *src_locp, OCILobLocator **dst_locpp );
OCI environment handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
LOB or BFILE
locator to copy from.
LOB or BFILE
locator to copy to. The caller must have allocated space for the destination locator by calling OCIDescriptorAlloc()
.
Assign source locator to destination locator. After the assignment, both locators refer to the same LOB value. For internal LOBs, the source locator's LOB value gets copied to the destination locator's LOB value only when the destination locator gets stored in the table. Therefore, issuing a flush of the object containing the destination locator will copy the LOB value.
OCILobAssign()
cannot be used for temporary LOBs; it will generate an OCI_INVALID_HANDLE
error. For temporary LOBs, use OCILobLocatorAssign().
For BFILE
s, only the locator that refers to the file is copied to the table. The operating system file itself is not copied.
It is an error to assign a BFILE
locator to an internal LOB locator, and vice versa.
If the source locator is for an internal LOB that was enabled for buffering, and the source locator has been used to modify the LOB data through the LOB buffering subsystem, and the buffers have not been flushed since the write, then the source locator may not be assigned to the destination locator. This is because only one locator for each LOB may modify the LOB data through the LOB buffering subsystem.
The value of the input destination locator must have already been allocated with a call to OCIDescriptorAlloc()
. For example, assume the following declarations:
OCILobLocator *source_loc = (OCILobLocator *) 0; OCILobLocator *dest_loc = (OCILobLocator *) 0;
An application could allocate the source_loc
locator as follows:
if (OCIDescriptorAlloc((dvoid *) envhp, (dvoid **) &source_loc, (ub4) OCI_DTYPE_LOB, (size_t) 0, (dvoid **) 0)) handle_error;
Assume that it then selects a LOB from a table into the source_loc
in order to initialize it. The application must allocate the destination locator, dest_loc
, before issuing the OCILobAssign()
call to assign the value of source_loc
to dest_loc
. For example:
if (OCIDescriptorAlloc((dvoid *) envhp, (dvoid **) &dest_loc, (ub4)OCI_DTYPE_LOB, (size_t) 0, (dvoid **) 0)) handle_error; if (OCILobAssign(envhp, errhp, source_loc, &dest_loc)) handle_error;
OCIErrorGet(), OCILobIsEqual(), OCILobLocatorAssign(), OCILobLocatorIsInit(), OCILobEnableBuffering()
Gets the character set form of the LOB locator, if any.
sword OCILobCharSetForm ( OCIEnv *envhp, OCIError *errhp, CONST OCILobLocator *locp, ub1 *csfrm );
OCI environment handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
LOB locator for which to get the character set form.
Character set form of the input LOB locator. If the input locator, locp,
is for a BLOB or a BFILE
, csfrm
is set to 0 since there is no concept of a character set for binary LOBs and BFILE
s. The caller must allocate space for the csfrm
(a ub1
).
csfrm
has two possible nonzero values:
Returns the character set form of the input CLOB
or NCLOB
locator in the csfrm
output parameter.
OCIErrorGet(), OCILobCharSetId(), OCILobLocatorIsInit()
Gets the LOB locator's database character set ID of the LOB locator, if any.
sword OCILobCharSetId ( OCIEnv *envhp, OCIError *errhp, CONST OCILobLocator *locp, ub2 *csid );
OCI environment handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
LOB locator for which to get the character set ID.
Database character set ID of the input LOB locator. If the input locator is for a BLOB
or a BFILE
, csid
is set to 0 since there is no concept of a character set for binary LOBs/FILEs. The caller must allocate space for the csid
ub2
.
Returns the character set ID of the input CLOB
or NCLOB
locator in the csid
output parameter.
OCIErrorGet(), OCILobCharSetForm(), OCILobLocatorIsInit()
Closes a previously opened LOB or BFILE
.
sword OCILobClose ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
The LOB to close. The locator can refer to an internal or external LOB.
Closes a previously opened internal or external LOB. No error is returned if the BFILE
exists but is not opened. An error is returned if the internal LOB is not open.
Closing a LOB requires a round trip to the server for both internal and external LOBs. For internal LOBs, close will trigger other code that relies on the close call and for external LOBs (BFILEs
), close actually closes the server-side operating system file.
It is not mandatory that you wrap all LOB operations inside the open or close calls. However, if you open a LOB, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column. It is an error to commit the transaction before closing all opened LOBs that were opened by the transaction.
When the error is returned, the LOB is no longer marked as open, but the transaction is successfully committed. Hence, all the changes made to the LOB and non-LOB data in the transaction are committed but the domain and function-based indexing are not updated. If this happens, please rebuild your functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or c lose API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance, so if you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open/close statements.
See Also:
"Functions for Opening and Closing LOBs"OCIErrorGet(), OCILobOpen(), OCILobIsOpen()
Copies all or a portion of a LOB value into another LOB value.
sword OCILobCopy ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *dst_locp, OCILobLocator *src_locp, ub4 amount, ub4 dst_offset, ub4 src_offset );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
An internal LOB locator uniquely referencing the destination LOB. This locator must be a locator that was obtained from the server specified by svchp
.
An internal LOB locator uniquely referencing the source LOB. This locator must be a locator that was obtained from the server specified by svchp
.
The number of characters for CLOBs
or NCLOB
s; or bytes for BLOB
s to be copied from the source LOB to the destination LOB.
This is the absolute offset for the destination LOB. For character LOBs it is the number of characters from the beginning of the LOB at which to begin writing. For binary LOBs it is the number of bytes from the beginning of the LOB from which to begin writing. The offset starts at 1.
This is the absolute offset for the source LOB. For character LOBs it is the number of characters from the beginning of the LOB, for binary LOBs it is the number of bytes. Starts at 1.
Copies all or a portion of an internal LOB value into another internal LOB as specified. The data is copied from the source to the destination. The source (src_locp
) and the destination (dst_locp
) LOBs must already exist.
If the data already exists at the destination's start position, it is overwritten with the source data. If the destination's start position is beyond the end of the current data, zero-byte fillers (for BLOBs
) or spaces (for CLOBs
) are written into the destination LOB from the end of the current data to the beginning of the newly written data from the source. The destination LOB is extended to accommodate the newly written data if it extends beyond the current length of the destination LOB. It is an error to extend the destination LOB beyond the maximum length allowed (that is, 4 gigabytes) or to try to copy from a NULL LOB.
Both the source and the destination LOB locators must be of the same type (that is, they must both be BLOBs
or both be CLOBs
). LOB buffering must not be enabled for either locator.
This function does not accept a BFILE
locator as the source or the destination.
It is not mandatory that you wrap this LOB operation inside the open or close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. If you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open or close statements.
Note:
You can callOCILobGetLength()
to determine the length of the source LOB.OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy2(), OCILobWrite(), OCILobWriteAppend()
Copies all or a portion of a LOB value into another LOB value. This function must be used for LOBs of size greater than 4 GB. You can also use this function for LOBs smaller than 4 GB.
sword OCILobCopy2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *dst_locp, OCILobLocator *src_locp, oraub8 amount, oraub8 dst_offset, oraub8 src_offset );
See Also:
"OCILobCopy()"Create a temporary LOB
sword OCILobCreateTemporary(OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub2 csid, ub1 csfrm, ub1 lobtype, boolean cache, OCIDuration duration);
The OCI service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
A locator which points to the temporary LOB. You must allocate the locator using OCIDescriptorAlloc()
before passing it to this function. It does not matter whether or not this locator already points to a LOB, it will get overwritten either way.
The LOB character set ID. For Oracle8i or later, pass as OCI_DEFAULT
.
The LOB character set form of the buffer data. csfrm
has two possible nonzero values:
SQLCS_IMPLICIT
- database character set ID, to create a CLOB
. OCI_DEFAULT
can also be used to implicitly create a CLOB
.
The default value is SQLCS_IMPLICIT
.
The type of LOB to create. Valid values include:
OCI_TEMP_BLOB
- for a temporary BLOB
OCI_TEMP_CLOB
- for a temporary CLOB
or NCLOB
Pass TRUE
if the temporary LOB should be read into the cache; FALSE
, if it should not. The default is FALSE
for NOCACHE
functionality.
The duration of the temporary LOB. The following are valid values:
OCI_DURATION_SESSION
OCI_DURATION_CALL
This function creates a temporary LOB and its corresponding index in the user's temporary tablespace.
When this function is complete, the locp
parameter points to an empty temporary LOB whose length is zero.
The lifetime of the temporary LOB is determined by the duration
parameter. At the end of its duration the temporary LOB is freed. An application can free a temporary LOB sooner with the OCILobFreeTemporary()
call.
If the LOB is a BLOB
, the csid
and csfrm
parameters are ignored.
See Also:
For more information about temporary LOBs and their durations, refer to "Temporary LOB Support".OCILobFreeTemporary(), OCILobIsTemporary(), OCIDescriptorAlloc(), OCIErrorGet()
Disable LOB buffering for the input locator.
sword OCILobDisableBuffering ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
An internal LOB locator uniquely referencing the LOB.
Disables LOB buffering for the input internal LOB locator. The next time data is read from or written to the LOB through the input locator, the LOB buffering subsystem is not used. Note that this call does not implicitly flush the changes made in the buffering subsystem. The user must explicitly call OCILobFlushBuffer()
to do this.
This function does not accept a BFILE
locator.
OCILobEnableBuffering(), OCIErrorGet(), OCILobFlushBuffer()
Enable LOB buffering for the input locator.
sword OCILobEnableBuffering ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
An internal LOB locator uniquely referencing the LOB.
Enables LOB buffering for the input internal LOB locator. The next time data is read from or written to the LOB through the input locator, the LOB buffering subsystem is used.
If LOB buffering is enabled for a locator and that locator is passed to one of the following routines, an error is returned: OCILobAppend()
, OCILobCopy()
, OCILobErase()
, OCILobGetLength()
, OCILobLoadFromFile()
, OCILobTrim()
, or OCILobWriteAppend()
.
This function does not accept a BFILE
locator.
OCILobDisableBuffering(), OCIErrorGet(), OCILobWrite(), OCILobRead(), OCILobFlushBuffer(), OCILobWriteAppend()
Erases a specified portion of the internal LOB data starting at a specified offset.
sword OCILobErase ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub4 *amount, ub4 offset );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
An internal LOB locator that uniquely references the LOB. This locator must be a locator that was obtained from the server specified by svchp
.
The number of characters for CLOB
s orNCLOB
s, or bytes for BLOB
s, to erase. On IN, the value signifies the number of characters or bytes to erase. On OUT, the value identifies the actual number of characters or bytes erased.
Absolute offset in characters for CLOB
s or NCLOB
s, or bytes for BLOB
s, from the beginning of the LOB value from which to start erasing data. Starts at 1.
The actual number of characters or bytes erased is returned. For BLOBs
, erasing means that zero-byte fillers overwrite the existing LOB value. For CLOBs
, erasing means that spaces overwrite the existing LOB value.
This function is valid only for internal LOBs; BFILE
s are not allowed.
It is not mandatory that you wrap this LOB operation inside the open or close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. If you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open or close statements.
OCIErrorGet(),OCILobErase2(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobWrite(), OCILobWriteAppend()
Erases a specified portion of the internal LOB data starting at a specified offset. This function must be used for LOBs of size greater than 4 GB. You can also use this function for LOBs smaller than 4 GB.
sword OCILobErase2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *amount, oraub8 offset );
See Also:
"OCILobErase()"Closes a previously opened BFILE
.
sword OCILobFileClose ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *filep );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
A pointer to a BFILE
locator that refers to the BFILE
to be closed.
Closes a previously opened BFILE
. It is an error if this function is called for an internal LOB. No error is returned if the BFILE
exists but is not opened.
This function is only meaningful the first time it is called for a particular BFILE
locator. Subsequent calls to this function using the same BFILE
locator have no effect.
See Also:
For more information aboutBFILE
s, refer to the description of BFILEs
in the Oracle Database Application Developer's Guide - Large Objects.OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(), OCILobFileExists(), OCILobFileIsOpen(), OCILobFileOpen(), OCILobOpen(), OCILobIsOpen()
Closes all open BFILE
s on a given service context.
sword OCILobFileCLoseAll ( OCISvcCtx *svchp, OCIError *errhp );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
Closes all open BFILE
s on a given service context.
See Also:
For more information aboutBFILE
s, refer to the description of BBFILEs in the Oracle Database Application Developer's Guide - Large Objects.OCILobFileClose(), OCIErrorGet(), OCILobFileExists(), OCILobFileIsOpen()
Tests to see if the BFILE
exists on the server's operating system.
sword OCILobFileExists ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *filep, boolean *flag );
The OCI service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
Pointer to the BFILE
locator that refers to the file.
Returns TRUE
if the BFILE
exists on the server; FALSE
if it does not.
Checks to see if the BFILE
exists on the server's file system. It is an error to call this function for an internal LOB.
See Also:
For more information aboutBFILE
s, refer to the description of BFILEs
in the Oracle Database Application Developer's Guide - Large Objects.OCIErrorGet(), OCILobFileClose(), OCILobFileCloseAll(), OCILobFileIsOpen(), OCILobOpen(), OCILobIsOpen()
Gets the BFILE
locator's directory object and file name.
sword OCILobFileGetName ( OCIEnv *envhp, OCIError *errhp, CONST OCILobLocator *filep, text *dir_alias, ub2 *d_length, text *filename, ub2 *f_length );
OCI environment handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
BFILE
locator for which to get the directory object and file name.
Buffer into which the directory object name is placed. This can be in UTF-16. You must allocate enough space for the directory object name. The maximum length for the directory object is 30 bytes.
Serves the following purposes (can be in codepoint for Unicode, or bytes):
IN: length of the input dir_alias
string
OUT: length of the returned dir_alias
string
Buffer into which the file name is placed. You must allocate enough space for the file name. The maximum length for the file name is 255 bytes.
Serves the following purposes (in number of bytes):
IN: length of the input filename
buffer
OUT: length of the returned filename
string
Returns the directory object and file name associated with this BFILE
locator. The environment handle determines whether or not it is in Unicode. It is an error to call this function for an internal LOB.
See Also:
For more information aboutBFILE
s, refer to the description of BFILE
s in the Oracle Database Application Developer's Guide - Large ObjectsOCILobFileSetName(), OCIErrorGet()
Tests to see if the BFILE
is open
sword OCILobFileIsOpen ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *filep, boolean *flag );
The OCI service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
Pointer to the BFILE
locator being examined.
Returns TRUE
if the BFILE
was opened using this particular locator; FALSE
if it was not.
Checks to see if a file on the server was opened with the filep
BFILE
locator. It is an error to call this function for an internal LOB.
If the input BFILE
locator was never passed to the OCILobFileOpen()
or OCILobOpen()
command, the file is considered not to be opened by this locator. However, a different locator may have the file open. Openness is associated with a particular locator.
See Also:
For more information aboutBFILE
s, refer to the description of BFILEs
in the Oracle Database Application Developer's Guide - Large ObjectsOCIErrorGet(), OCILobClose(), OCILobFileCloseAll(), OCILobFileExists(), OCILobFileClose(), OCILobFileOpen(), OCILobOpen(), OCILobIsOpen()
Opens a BFILE
on the file system of the server for read-only access.
sword OCILobFileOpen ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *filep, ub1 mode );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
The BFILE
to open. It is an error if the locator does not refer to a BFILE
.
Mode in which to open the file. The only valid mode is OCI_FILE_READONLY
.
Opens a BFILE
on the file system of the server. The BFILE
can be opened for read-only access. BFILE
s may not be written through Oracle. It is an error to call this function for an internal LOB.
This function is only meaningful the first time it is called for a particular BFILE
locator. Subsequent calls to this function using the same BFILE
locator have no effect.
See Also:
For more information aboutBFILE
s, refer to the description of BFILEs
in the Oracle Database Application Developer's Guide - Large ObjectsOCIErrorGet(), OCILobClose(), OCILobFileCloseAll(), OCILobFileExists(), OCILobFileClose(), OCILobFileIsOpen(), OCILobOpen(), OCILobIsOpen()
Sets the directory object and file name in the BFILE
locator.
sword OCILobFileSetName ( OCIEnv *envhp, OCIError *errhp, OCILobLocator **filepp, CONST text *dir_alias, ub2 d_length, CONST text *filename, ub2 f_length );
OCI environment handle. Contains UTF-16 setting.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
Pointer to the BFILE
locator for which to set the directory object and file name.
Buffer that contains the directory object name (must be in the encoding specified by the charset
parameter of a previous call to OCIEnvNlsCreate()
) to set in the BFILE
locator.
Length of the input dir_alias
parameter. In bytes.
Buffer that contains the file name (must be in the encoding specified by the charset
parameter of a previous call to OCIEnvNlsCreate()
) to set in the BFILE
locator.
Length of the input filename
parameter. In bytes.
It is an error to call this function for an internal LOB.
See Also:
For more information aboutBFILE
s, refer to the description of BFILEs
in tthe Oracle Database Application Developer's Guide - Large ObjectsOCILobFileGetName(), OCIErrorGet()
Flush/write all buffers for this lob to the server.
sword OCILobFlushBuffer ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp ub4 flag );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
An internal locator uniquely referencing the LOB.
When set to OCI_LOB_BUFFER_FREE
, the buffer resources for the LOB are freed after the flush. See Comments section.
Flushes to the server, changes made to the buffering subsystem that are associated with the LOB referenced by the input locator. This routine will actually write the data in the buffer to the LOB in the database. LOB buffering must have already been enabled for the input LOB locator.
The flush operation, by default, does not free the buffer resources for reallocation to another buffered LOB operation. However, if you want to free the buffer explicitly, you can set the flag parameter to OCI_LOB_BUFFER_FREE
.
If the client application intends to read the buffer value after the flush and knows in advance that the current value in the buffer is the desired value, there is no need to reread the data from the server.
The effects of freeing the buffer are mostly transparent to the user, except that the next access to the same range in the LOB involves a round trip to the server, and also the cost of acquiring buffer resources and initializing it with the data read from the LOB. This option is intended for client environments that have low on-board memory.
OCILobEnableBuffering(), OCIErrorGet(), OCILobWrite(), OCILobRead(), OCILobDisableBuffering(), OCILobWriteAppend()
Free a temporary LOB
sword OCILobFreeTemporary( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp);
The OCI service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
A locator uniquely referencing the LOB to be freed.
This function frees the contents of the temporary LOB to which this locator points. Note that the locator itself is not freed until OCIDescriptorFree()
is called.
This function returns an error if the LOB locator passed in the locp
parameter does not point to a temporary LOB, which might be due to any of the following:
It points to a permanent LOB
It pointed to a temporary LOB which has already been freed
It has never pointed to anything
OCILobCreateTemporary(), OCILobIsTemporary(), OCIErrorGet()
Gets the chunk size of a LOB.
sword OCILobGetChunkSize ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub4 *chunk_size );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
The internal LOB for which to get the usable chunk size.
The amount of a chunk's space that is used to store the internal LOB value. This is the amount that users should use when reading or writing the LOB value. If possible, users should start their writes at chunk boundaries, such as the beginning of a chunk, and write a chunk at a time.
chunk_size
will be returned in terms of bytes for BLOBs
and in terms of characters for CLOBs
and NCLOBs
. For varying width character sets, the value will be the number of Unicode characters that fit in a chunk.
When creating a table that contains an internal LOB, the user can specify the chunking factor, which can be a multiple of Oracle blocks. This corresponds to the chunk size used by the LOB data layer when accessing and modifying the LOB value. Part of the chunk is used to store system-related information and the rest stores the LOB value. This function returns the amount of space used in the LOB chunk to store the LOB value. Performance will be improved if the application issues read or write requests using a multiple of this chunk size. For writes, there is an added benefit since LOB chunks are versioned and, if all writes are done on a chunk basis, no extra or excess versioning is done nor duplicated. Users could batch up the write until they have enough for a chunk instead of issuing several write calls for the same chunk.
See Also:
"Improving LOB Read/Write Performance"OCIErrorGet(), OCILobGetStorageLimit(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobWrite(), OCILobWriteAppend()
Gets the length of a LOB.
sword OCILobGetLength ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub4 *lenp );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
A LOB locator that uniquely references the LOB. For internal LOBs, this locator must be a locator that was obtained from the server specified by svchp
. For BFILE
s, the locator can be set by OCILobFileSetName()
, by a SELECT
statement, or by OCIObjectPin()
.
On output, it is the length of the LOB if the LOB is not NULL
. For character LOBs, it is the number of characters, for binary LOBs and BFILEs
it is the number of bytes in the LOB.
Gets the length of a LOB. If the LOB is NULL
, the length is undefined. The length of a BFILE
includes the EOF, if it exists. The length of an empty internal LOB is zero.
Regardless of whether the client-side character set is varying-width, the output length is in characters for CLOBs
and NCLOBs
, and in bytes for BLOBs
and BFILEs
.
Note:
Any zero-byte or space fillers in the LOB written by previous calls toOCILobErase()
or OCILobWrite2()
are also included in the length count.OCIErrorGet(), OCILobFileSetName(),OCILobGetLength2(), OCILobRead(), OCILobWrite(), OCILobCopy(), OCILobAppend(), OCILobLoadFromFile(), OCILobWriteAppend()
Gets the length of a LOB. This function must be used for LOBs of size greater than 4 GB. You can also use this function for LOBs smaller than 4 GB.
sword OCILobGetLength2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *lenp );
See Also:
OCILobGetLength()Gets the maximum length of an internal LOB (BLOB, CLOB, or NCLOB) in bytes.
sword OCILobGetStorageLimit ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *limitp );
The service context handle.
An error handle that you can pass to OCIError()
for diagnostic information in the event iof an error.
A LOB locator that uniquely references the LOB. The locator must be one that was obtained from the server specified by svchp
.
The maximum length of the LOB (in bytes) that can be stored in the database.
Because block size ranges from 2KB to 32KB, the maximum LOB size ranges from 8 terabytes to 128 terabytes.
See Also:
"Using LOBs of Size Greater than 4 GB"Compares two LOB or BFILE
locators for equality.
sword OCILobIsEqual ( OCIEnv *envhp, CONST OCILobLocator *x, CONST OCILobLocator *y, boolean *is_equal );
The OCI environment handle.
LOB locator to compare.
LOB locator to compare.
TRUE, if the LOB locators are equal; FALSE if they are not.
Compares the given LOB or BFILE
locators for equality. Two LOB or BFILE
locators are equal if and only if they both refer to the same LOB or BFILE
value.
Two NULL
locators are considered not equal by this function.
OCILobAssign(), OCILobLocatorIsInit()
Tests whether a LOB or BFILE
is open.
sword OCILobIsOpen ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, boolean *flag );
The service context handle.
An error handle which can be passed to OCIErrorGet()
for diagnostic information in the event of an error.
Pointer to the LOB locator being examined. The locator can refer to an internal or external LOB.
Returns TRUE
if the internal LOB is open or if the BFILE
was opened using the input locator. Returns FALSE
if it was not.
Checks to see if the internal LOB is open or if the BFILE
was already opened using the input locator.
If the input BFILE
locator was never passed to OCILobOpen()
or OCILobFileOpen()
, the BFILE
is considered not to be opened by this BFILE
locator. However, a different BFILE
locator may have opened the BFILE
. More than one open can be performed on the same BFILE
using different locators. In other words, openness is associated with a specific locator for BFILEs
.
Openness is associated with the LOB, not with the locator. If locator1
opened the LOB then locator2
also sees the LOB as open.
For internal LOBs, this call requires a server round trip because it checks the state on the server to see if the LOB is indeed open. For external LOBs (BFILEs
), this call also requires a round trip because the actual operating system file on the server side must be checked to see if it is actually open.
See Also:
"Functions for Opening and Closing LOBs"OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(), OCILobFileExists(), OCILobFileClose(), OCILobFileIsOpen(), OCILobFileOpen(), OCILobOpen()
Tests if a locator points to a temporary LOB
sword OCILobIsTemporary(OCIEnv *envhp, OCIError *errhp, OCILobLocator *locp, boolean *is_temporary);
The OCI environment handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
The locator to test.
Returns TRUE if the LOB locator points to a temporary LOB; FALSE if it does not.
This function tests a locator to determine if it points to a temporary LOB. If so, is_temporary
is set to TRUE. If not, is_temporary
is set to FALSE.
OCILobCreateTemporary(), OCILobFreeTemporary()
Load and copy all or a portion of the file into an internal LOB.
sword OCILobLoadFromFile ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *dst_locp, OCILobLocator *src_locp, ub4 amount, ub4 dst_offset, ub4 src_offset );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
A locator uniquely referencing the destination internal LOB which may be of type BLOB, CLOB, or NCLOB.
A locator uniquely referencing the source BFILE
.
The number of bytes to be loaded.
This is the absolute offset for the destination LOB. For character LOBs it is the number of characters from the beginning of the LOB at which to begin writing. For binary LOBs it is the number of bytes from the beginning of the LOB from which to begin reading. The offset starts at 1.
This is the absolute offset for the source BFILE
. It is the number of bytes from the beginning of the BFILE
. The offset starts at 1.
Loads and copies a portion or all of a BFILE
value into an internal LOB as specified. The data is copied from the source BFILE
to the destination internal LOB (BLOB
or CLOB
). No character set conversions are performed when copying the BFILE
data to a CLOB
or NCLOB
. Also, when binary data is loaded into a BLOB
, no character set conversions are performed. Therefore, the BFILE
data must already be in the same character set as the LOB in the database. No error checking is performed to verify this.
The source (src_locp
) and the destination (dst_locp
) LOBs must already exist. If the data already exists at the destination's start position, it is overwritten with the source data. If the destination's start position is beyond the end of the current data, zero-byte fillers (for BLOBs
) or spaces (for CLOBs
) are written into the destination LOB from the end of the data to the beginning of the newly written data from the source. The destination LOB is extended to accommodate the newly written data if it extends beyond the current length of the destination LOB.
It is an error to extend the destination LOB beyond the maximum length allowed (4 gigabytes) or to try to copy from a NULL BFILE
.
It is not mandatory that you wrap this LOB operation inside the open or close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. If you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open or close statements.
OCIErrorGet(), OCILobAppend(), OCILobWrite(), OCILobTrim(), OCILobCopy(), OCILobGetLength(), OCILobLoadFromFile2(), OCILobWriteAppend()
Load and copy all or a portion of the file into an internal LOB. This function must be used for LOBs of size greater than 4 GB. You can also use this function for LOBs smaller than 4 GB.
sword OCILobLoadFromFile2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *dst_locp, OCILobLocator *src_locp, oraub8 amount, oraub8 dst_offset, oraub8 src_offset );
See Also:
OCILobLoadFromFile()Assigns one LOB or BFILE
locator to another.
sword OCILobLocatorAssign ( OCISvcCtx *svchp, OCIError *errhp, CONST OCILobLocator *src_locp, OCILobLocator **dst_locpp );
The OCI service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
The LOB/BFILE
locator to copy from.
The LOB/BFILE
locator to copy to. The caller must allocate space for the OCILobLocator by calling OCIDescriptorAlloc()
.
This call assigns the source locator to the destination locator. After the assignment, both locators refer to the same LOB data. For internal LOBs, the source locator's LOB data gets copied to the destination locator's LOB data only when the destination locator gets stored in the table. Therefore, issuing a flush of the object containing the destination locator copies the LOB data. For BFILE
s only the locator that refers to the OS file is copied to the table; the OS file is not copied.
Note that this call is similar to OCILobAssign()
but OCILobLocatorAssign()
takes an OCI service handle pointer instead of an OCI environment handle pointer. Also, OCILobLocatorAssign()
can be used for temporary LOBs and OCILobAssign()
cannot be used for temporary LOBs.
Note:
If theOCILobLocatorAssign()
function fails, the target locator will not be restored to its previous state. The target locator should not be used in subsequent operations unless it is reinitialized.If the destination locator is for a temporary LOB, the destination temporary LOB is freed before assigning the source LOB locator to it.
If the source LOB locator refers to a temporary LOB, the destination will be made into a temporary LOB too. The source and the destination will conceptually be different temporary LOBs. In the OCI_DEFAULT
mode, the source temporary LOB is deep copied and a destination locator is created to refer to the new deep copy of the temporary LOB. Hence OCILobIsEqual()
will return FALSE
after the OCILobLocatorAssign()
call. However, in the OCI_OBJECT
mode, an optimization is made to minimize the number of deep copies, so the source and destination locators will point to the same LOB until any modification is made through either LOB locator. Hence OCILobIsEqual()
will return TRUE right after OCILobLocatorAssign()
until the first modification. In both these cases, after the OCILobLocatorAssign()
, any changes to the source or the destination will not reflect in the other (that is, destination or source) LOB. If you want the source and the destination to point to the same LOB and want your changes to reflect in the other, then you must use the equal sign to ensure that two LOB locator pointers refer to the same LOB locator.
OCIErrorGet(), OCILobAssign(), OCILobIsEqual(), OCILobLocatorIsInit()
Tests to see if a given LOB or BFILE
locator is initialized.
sword OCILobLocatorIsInit ( OCIEnv *envhp, OCIError *errhp, CONST OCILobLocator *locp, boolean *is_initialized );
OCI environment handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
The LOB or BFILE
locator being tested
Returns TRUE if the given LOB or BFILE
locator is initialized; FALSE if it is not.
Tests to see if a given LOB or BFILE
locator is initialized.
Internal LOB locators can be initialized by one of the following methods:
selecting a non-NULL
LOB into the locator,
pinning an object that contains a non-NULL
LOB attribute by OCIObjectPin()
setting the locator to empty by OCIAttrSet()
See Also:
"LOB Locator Attributes"BFILE
locators can be initialized by one of the following methods:
selecting a non-NULL
BFILE
into the locator
pinning an object that contains a non-NULL
BFILE
attribute by OCIObjectPin()
calling OCILobFileSetName()
OCIErrorGet(), OCILobIsEqual()
Opens a LOB, internal or external, in the indicated mode.
sword OCILobOpen ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub1 mode );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
The LOB to open. The locator can refer to an internal or external LOB.
The mode in which to open the LOB or BFILE
. In Oracle8i or later, valid modes for LOBs are OCI_LOB_READONLY
and OCI_LOB_READWRITE
. Note that OCI_FILE_READONLY
exists as input to OCILobFileOpen()
. OCI_FILE_READONLY
can be used with OCILobOpen()
if the input locator is for a BFILE
.
It is an error to open the same LOB twice. BFILEs
cannot be opened in read/write mode. Note that if the LOB or BFILE
was opened in read-only mode and the user tries to write to the LOB or BFILE
, an error will be returned.
Opening a LOB requires a round trip to the server for both internal and external LOBs. For internal LOBs, the open will trigger other code that relies on the open call. For external LOBs (BFILEs
), open requires a round trip because the actual operating system file on the server side is being opened.
It is not necessary to open a LOB in order to perform operations on it. When using function-based indexes, extensible indexes or context, and making more than one call to update or write to the LOB, you should first call OCILobOpen()
, then update the LOB as many times as you want, and finally call OCILobClose()
. This sequence
of operations will ensure that the indexes are only updated once at the end of all the write operations instead of once for each write operation.
It is not mandatory that you wrap all LOB operations inside the Open and Close calls. However, if you open a LOB, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column. It is an error to commit the transaction before closing all opened LOBs that were opened by the transaction.
When the error is returned, the LOB is no longer marked as open, but the transaction is successfully committed. Hence, all the changes made to the LOB and non-LOB data in the transaction are committed but the domain and function-based indexing are not updated. If this happens, please rebuild your functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance, so if you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open or close statements.
See Also:
"Functions for Opening and Closing LOBs"OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(), OCILobFileExists(), OCILobFileClose(), OCILobFileIsOpen(), OCILobFileOpen(), OCILobIsOpen()
Reads a portion of a LOB or BFILE
, 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 or BFILE
locator that uniquely references the LOB or BFILE
. This locator must be a locator that was obtained from the server specified by svchp
.
The value in amtp
is the amount in either bytes or characters, as shown in this table:
Table 16-4 Characters or Bytes in amtp
LOB or BFILE | Input | Output with fixed-width client-side character set | Output with varying-width client-side character set |
---|---|---|---|
|
bytes |
bytes |
bytes |
|
characters |
characters |
bytes (1) |
(1) The input amount refers to the number of characters to be read from the server-side CLOB
or 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.
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 or BFILE
s 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 bufl
.
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.
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 terminated.
The context for the callback function. Can be NULL
.
A buffer pointer for the piece.
The length in bytes of the current piece in bufp
.
Which piece: OCI_FIRST_PIECE
, OCI_NEXT_PIECE
, or OCI_LAST_PIECE
.
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 or BFILE
as specified by the call into a buffer. It is an error to try to read from a NULL
LOB or BFILE
.
Note:
When reading or writing LOBs, the character set form (csfrm
) specified should match the form of the locator itself.For BFILE
s, 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 terminate anOCILobRead()
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 in OCI"
For more information about BFILEs
, refer to the description of BFILEs
in the Oracle Database Application Developer's Guide - Large Objects
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 in OCI"
OCIErrorGet(),OCILobRead2(), OCILobWrite(), OCILobFileSetName(), OCILobWriteAppend()
Reads a portion of a LOB or BFILE
, as specified by the call, into a buffer. This function must be used for LOBs of size greater than 4 GB. You can also use this function for LOBs smaller than 4 GB.
sword OCILobRead2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *byte_amtp, oraub8 *char_amtp, oraub8 offset, dvoid *bufp, oraub8 bufl, ub1 piece, dvoid *ctxp, OCICallbackLobRead2 (cbfp) ( dvoid *ctxp, CONST dvoid *bufp, oraub8 lenp, ub1 piecep dvoid **changed_bufpp, oraub8 *changed_lenp ) 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 or BFILE
locator that uniquely references the LOB or BFILE
. This locator must be a locator that was obtained from the server specified by svchp
.
IN - The number of bytes to read from the database. Used for BLOB
and BFILE
always. For CLOB and NCLOB, it is used only when char_amtp
is zero.
OUT - The number of bytes read into the user buffer.
IN - The maximum number of characters to read into the user buffer. Ignored for BLOB
and BFILE
.
OUT - The number of characters read into the user buffer. Undefined for BLOB
and BFILE
.
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 or BFILE
s 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 bufl
.
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.
OCI_ONE_PIECE
- The call never assumes polling. If the amount indicated is more than the buffer length then the buffer is filled as much as possible.
For polling, pass OCI_FIRST_PIECE
the first time and OCI_NEXT_PIECE
in subsequent calls. OCI_FIRST_PIECE
should be passed while using the callback.
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 terminated.
The context for the callback function. Can be NULL
.
A buffer pointer for the piece.
The length in bytes of the current piece in bufp
.
Which piece: OCI_FIRST_PIECE
, OCI_NEXT_PIECE
, or OCI_LAST_PIECE
.
The callback function can put the address of a new buffer if it prefers to use a new buffer for the next piece to read. The default old buffer bufp
is used if this parameter is set to NULL
.
Length of the new buffer, if provided.
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 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 or BFILE
as specified by the call into a buffer. It is an error to try to read from a NULL
LOB or BFILE
.
Note:
When reading or writing LOBs, the character set form (csfrm
) specified should match the form of the locator itself.For BFILE
s, 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 OCILobRead2()
, the first call needs to specify values for offset
and amtp
, but on subsequent polling calls to OCILobRead2()
, the user need not specify these values.
If the LOB is a BLOB
, the csid
and csfrm
parameters are ignored.
Note:
To terminate anOCILobRead2()
operation and free the statement handle, use the OCIBreak()
call.The following points applly to reading LOB data in streaming mode:
When using polling mode, be sure to specify the char_amtp
and byte_amtp
and offset parameters only in the first call to OCILobRead2()
. On subsequent polling calls these parameters are ignored. If both byte_amtp
and char_amtp
are set to point to zero and OCI_FIRST_PIECE
is passed then polling mode is assumed and data is read till the end of the LOB. On output, byte_amtp
gives the number of bytes read in the current piece. For CLOB
s and NCLOB
s, char_amtp
gives the number of characters read in the current piece.
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 because the entire buffer may not be filled with data.
When using polling, look at the byte_amtp
parameter to see how much the buffer is filled for the current piece. For CLOB
s and NCLOB
s, char_amtp
returns the number of characters read in the buffer as well.
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 in OCI"
For more information about BFILEs
, refer to the description of BFILEs
in the Oracle Database Application Developer's Guide - Large Objects
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 in OCI"
OCIErrorGet(), OCILobWrite2(), OCILobFileSetName(), OCILobWriteAppend2()
Truncates the LOB value to a shorter length.
sword OCILobTrim ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub4 newlen );
The service context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
An internal LOB locator that uniquely references the LOB. This locator must be a locator that was obtained from the server specified by svchp
.
The new length of the LOB value, which must be less than or equal to the current length. For character LOBs, it is the number of characters, for binary LOBs and BFILE
s it is the number of bytes in the LOB.
This function trims the LOB data to a specified shorter length. The function returns an error if newlen
is greater than the current LOB length. This function is valid only for internal LOBs. BFILE
s are not allowed.
It is not mandatory that you wrap this LOB operation inside the open or close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. If you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open or close statements.
OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobErase(),OCILobTrim2(), OCILobWrite(), OCILobWriteAppend()
Truncates the LOB value to a shorter length. This function must be used for LOBs of size greater than 4 GB. You can also use this function for LOBs smaller than 4 GB.
sword OCILobTrim2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 newlen );
See Also:
OCILobTrim()Writes a buffer into a LOB
sword OCILobWrite ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub4 *amtp, ub4 offset, dvoid *bufp, ub4 buflen, ub1 piece, dvoid *ctxp, OCICallbackLobWrite (cbfp) ( dvoid *ctxp, dvoid *bufp, ub4 *lenp, ub1 *piecep ) 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.
An internal LOB locator that uniquely references the LOB. This locator must be a locator that was obtained from the server specified by svchp
.
The value in amtp
is the amount in either bytes or characters, as shown in this table:
Table 16-5 Characters or Bytes in amtp
LOB or BFILE | Input with fixed-width client-side character set | Input with varying-width client-side character set | Output |
---|---|---|---|
|
bytes |
bytes |
bytes |
|
characters |
bytes (1) |
characters |
(1) The input amount refers to the number of bytes of data that the user wants to write into the LOB and not the number of bytes in the bufp
, which is specified by buflen
. In the case where data is written in pieces, the amount of bytes to write may be larger than the buflen
. The output amount refers to the number of characters written into the server-side CLOB
or NCLOB
.
This should always be a non-NULL
pointer. If you want to specify write-until-end-of-file, then you must declare a variable, set it equal to zero, and pass its address for this parameter.
If the amount is specified on input, and the data is written in pieces, *amtp
will contain the total length of the pieces written at the end of the call (last piece written) and is undefined in between. Note that it is different from the piecewise read case. An error is returned if that amount is not sent to the server.
If amtp
is zero, then streaming mode is assumed, and data is written until the user specifies OCI_LAST_PIECE
.
On input, it is the absolute offset from the beginning of the LOB value. For character LOBs it is the number of characters from the beginning of the LOB, for binary LOBs 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 from which the piece will be written. The length of the data in the buffer is assumed to be the value passed in buflen
. Even if the data is being written in pieces using the polling method, bufp
must contain the first piece of the LOB when this call is invoked. If a callback is provided, bufp
must not be used to provide data or an error will result.
The length, in bytes, of the data in the buffer. This value will differ from the amtp
value for CLOBs
and NCLOBs
if the amtp
parameter is specified in terms of characters, while the buflen
parameter is specified in terms of bytes.
Note:
This parameter assumes an 8-bit byte. If your operating system uses a longer byte, you must adjust the value ofbuflen
accordingly.Which piece of the buffer is being written. The default value for this parameter is OCI_ONE_PIECE
, indicating the buffer will be written in a single piece.
The following other values are also possible for piecewise or callback mode: OCI_FIRST_PIECE
, OCI_NEXT_PIECE
and OCI_LAST_PIECE
.
The context for the callback function. Can be NULL
.
A callback that may be registered to be called for each piece in a piecewise write. If this is NULL
, the standard polling method will be used.
The callback function must return OCI_CONTINUE
for the write to continue. If any other error code is returned, the LOB write is terminated. The callback takes the following parameters:
The context for the callback function. Can be NULL
.
A buffer pointer for the piece. This is the same as the bufp
passed as an input to the OCILobWrite()
routine.
The length, in bytes, of the data in the buffer (IN), and the length in bytes of current piece in bufp
(OUT).
Which piece: OCI_NEXT_PIECE
or OCI_LAST_PIECE
.
The character set ID of the data in the buffer. 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
.
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
.
Writes a buffer into an internal LOB as specified. If LOB data already exists it is overwritten with the data stored in the buffer. The buffer can be written to the LOB in a single piece with this call, or it can be provided piecewise using callbacks or a standard polling method.
Note:
When reading or writing LOBs, the character set form (csfrm
) specified should match the form of the locator itself.When using the polling mode for OCILobWrite()
, the first call needs to specify values for offset
and amtp
, but on subsequent polling calls to OCILobWrite()
, the user need not specify these values.
If the value of the piece
parameter is OCI_FIRST_PIECE
, data may need to be provided through callbacks or polling.
If a callback function is defined in the cbfp
parameter, then this callback function will be invoked to get the next piece after a piece is written to the pipe. Each piece will be written from bufp
. If no callback function is defined, then OCILobWrite()
returns the OCI_NEED_DATA
error code. The application must call OCILobWrite()
again to write more pieces of the LOB. In this mode, the buffer pointer and the length can be different in each call if the pieces are of different sizes and from different locations.
A piece
value of OCI_LAST_PIECE
terminates the piecewise write, regardless of whether the polling or callback method is used.
If the amount of data passed to Oracle (through either input mechanism) is less than the amount specified by the amtp
parameter, an ORA-22993 error is returned.
This function is valid for internal LOBs only. BFILE
s are not allowed, since they are read-only. If the LOB is a BLOB
, the csid
and csfrm
parameters are ignored.
If the client-side character set is varying-width, then the input amount is in bytes and the output amount is in characters for CLOBs
and NCLOBs
. The input amount refers to the number of bytes of data that the user wants to write into the LOB and not the number of bytes in the bufp
, which is specified by buflen
. In the case where data is written in pieces, the amount of bytes to write may be larger than the buflen
. The output amount refers to the number of characters written into the server-side CLOB
or NCLOB
.
To write data in UTF16 format, set the csid
parameter to OCI_UTF16ID
. If the csid
parameter is set, it overrides the NLS_LANG
environment variable.
It is not mandatory that you wrap this LOB operation inside the open or close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. If you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open or close statements.
See Also:
For additional information on Unicode format, see "PL/SQL REF CURSORs and Nested Tables in OCI"
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 in OCI"
OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobWriteAppend(), OCILobWrite2()
Writes a buffer into a LOB. This function must be used for LOBs of size greater than 4 GB. You can also use this function for LOBs smaller than 4 GB.
sword OCILobWrite2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *byte_amtp, oraub8 *char_amtp, oraub8 offset, dvoid *bufp, oraub8 buflen, ub1 piece, dvoid *ctxp, OCICallbackLobWrite2 (cbfp) ( dvoid *ctxp, dvoid *bufp, oraub8 *lenp, ub1 *piecep dvoid **changed_bufpp, oraub8 *changed_lenp ) 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.
An internal LOB locator that uniquely references the LOB. This locator must be a locator that was obtained from the server specified by svchp
.
IN - The number of bytes to write to the database. Always used for BLOB
. For CLOB
and NCLOB
it is used only when char_amtp
is zero.
OUT - The number of bytes written to the database. In polling mode, it is the length of the piece, in bytes, just written.
IN - The maximum number of characters to write to the database. Ignored for BLOB
.
OUT - The number of characters written to the database. Undefined for BLOB
. In polling mode, it is the length of the piece, in characters, just written.
On input, it is the absolute offset from the beginning of the LOB value. For character LOBs it is the number of characters from the beginning of the LOB, for binary LOBs 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 from which the piece will be written. The length of the data in the buffer is assumed to be the value passed in buflen
. Even if the data is being written in pieces using the polling method, bufp
must contain the first piece of the LOB when this call is invoked. If a callback is provided, bufp
must not be used to provide data or an error will result.
The length, in bytes, of the data in the buffer. This value will differ from the char_amtp
value for CLOBs
and NCLOB
s if the amount is specified in terms of characters using the char_amtp
parameter, while the buflen
parameter is specified in terms of bytes.
Note:
This parameter assumes an 8-bit byte. If your operating system uses a longer byte, you must adjust the value ofbuflen
accordingly.Which piece of the buffer is being written. The default value for this parameter is OCI_ONE_PIECE
, indicating the buffer will be written in a single piece.
The following other values are also possible for piecewise or callback mode: OCI_FIRST_PIECE
, OCI_NEXT_PIECE
and OCI_LAST_PIECE
.
The context for the callback function. Can be NULL
.
A callback that may be registered to be called for each piece in a piecewise write. If this is NULL
, the standard polling method will be used.
The callback function must return OCI_CONTINUE
for the write to continue. If any other error code is returned, the LOB write is terminated. The callback takes the following parameters:
The context for the callback function. Can be NULL
.
A buffer pointer for the piece. This is the same as the bufp
passed as an input to the OCILobWrite()
routine.
The length, in bytes, of the data in the buffer (IN), and the length in bytes of current piece in bufp
(OUT).
Which piece: OCI_NEXT_PIECE
or OCI_LAST_PIECE
.
The callback function can put the address of a new buffer if it prefers to use a new buffer for next piece to read. The default old buffer bufp
is used if this parameter is set to NULL
.
Length of the new buffer, if provided.
The character set ID of the data in the buffer. 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
.
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:
Writes a buffer into an internal LOB as specified. If LOB data already exists it is overwritten with the data stored in the buffer. The buffer can be written to the LOB in a single piece with this call, or it can be provided piecewise using callbacks or a standard polling method.
Note:
When reading or writing LOBs, the character set form (csfrm
) specified should match the form of the locator itself.When using the polling mode for OCILobWrite2()
, the first call needs to specify values for offset
, byte_amtp
, and char_amtp
, but on subsequent polling calls to OCILobWrite2()
, the user need not specify these values.
If the value of the piece
parameter is OCI_FIRST_PIECE
, data may need to be provided through callbacks or polling.
If a callback function is defined in the cbfp
parameter, then this callback function will be invoked to get the next piece after a piece is written to the pipe. Each piece will be written from bufp
. If no callback function is defined, then OCILobWrite2()
returns the OCI_NEED_DATA
error code. The application must call OCILobWrite2()
again to write more pieces of the LOB. In this mode, the buffer pointer and the length can be different in each call if the pieces are of different sizes and from different locations.
A piece
value of OCI_LAST_PIECE
terminates the piecewise write, regardless of whether the polling or callback method is used.
If the amount of data passed to the database (through either input mechanism) is less than the amount specified by the byte_amtp
or the char_amtp
parameter, an ORA-22993 error is returned.
This function is valid for internal LOBs only. BFILE
s are not allowed, since they are read-only. If the LOB is a BLOB
, the csid
and csfrm
parameters are ignored.
If both byte_amtp
and char_amtp
are set to point to zero amount and OCI_FIRST_PIECE
is given as input, then polling mode is assumed and data is written until you specify OCI_LAST_PIECE
. For CLOB
s and NCLOB
s, byte_amtp
and char_amtp
return the data written by each piece in terms of number of bytes and number of characters respectively. For BLOB
s byte_amtp
returns the number of bytes written by each piece while char_amtp
is undefined on output.
To write data in UTF16 format, set the csid
parameter to OCI_UTF16ID
. If the csid
parameter is set, it overrides the NLS_LANG
environment variable.
It is not mandatory that you wrap this LOB operation inside the open or close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. If you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open or close statements.
See Also:
For additional information on Unicode format, see "PL/SQL REF CURSORs and Nested Tables in OCI"
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 in OCI"
OCIErrorGet(), OCILobRead2(), OCILobAppend(), OCILobCopy(), OCILobWriteAppend2()
Writes data starting at the end of a LOB.
sword OCILobWriteAppend ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub4 *amtp, dvoid *bufp, ub4 buflen, ub1 piece, dvoid *ctxp, OCICallbackLobWrite (cbfp) ( dvoid *ctxp, dvoid *bufp, ub4 *lenp, ub1 *piecep ) 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.
An internal LOB locator that uniquely references a LOB.
The value in amtp
is the amount in either bytes or characters, as shown in this table:
Table 16-6 Characters or Bytes in amtp
LOB or BFILE | Input with fixed-width client-side character set | Input with varying-width client-side character set | Output |
---|---|---|---|
|
bytes |
bytes |
bytes |
|
characters |
bytes (1) |
characters |
(1) The input amount refers to the number of bytes of data that the user wants to write into the LOB and not the number of bytes in the bufp,
which is specified by buflen
. In the case where data is written in pieces, the amount of bytes to write may be larger than the buflen
. The output amount refers to the number of characters written into the server-side CLOB
or NCLOB
.
If the amount specified on input, and the data is written in pieces, *amtp
will contain the total length of the pieces written at the end of the call (last piece written) and is undefined in between. (Note it is different from the piecewise read case). An error is returned if that amount is not sent to the server. If amtp is zero, then streaming mode is assumed, and data is written until the user specifies OCI_LAST_PIECE
.
If the client-side character set is varying-width, then the input amount is in bytes, not characters, for CLOBs
or NCLOBs
.
The pointer to a buffer from which the piece will be written. The length of the data in the buffer is assumed to be the value passed in buflen
. Even if the data is being written in pieces, bufp
must contain the first piece of the LOB when this call is invoked. If a callback is provided, bufp must not be used to provide data or an error will result.
The length, in bytes, of the data in the buffer. Note that this parameter assumes an 8-bit byte. If your operating system uses a longer byte, the value of buflen
must be adjusted accordingly.
Which piece of the buffer is being written. The default value for this parameter is OCI_ONE_PIECE
, indicating the buffer will be written in a single piece. The following other values are also possible for piecewise or callback mode: OCI_FIRST_PIECE
, OCI_NEXT_PIECE
and OCI_LAST_PIECE
.
The context for the call back function. Can be NULL
.
A callback that may be registered to be called for each piece in a piecewise write. If this is NULL
, the standard polling method will be used. The callback function must return OCI_CONTINUE
for the write to continue. If any other error code is returned, the LOB write is terminated. The callback takes the following parameters:
The context for the callback function. Can be NULL
.
A buffer pointer for the piece.
The length, in bytes, of the data in the buffer (IN), and the length in bytes of current piece in bufp
(OUT).
Which piece: OCI_NEXT_PIECE
or OCI_LAST_PIECE
.
The character set ID of the buffer data.
The character set form of the buffer data.
csfrm
has two possible nonzero values:
The default value is SQLCS_IMPLICIT
.
The buffer can be written to the LOB in a single piece with this call, or it can be provided piecewise using callbacks or a standard polling method. If the value of the piece parameter is OCI_FIRST_PIECE
, data must be provided through callbacks or polling. If a callback function is defined in the cbfp
parameter, then this callback function will be invoked to get the next piece after a piece is written to the pipe. Each piece will be written from bufp
. If no callback function is defined, then OCILobWriteAppend()
returns the OCI_NEED_DATA
error code.
The application must call OCILobWriteAppend()
again to write more pieces of the LOB. In this mode, the buffer pointer and the length can be different in each call if the pieces are of different sizes and from different locations. A piece value of OCI_LAST_PIECE
terminates the piecewise write.
OCILobWriteAppend()
is not supported if LOB buffering is enabled.
If the LOB is a BLOB
, the csid
and csfrm
parameters are ignored.
If the client-side character set is varying-width, then the input amount is in bytes, not characters, for CLOB
s or NCLOB
s.
It is not mandatory that you wrap this LOB operation inside the open or close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. If you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open or close statements.
See Also:
"Improving LOB Read/Write Performance"OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobWrite(), OCILobWriteAppend2()
Writes data starting at the end of a LOB. This function must be used for LOBs of size greater than 4 GB. You can also use this function for LOBs smaller than 4 GB.
sword OCILobWriteAppend2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *byte_amtp, oraub8 *char_amtp, dvoid *bufp, oraub8 buflen, ub1 piece, dvoid *ctxp, OCICallbackLobWrite2 (cbfp) ( dvoid *ctxp, dvoid *bufp, oraub8 *lenp, ub1 *piecep dvoid **changed_bufpp, oraub8 *changed_lenp ) 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.
An internal LOB locator that uniquely references a LOB.
IN - The number of bytes to write to the database. Used for BLOB
. For CLOB
and NCLOB
it is used only when char_amtp
is zero.
OUT - The number of bytes written to the database.
IN - The maximum number of characters to write to the database. Ignored for BLOB
.
OUT - The number of characters written to the database. Undefined for BLOB
.
The pointer to a buffer from which the piece will be written. The length of the data in the buffer is assumed to be the value passed in buflen
. Even if the data is being written in pieces, bufp
must contain the first piece of the LOB when this call is invoked. If a callback is provided, bufp must not be used to provide data or an error will result.
The length, in bytes, of the data in the buffer. Note that this parameter assumes an 8-bit byte. If your operating system uses a longer byte, the value of buflen
must be adjusted accordingly.
Which piece of the buffer is being written. The default value for this parameter is OCI_ONE_PIECE
, indicating the buffer will be written in a single piece. The following other values are also possible for piecewise or callback mode: OCI_FIRST_PIECE
, OCI_NEXT_PIECE
, and OCI_LAST_PIECE
.
The context for the call back function. Can be NULL
.
A callback that may be registered to be called for each piece in a piecewise write. If this is NULL
, the standard polling method will be used. The callback function must return OCI_CONTINUE
for the write to continue. If any other error code is returned, the LOB write is terminated. The callback takes the following parameters:
The context for the callback function. Can be NULL
.
A buffer pointer for the piece.
The length, in bytes, of the data in the buffer (IN), and the length in bytes of current piece in bufp
(OUT).
Which piece: OCI_NEXT_PIECE
or OCI_LAST_PIECE
.
The callback function can put the address of a new buffer if it prefers to use a new buffer for next piece to be written. The default old buffer bufp
is used if this parameter is set to NULL
.
Length of the new buffer, if provided.
The character set ID of the buffer data.
The character set form of the buffer data.
csfrm
has two possible nonzero values:
The default value is SQLCS_IMPLICIT.
The buffer can be written to the LOB in a single piece with this call, or it can be provided piecewise using callbacks or a standard polling method. If the value of the piece parameter is OCI_FIRST_PIECE
, data must be provided through callbacks or polling. If a callback function is defined in the cbfp
parameter, then this callback function will be invoked to get the next piece after a piece is written to the pipe. Each piece will be written from bufp
. If no callback function is defined, then OCILobWriteAppend2()
returns the OCI_NEED_DATA
error code.
The application must call OCILobWriteAppend2()
again to write more pieces of the LOB. In this mode, the buffer pointer and the length can be different in each call if the pieces are of different sizes and from different locations. A piece value of OCI_LAST_PIECE
terminates the piecewise write.
OCILobWriteAppend2()
is not supported if LOB buffering is enabled.
If the LOB is a BLOB
, the csid
and csfrm
parameters are ignored.
If both byte_amtp
and char_amtp
are set to point to zero amount and OCI_FIRST_PIECE
is given as input, then polling mode is assumed and data is written until you specify OCI_LAST_PIECE
. For CLOB
s and NCLOB
s, byte_amtp
and char_amtp
return the data written by each piece in terms of number of bytes and number of characters respectively. For BLOB
s byte_amtp
returns the number of bytes written by each piece while char_amtp
is undefined on output.
It is not mandatory that you wrap this LOB operation inside the open or close calls. If you did not open the LOB prior to performing this operation, then the functional and domain indexes on the LOB column are updated during this call. However, if you did open the LOB prior to performing this operation, then you must close it before you commit or rollback your transaction. When an internal LOB is closed, it updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the functional and domain indexes are updated each time you write to the LOB. This can adversely affect performance. If you have functional or domain indexes, we recommend that you enclose write operations to the LOB within the open or close statements.
See Also:
"Improving LOB Read/Write Performance"OCIErrorGet(), OCILobRead2(), OCILobAppend(), OCILobCopy(), OCILobWrite2()