OCILobGetLength
Purpose : You can call this function to return the length of a large object (LOB) in bytes.
Function syntax :
sword OCILobGetLength (
OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *lenp );
Parameters :
| Parameter | Description |
|---|---|
| svchp(IN) | A pointer to a context handle. |
| errhp(IN/OUT) | An error handle. |
| locp(IN) | A pointer to an LOB locator. |
| lenp(OUT) | The returned length of the LOB, in bytes. |
Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.
OCILobRead
Purpose : You can call this function to read the content of a specified length from an LOB.
Function syntax :
sword OCILobRead (
OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amtp,
ub4 offset,
dvoid *bufp,
ub4 bufl,
dvoid *ctxp,
OCICallbackLobRead (cbfp)
( dvoid *ctxp,
CONST dvoid *bufp,
ub4 len,
ub1 piece
)
ub2 csid,
ub1 csfrm );
Parameters :
| Parameter | Description |
|---|---|
| svchp(IN) | A pointer to a context handle. |
| errhp(IN/OUT) | An error handle. |
| locp(IN) | A pointer to an LOB locator. |
| Amtp(IN/OUT) | The amount of input or output bytes. When the function is called, this parameter indicates the number of bytes to be read. After the function is executed, OBCI backfills the number of bytes that were actually read. |
| offset | A reserved parameter. |
| bufp(IN) | The pointer to the buffer that stores the data read. |
| bufl(IN) | The length of the buffer that stores the data read. |
| ctxp | The context pointer of the callback function. The value can be NULL. |
| cbfp | A callback function that can be registered as a function that can be called by each piece. |
| csid | The character set ID of the buffer data. |
| csfrm | The character set form of the buffer data. |
Return value : OCI_NEED_DATA is returned if the function call succeeded but the data reading has not completed. OCI_SUCCESS is returned after the data reading is completed OCI_ERROR is returned if the function call failed.
OCILobRead2()
Purpose : You can call this function to read the content of a specified length from an LOB. This function must be used for LOBs greater than 4 GB. You can choose to use the OCILobRead2() or OCILobRead() function for LOBs smaller than 4 GB. Note
This function is available only in OceanBase Database V2.2.76 and later versions.
Function syntax :
sword OCILobRead2 (
OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *byte_amtp,
oraub8 *char_amtp,
oraub8 offset,
void *bufp,
oraub8 bufl,
ub1 piece,
void *ctxp,
OCICallbackLobRead2 (cbfp)
( void *ctxp,
const void *bufp,
oraub8 lenp,
ub1 piecep
void **changed_bufpp,
oraub8 *changed_lenp
)
ub2 csid,
ub1 csfrm );
Parameters :
| Parameter | Description |
|---|---|
| svchp(IN) | A pointer to a context handle. |
| errhp(IN/OUT) | An error handle. |
| locp(IN) | A pointer to an LOB locator. |
| byte_amtp (IN/OUT) | The parameter indicates the number of bytes to read from the database when the value is IN. This parameter is always used for a field whose data type is BLOB or BFILE. For a field whose data type is CLOB or NCLOB, it is used only when char_amtp is 0. The parameter indicates the number of bytes read into the user buffer when the value is OUT. |
| char_amtp (IN/OUT) | The parameter indicates the maximum number of characters read into the user buffer when the value is IN. The parameter indicates the number of characters read into the user buffer when the value is OUT. |
| offset | A reserved parameter. |
| bufp(IN) | The pointer to the buffer that stores the data read. |
| bufl(IN) | The length of the buffer that stores the data read. |
| piece (IN) | A reserved parameter. |
| ctxp | The context pointer of the callback function. The value can be NULL. |
| bufp (IN/OUT) | A buffer pointer to a piece. |
| lenp (IN) | The length in bytes of the current piece in bufp. |
| piecep (IN) | Indicates whether the piece type is OCI_FIRST_PIECE, OCI_NEXT_PIECE, or OCI_LAST_PIECE. |
| changed_bufpp (OUT) | The address of a new buffer. The default old buffer, that is, the buffer that the bufp parameter points to, is used if this parameter is set to NULL. |
| changed_lenp (OUT) | The length of the new buffer. |
| cbfp | A callback function that can be registered as a function that can be called by each piece. |
| csid | The character set ID of the buffer data. |
| csfrm | The character set form of the buffer data. |
Return value : OCI_NEED_DATA is returned if the function call succeeded but the data reading has not completed. OCI_SUCCESS is returned after the data reading is completed OCI_ERROR is returned if the function call failed.
OCILobWrite
Purpose : You can call this function to continuously write content into an LOB.
Function syntax :
sword OCILobWrite (
OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amtp,
ub4 offset,
void *bufp,
ub4 buflen,
ub1 piece,
void *ctxp,
OCICallbackLobWrite (cbfp)
(
void *ctxp,
void *bufp,
ub4 *lenp,
ub1 *piecep
)
ub2 csid,
ub1 csfrm );
Parameters :
| Parameter | Description |
|---|---|
| svchp(IN) | A pointer to a context handle. |
| errhp(IN/OUT) | An error handle. |
| locp(IN) | A pointer to an LOB locator. |
| amtp(IN/OUT) | The amount of input or output bytes. When the function is called, this parameter indicates the number of bytes to be read. After the function is executed, OBCI backfills the number of bytes that were actually read. |
| offset | A reserved parameter. |
| bufp(IN) | The pointer to the buffer that stores the data read. |
| buflen(IN) | The length of the buffer that stores the data read. |
| piece | A reserved parameter. |
| ctxp | A reserved parameter. |
| cbfp | A reserved parameter. |
| csid | A reserved parameter. |
| csfrm | A reserved parameter. |
Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.
OCILobLocatorIsInit
Purpose : You can call this function to verify whether the given LOB or BFILE locator has been initialized.
Function syntax :
sword OCILobLocatorIsInit (
OCIEnv *envhp,
OCIError *errhp,
const OCILobLocator *locp,
boolean *is_initialized );
Parameters :
| Parameter | Description |
|---|---|
| svchp(IN/OUT) | A pointer to a context handle. |
| errhp(IN/OUT) | An error handle. |
| locp(IN) | An LOB or BFILE locator. |
| is_initialized (OUT) | Returns TRUE if the given LOB or BFILE locator has been initialized, and FALSE if otherwise. |
Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.
OCILobOpen
Purpose : You can call this function to open an LOB or BFILE object.
Function syntax :
sword OCILobOpen (
OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub1 mode );
Parameters :
| Parameter | Description |
|---|---|
| svchp(IN) | A pointer to a context handle. |
| errhp(IN/OUT) | An error handle. |
| locp(IN/OUT) | An LOB or BFILE locator. |
| mode (IN) | The opening mode. |
Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.
OCILobClose
Purpose : You can call this function to close an LOB or BFILE object.
Function syntax :
sword OCILobClose (
OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp );
Parameters :
| Parameter | Description |
|---|---|
| svchp(IN) | A pointer to a context handle. |
| errhp(IN/OUT) | An error handle. |
| locp(IN/OUT) | An LOB or BFILE locator. |
Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.
OCILobIsOpen
Purpose : You can call this function to test whether an LOB or FILE object is open.
Function syntax :
sword OCILobIsOpen (
OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
boolean *flag );
Parameters :
| Parameter | Description |
|---|---|
| svchp(IN) | A pointer to a context handle. |
| errhp(IN/OUT) | An error handle. |
| locp(IN) | An LOB or FILE locator. |
| flag(OUT) | Returns TRUE if the LOB or FILE object is open, or FALSE if otherwise. |
Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.
OCILobTrim
Purpose : You can call this function to trim an LOB value to a shorter length.
Function syntax :
sword OCILobTrim (
OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 newlen );
Parameters :
| Parameter | Description |
|---|---|
| svchp(IN) | A pointer to a context handle. |
| errhp(IN/OUT) | An error handle. |
| locp(IN) | An LOB or FILE locator. |
| newlen(IN) | The new length of the LOB value, which must be shorter than or equal to the current length. For character LOBs, it indicates the number of characters, and for binary LOBs and BFILEs, it indicates the number of bytes in the LOB. |
Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.
OCILobTrim2
Purpose : You can call this function to trim an LOB value to a shorter length. This function must be used for LOBs greater than 4 GB. You can also use this function for LOBs smaller than 4 GB.
Function syntax :
sword OCILobTrim2 (
OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 newlen );
Parameters :
| Parameter | Description |
|---|---|
| svchp(IN) | A pointer to a context handle. |
| errhp(IN/OUT) | An error handle. |
| locp(IN) | An LOB or FILE locator. |
| newlen(IN) | The new length of the LOB value, which must be shorter than or equal to the current length. For character LOBs, it indicates the number of characters, and for binary LOBs and BFILEs, it indicates the number of bytes in the LOB. |
Return value : OCI_SUCCESS is returned if the function call succeeded, and OCI_ERROR is returned if the function call failed.
OCILobCharSetForm
Purpose: obtains the character set form of the LOB locator if the LOB locator has a character set.
Prototype:
sword OCILobCharSetForm ( OCIEnv *envhp,
OCIError *errhp,
const OCILobLocator *locp,
ub1 *csfrm );
Arguments:
| Argument | Description |
|---|---|
| envhp (IN/OUT) | The environment handle of OCI. |
| errhp(IN/OUT) | The error handle. |
| locp(IN) | The LOB locator for which the character set form must be obtained. |
| csfrm (OUT) | The character set form of the input LOB locator. If the input locator (locp) is of the BLOB or BFILE type, set csfrm to 0. This is because the concept of character set is not supported in BLOB and BFILE. The caller must allocate space for csfrm(a ub1). The csfrm argument has two possible non-zero values.
|
Return value: The character set form of the input CLOB or NCLOB locator specified in the csfrm argument.
Note
The OCILobCharSetForm function does not support the processing of results.
OCILobCreateTemporary
Purpose: creates a temporary LOB.
Prototype:
sword OCILobCreateTemporary(OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub2 csid,
ub1 csfrm,
ub1 lobtype,
boolean cache,
OCIDuration duration);
Arguments:
| Argument | Description |
|---|---|
| svchp (IN) | The service context handle of the OCI. |
| errhp(IN/OUT) | The error handle. |
| locp (IN/OUT) | The locator that points to the temporary LOB. Before the locator is transferred to this function, you must call the OCIDescriptorAlloc function to allocate a locator. It does not matter whether this locator points to the LOB. All changes made to this locator apply to the temporary LOB. |
| csid (IN) | The character set ID of the LOB. |
| csfrm (IN) | The character set form of the LOB for data in the buffer. The csfrm argument has two possible non-zero values.
SQLCS_IMPLICIT. |
| lobtype (IN) | The type of the LOB to be created. Valid values:
|
| cache (IN) | Specifies whether to read the data in the LOB and write it to the cache. Set the value to TRUE if the data in the LOB must be read and written to the cache, and to FALSE if otherwise. The default value is FALSE for the NOCACHE feature. |
| duration (IN) | The duration of the temporary LOB. Valid values:
|
OCILobWrite2
Purpose: writes the data in the buffer into the LOB.
Prototype:
sword OCILobWrite2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *byte_amtp,
oraub8 *char_amtp,
oraub8 offset,
void *bufp,
oraub8 buflen,
ub1 piece,
void *ctxp,
OCICallbackLobWrite2 (cbfp)
(
void *ctxp,
void *bufp,
oraub8 *lenp,
ub1 *piecep
void **changed_bufpp,
oraub8 *changed_lenp
)
ub2 csid,
ub1 csfrm );
Parameters:
| Argument | Description |
|---|---|
| svchp (IN) | The service context handle of the OCI. |
| errhp(IN/OUT) | The error handle. |
| locp (IN/OUT) | The only internal LOB locator that references the LOB. This locator must be obtained from the specified server of svchp. |
| byte_amtp (IN/OUT) |
|
| char_amtp (IN/OUT) |
|
| offset (IN) | During the input, it indicates the absolute offset starting from the LOB value. For CLOBs, it indicates the number of characters starting from the LOB. For BLOBs, it indicates the number of bytes starting from the LOB. The first bit is 1. If streaming transmission is used by using the polling method or callbacks, you must specify the offset in the first call. Then, the offset argument will be ignored in subsequent calls. The offset argument is not used in callbacks. |
| bufp (IN) | The pointer to the buffer of the written data piece. It is assumed that the length of the data in the buffer equals the value specified in the buflen argument. Even if the data is written based on blocks by using the polling method, the bufp argument must also contain the first part of the LOB when this call is made. If a callback is provided, you must not use the bufp argument to provide data or the error result. |
| buflen (IN) | The length of the data in the buffer, in bytes. This value is different from the CLOB and NCLOB values specified in the char_amtp argument. The length is specified in the unit of characters when the char_amtp argument is used, and in the unit of bytes when the buflen argument is used. Assume that the value of this argument is 8 bytes. If the operating system uses a longer byte length, you must adjust the value of the buflen argument accordingly. |
| piece (IN) | The data piece in the buffer that is being written. The default value is OCI_ONE_PIECE, indicating that the data in the buffer is written as a single piece. In the piece-wise or callback mode, the value can also be OCI_FIRST_PIECE, OCI_NEXT_PIECE, or OCI_LAST_PIECE. |
| ctxp (IN) | The context of the callback function. The value can be NULL. |
| cbfp (IN) | The callback called for each data piece in the piece-wise write mode. If the value is NULL, the standard polling method is used. Data writing will continue only if the callback function returns OCI_CONTINUE. The LOB write is aborted if any other error code is returned. Callback arguments: |
| ctxp (IN) | The context of the callback function. The value can be NULL. |
| bufp (IN/OUT) | The pointer to the buffer of the data piece. This argument is used in the same way as that of the bufp argument in the OCILobWrite() function. |
| lenp (IN/OUT) | The length of the data in the buffer, in bytes, and the length of the current data piece in bufp (OUT), in bytes. |
| piecep (OUT) | The data piece in the buffer that is being written. Valid values: OCI_NEXT_PIECE and OCI_LAST_PIECE. |
| changed_bufpp (OUT) | The address of the new buffer if the callback function needs to use a new buffer to read the next data piece. If the value is set to NULL, the old buffer specified in the bufp argument is used. |
| changed_lenp (OUT) | The length of the new buffer, if provided. |
| csid (IN) | The ID of the character set used for the data in the buffer. If the value is 0, the csid argument will be set to the value of NLS_LANG or NLS_CHAR of the client based on the value of the csfrm argument. |
| csfrm (IN) | The character set form for the data in the buffer. The value must conform to the LOB type. It has two possible non-zero values:
|
Note
The OCILobWrite2 function supports writing a maximum of 31 KB of data into a BLOB at a time.
