Internal Large Objects (LOBs)


Detailed Description

Large Objects (LOBs) were introduced with Oracle 8i to replace LONGs

Oracle OCI supplies a set APIs to manipulate this datatype.

OCILIB encapsulates this API by supplying:

OCIB currently supports 3 types of Lobs :

OCI_Lob objects can be :

Lobs > 4 Go
Oracle 10g extended lobs by increasing maximum size from 4Go to 128 To.

OCILIB, with version 2.1.0, supports now this new limit. For handling sizes and offsets up to 128 To, 64 bit integers are requested.

So, A new scalar integer type has been introduced: big_uint (elderly lobsize_t). This type can be a 32 bits or 64 bits integer depending on :

big_uint will be a 64 bits integer :

Example
#include "ocilib.h"

#define SIZE_BUF 512

int main(void)
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Resultset *rs;
    OCI_Lob *lob1, *lob2;

    char temp[SIZE_BUF+1];
    int code, n;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);
 
    OCI_ExecuteStmt(st, "select code, content from test_lob for update");

    rs = OCI_GetResultset(st);
    
    while (OCI_FetchNext(rs))
    {
        code = OCI_GetInt(rs, 1);
        lob1 = OCI_GetLob(rs, 2);
        lob2 = OCI_LobCreate(cn, OCI_CLOB);

        n = OCI_LobWrite(lob1, "Today, ", 7);
        OCI_LobSeek(lob1, n, OCI_SEEK_SET);
       
        n = OCI_LobWrite(lob2, "I'm going to the cinema !", 25);
       
        OCI_LobAppendLob(lob1, lob2);
        OCI_LobSeek(lob1, 0, OCI_SEEK_SET);
        
        n = OCI_LobRead(lob1, temp, SIZE_BUF);
        temp[n] = 0;

        printf("code: %i, action : %s\n", code, temp);
            
        OCI_LobFree(lob2);
    }

    printf("\n%d row(s) fetched\n", OCI_GetRowCount(rs));

    OCI_Cleanup();

    return EXIT_SUCCESS;
}


Functions

OCI_EXPORT OCI_Lob *OCI_API OCI_LobCreate (OCI_Connection *con, unsigned int type)
 Create a local temporary Lob instance.
OCI_EXPORT boolean OCI_API OCI_LobFree (OCI_Lob *lob)
 Free a local temporary lob.
OCI_EXPORT unsigned int OCI_API OCI_LobGetType (OCI_Lob *lob)
 Return the type of the given Lob object.
OCI_EXPORT boolean OCI_API OCI_LobSeek (OCI_Lob *lob, big_uint offset, unsigned int mode)
 Perform a seek operation on the OCI_lob content buffer.
OCI_EXPORT big_uint OCI_API OCI_LobGetOffset (OCI_Lob *lob)
 Return the current position in the Lob content buffer.
OCI_EXPORT unsigned int OCI_API OCI_LobRead (OCI_Lob *lob, void *buffer, unsigned int len)
 Read a portion of a lob into the given buffer.
OCI_EXPORT unsigned int OCI_API OCI_LobWrite (OCI_Lob *lob, void *buffer, unsigned int len)
 Write a buffer into a LOB.
OCI_EXPORT boolean OCI_API OCI_LobTruncate (OCI_Lob *lob, big_uint size)
 Truncate the given lob to a shorter length.
OCI_EXPORT big_uint OCI_API OCI_LobGetLength (OCI_Lob *lob)
 Return the actual length of a lob.
OCI_EXPORT big_uint OCI_API OCI_LobErase (OCI_Lob *lob, big_uint offset, big_uint len)
 Erase a portion of the lob at a given position.
OCI_EXPORT unsigned int OCI_API OCI_LobAppend (OCI_Lob *lob, void *buffer, unsigned int len)
 Append a buffer at the end of a LOB.
OCI_EXPORT boolean OCI_API OCI_LobAppendLob (OCI_Lob *lob, OCI_Lob *lob_src)
 Append a source LOB at the end of a destination LOB.
OCI_EXPORT boolean OCI_API OCI_LobIsTemporary (OCI_Lob *lob)
 Check if the given lob is a temporary lob.
OCI_EXPORT boolean OCI_API OCI_LobCopy (OCI_Lob *lob, OCI_Lob *lob_src, big_uint offset_dst, big_uint offset_src, big_uint count)
 Copy a portion of a source LOB into a destination LOB.
OCI_EXPORT boolean OCI_API OCI_LobCopyFromFile (OCI_Lob *lob, OCI_File *file, big_uint offset_dst, big_uint offset_src, big_uint count)
 Copy a portion of a source FILE into a destination LOB.
OCI_EXPORT boolean OCI_API OCI_LobOpen (OCI_Lob *lob, unsigned int mode)
 Open explicitly a Lob.
OCI_EXPORT boolean OCI_API OCI_LobClose (OCI_Lob *lob)
 Close explicitly a Lob.
OCI_EXPORT boolean OCI_API OCI_LobIsEqual (OCI_Lob *lob, OCI_Lob *lob2)
 Compare two lob handles for equality.
OCI_EXPORT boolean OCI_API OCI_LobAssign (OCI_Lob *lob, OCI_Lob *lob_src)
 Assign a lob to another one.
OCI_EXPORT big_uint OCI_API OCI_LobGetMaxSize (OCI_Lob *lob)
 Return the maximum size that the lob can contain.
OCI_EXPORT boolean OCI_API OCI_LobFlush (OCI_Lob *lob)
 Flush Lob content to the server.


Function Documentation

OCI_EXPORT unsigned int OCI_API OCI_LobAppend ( OCI_Lob lob,
void *  buffer,
unsigned int  len 
)

Append a buffer at the end of a LOB.

Parameters:
lob - Lob handle
buffer - Pointer to a buffer
len - Length of the buffer (in bytes or characters)
Note:
Length is expressed in :
  • Bytes for BLOBs
  • Characters for CLOBs
Returns:
Number of bytes / characters written on success otherwise 0 on failure

Definition at line 667 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, OCI_Lob::handle, OCI_LobGetLength(), OCI_LobSeek(), OCI_LobWrite(), OCI_Lob::offset, and OCI_Lob::type.

OCI_EXPORT boolean OCI_API OCI_LobAppendLob ( OCI_Lob lob,
OCI_Lob lob_src 
)

Append a source LOB at the end of a destination LOB.

Parameters:
lob - Destination Lob handle
lob_src - Source Lob handle
Returns:
TRUE on success otherwise FALSE

Definition at line 766 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, OCI_Lob::handle, OCI_LobGetLength(), and OCI_Lob::offset.

OCI_EXPORT boolean OCI_API OCI_LobAssign ( OCI_Lob lob,
OCI_Lob lob_src 
)

Assign a lob to another one.

Parameters:
lob - Destination Lob handle
lob_src - Source Lob handle
Returns:
TRUE on success otherwise FALSE

Definition at line 889 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, OCI_Lob::handle, and OCI_Lob::hstate.

Referenced by OCI_ElemSetLob(), and OCI_ObjectSetLob().

OCI_EXPORT boolean OCI_API OCI_LobClose ( OCI_Lob lob  ) 

Close explicitly a Lob.

Parameters:
lob - Lob handle
Note:
  • A call to OCI_LobClose is not necessary to manipulate a Lob.
Returns:
TRUE on success otherwise FALSE

Definition at line 843 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, and OCI_Lob::handle.

OCI_EXPORT boolean OCI_API OCI_LobCopy ( OCI_Lob lob,
OCI_Lob lob_src,
big_uint  offset_dst,
big_uint  offset_src,
big_uint  count 
)

Copy a portion of a source LOB into a destination LOB.

Parameters:
lob - Destination Lob handle
lob_src - Source Lob handle
offset_dst - Absolute position in destination lob
offset_src - Absolute position in source lob
count - Number of bytes or character to copy
Note:
For character LOB (CLOB/NCLOBS) the parameters count, offset_dst and offset_src are expressed in characters and not in bytes.

Absolute position starts at 1.

Definition at line 562 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, and OCI_Lob::handle.

OCI_EXPORT boolean OCI_API OCI_LobCopyFromFile ( OCI_Lob lob,
OCI_File file,
big_uint  offset_dst,
big_uint  offset_src,
big_uint  count 
)

Copy a portion of a source FILE into a destination LOB.

Parameters:
lob - Destination Lob handle
file - Source File handle
offset_dst - Absolute position in destination lob
offset_src - Absolute position in source file
count - Number of bytes to copy
Note:
  • For character LOB (CLOB/NCLOB) the parameter offset_src are expressed in characters and not in bytes.
  • Offset_src is always in bytes

Absolute position starts at 1.

Definition at line 614 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, OCI_File::handle, and OCI_Lob::handle.

OCI_EXPORT OCI_Lob* OCI_API OCI_LobCreate ( OCI_Connection con,
unsigned int  type 
)

Create a local temporary Lob instance.

Parameters:
con - Connection handle
type - Lob type
Supported lob types :

Returns:
Return the lob handle on success otherwise NULL on failure

Definition at line 138 of file lob.c.

OCI_EXPORT big_uint OCI_API OCI_LobErase ( OCI_Lob lob,
big_uint  offset,
big_uint  len 
)

Erase a portion of the lob at a given position.

Parameters:
lob - Lob handle
offset - Absolute position in source lob
len - Number of bytes or characters to erase
Note:
Absolute position starts at 1.
Returns:
Number of bytes (BLOB) or characters (CLOB/NCLOB) erased on success otherwise 0 on failure

Definition at line 470 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, and OCI_Lob::handle.

OCI_EXPORT boolean OCI_API OCI_LobFlush ( OCI_Lob lob  ) 

Flush Lob content to the server.

Parameters:
lob - Lob handle
Returns:
TRUE on success otherwise FALSE

Definition at line 954 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, and OCI_Lob::handle.

OCI_EXPORT boolean OCI_API OCI_LobFree ( OCI_Lob lob  ) 

Free a local temporary lob.

Parameters:
lob - Lob handle
Warning:
Only lobs created with OCI_LobCreate() should be freed by OCI_LobFree()
Returns:
TRUE on success otherwise FALSE

Definition at line 157 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, OCI_Lob::handle, OCI_Lob::hstate, and OCI_LobIsTemporary().

Referenced by OCI_ElemFree().

OCI_EXPORT big_uint OCI_API OCI_LobGetLength ( OCI_Lob lob  ) 

Return the actual length of a lob.

Parameters:
lob - Lob handle
Note:
The returned value is in bytes for BLOBS and characters for CLOBS/NCLOBs

Definition at line 517 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, and OCI_Lob::handle.

Referenced by OCI_LobAppend(), OCI_LobAppendLob(), and OCI_LobSeek().

OCI_EXPORT big_uint OCI_API OCI_LobGetMaxSize ( OCI_Lob lob  ) 

Return the maximum size that the lob can contain.

Parameters:
lob - Lob handle
Returns:
TRUE on success otherwise FALSE

Definition at line 927 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, and OCI_Lob::handle.

OCI_EXPORT big_uint OCI_API OCI_LobGetOffset ( OCI_Lob lob  ) 

Return the current position in the Lob content buffer.

Parameters:
lob - Lob handle
Returns:
Lob position (starting with 0) or 0 on failure

Definition at line 233 of file lob.c.

References OCI_Lob::offset.

OCI_EXPORT unsigned int OCI_API OCI_LobGetType ( OCI_Lob lob  ) 

Return the type of the given Lob object.

Parameters:
lob - Lob handle
Note:
For possible values, see OCI_LobCreate()
Returns:
Object type or OCI_UNKNOWN the input handle is NULL

Definition at line 191 of file lob.c.

References OCI_Lob::type.

OCI_EXPORT boolean OCI_API OCI_LobIsEqual ( OCI_Lob lob,
OCI_Lob lob2 
)

Compare two lob handles for equality.

Parameters:
lob - Lob handle
lob2 - Lob2 handle
Note:
Returns:
TRUE is the lobs are not null and equal otherwise FALSE

Definition at line 865 of file lob.c.

References OCI_Lob::con, and OCI_Lob::handle.

OCI_EXPORT boolean OCI_API OCI_LobIsTemporary ( OCI_Lob lob  ) 

Check if the given lob is a temporary lob.

Parameters:
lob - Lob handle
Returns:
TRUE if it's a temporary lob otherwise FALSE

Definition at line 798 of file lob.c.

References OCI_Lob::con, OCI_Connection::err, and OCI_Lob::handle.

Referenced by OCI_LobFree().

OCI_EXPORT boolean OCI_API OCI_LobOpen ( OCI_Lob lob,
unsigned int  mode 
)

Open explicitly a Lob.

Parameters:
lob - Lob handle
mode - open mode
Possible values for mode are :

Note:
  • A call to OCI_LobOpen is not necessary to manipulate a Lob.
  • If a lob hasn't been opened explicitly, triggers are fired and indexes updated at every read/write/append operation
Returns:
TRUE on success otherwise FALSE

Definition at line 821 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, and OCI_Lob::handle.

OCI_EXPORT unsigned int OCI_API OCI_LobRead ( OCI_Lob lob,
void *  buffer,
unsigned int  len 
)

Read a portion of a lob into the given buffer.

Parameters:
lob - Lob handle
buffer - Pointer to a buffer
len - Length of the buffer (in bytes or characters)
Note:
Length is expressed in :
  • Bytes for BLOBs
  • Characters for CLOBs/NCLOBS
Returns:
Number of bytes/characters read on success otherwise 0 on failure

Definition at line 246 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, OCI_Lob::handle, OCI_Lob::offset, and OCI_Lob::type.

Referenced by OCI_GetString().

OCI_EXPORT boolean OCI_API OCI_LobSeek ( OCI_Lob lob,
big_uint  offset,
unsigned int  mode 
)

Perform a seek operation on the OCI_lob content buffer.

Parameters:
lob - Lob handle
offset - Offset from current position (bytes or characters)
mode - Seek mode
Parameter 'mode' can be one of the following value :

Note:
  • For CLOB and CLOB, offset in in characters
  • For BLOB and BFILE, offset is in bytes

Position in the Lob buffer starts at 0.

Returns:
TRUE on success otherwise FALSE

Definition at line 204 of file lob.c.

References OCI_LobGetLength(), and OCI_Lob::offset.

Referenced by OCI_GetString(), and OCI_LobAppend().

OCI_EXPORT boolean OCI_API OCI_LobTruncate ( OCI_Lob lob,
big_uint  size 
)

Truncate the given lob to a shorter length.

Parameters:
lob - Lob handle
size - New length (in bytes or characters)
Note:
Length is expressed in :
  • Bytes for BLOBs
  • Characters for CLOBs/NCLOBs
Returns:
TRUE on success otherwise FALSE

Definition at line 429 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, and OCI_Lob::handle.

OCI_EXPORT unsigned int OCI_API OCI_LobWrite ( OCI_Lob lob,
void *  buffer,
unsigned int  len 
)

Write a buffer into a LOB.

Parameters:
lob - Lob handle
buffer - Pointer to a buffer
len - Length of the buffer (in bytes or characters)
Note:
Length is expressed in :
  • Bytes for BLOBs
  • Characters for CLOBs/NCLOBs
Returns:
Number of bytes / characters written on success otherwise 0 on failure

Definition at line 336 of file lob.c.

References OCI_Lob::con, OCI_Connection::cxt, OCI_Connection::err, OCI_Lob::handle, OCI_Lob::offset, and OCI_Lob::type.

Referenced by OCI_LobAppend().


Generated on Thu Jul 30 17:41:54 2009 for OCILIB (C Driver for Oracle) by  doxygen 1.5.4