Functions

Long objects


Detailed Description

Long Objects encapsulate Oracle LONGs datatypes and were used to store large buffers in Oracle database.

They're still supported but are depreciated. Oracle now provides a newer and better way to deal with data that needs large storage : LOBs

OCILIB supports this datatype because it was and still is widely used

OCILIB provides a set of API for manipulating LONGs that is really close to the one provided for LOBs.

OCILIB currently supports 3 types of Long Objects:

OCI_Lob objects can be :

Example
#include "ocilib.h"

#define FILENAME "data.lst"
#define SIZE_BUF 512

int main(void)
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Resultset *rs;
    OCI_Long *lg;
    FILE *f;
    char buffer[SIZE_BUF];
    int 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);
 
     /* open the data file */

    f = fopen(FILENAME, "rb");

    if (f)
    {
        fseek (f , 0 , SEEK_END); 
        n = ftell(f); 
        rewind (f);  
  
        printf("\n%d bytes to write\n", n);

        lg = OCI_LongCreate(st, OCI_BLONG);

        OCI_Prepare(st,  "insert into test_long_raw(code, content) values (1, :data)");
        OCI_BindLong(st, ":data", lg, n);
        OCI_Execute(st);

        /* write data into table by chunks of SIZE_BUF bytes */       

        while ((n = fread(buffer, 1, sizeof(buffer), f)))
        {
            OCI_LongWrite(lg, buffer, n);
        }

        printf("\n%d bytes written\n", OCI_LongGetSize(lg));
        fclose(f);

        OCI_LongFree(lg);
        OCI_Commit(cn);
    }

    /* FETCHING LONGS  -------------------------------------------- */

 
    OCI_ExecuteStmt(st, "select content from test_long_raw where code = 1");
    OCI_SetLongMaxSize(st, 10000);

    rs = OCI_GetResultset(st);

    /* read data by chunks of 2048 bytes*/       
    while (OCI_FetchNext(rs))
    {
        lg = OCI_GetLong(rs, 1);

        while ((n = OCI_LongRead(lg, buffer, sizeof(buffer)))) {}

        printf("\n%d bytes read\n", OCI_LongGetSize(lg));
    }

    OCI_Cleanup();

    return EXIT_SUCCESS;
}

Functions

OCI_EXPORT OCI_Long *OCI_API OCI_LongCreate (OCI_Statement *stmt, unsigned int type)
 Create a local temporary Long instance.
OCI_EXPORT boolean OCI_API OCI_LongFree (OCI_Long *lg)
 Free a local temporary long.
OCI_EXPORT unsigned int OCI_API OCI_LongGetType (OCI_Long *lg)
 Return the type of the given Long object.
OCI_EXPORT unsigned int OCI_API OCI_LongRead (OCI_Long *lg, void *buffer, unsigned int len)
 Read a portion of a long into the given buffer [Obsolete].
OCI_EXPORT unsigned int OCI_API OCI_LongWrite (OCI_Long *lg, void *buffer, unsigned int len)
 Write a buffer into a Long.
OCI_EXPORT unsigned int OCI_API OCI_LongGetSize (OCI_Long *lg)
 Return the buffer size of a long object in bytes (OCI_BLONG) or character (OCI_CLONG)
OCI_EXPORT void *OCI_API OCI_LongGetBuffer (OCI_Long *lg)
 Return the internal buffer of an OCI_Long object read from a fetch sequence.

Function Documentation

OCI_EXPORT OCI_Long* OCI_API OCI_LongCreate ( OCI_Statement stmt,
unsigned int  type 
)

Create a local temporary Long instance.

Parameters:
stmt- Statement handle
type- Long type

Supported lob types :

  • OCI_BLONG : Binary Long
  • OCI_CLONG : Character Long
Returns:
Return the long handle on success otherwise NULL on failure

Definition at line 94 of file long.c.

OCI_EXPORT boolean OCI_API OCI_LongFree ( OCI_Long lg )

Free a local temporary long.

Parameters:
lg- Long handle
Warning:
Only lobs created with OCI_LongCreate() should be freed by OCI_LongFree()
Returns:
TRUE on success otherwise FALSE

Definition at line 117 of file long.c.

OCI_EXPORT unsigned int OCI_API OCI_LongGetType ( OCI_Long lg )

Return the type of the given Long object.

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

Definition at line 138 of file long.c.

OCI_EXPORT unsigned int OCI_API OCI_LongRead ( OCI_Long lg,
void *  buffer,
unsigned int  len 
)

Read a portion of a long into the given buffer [Obsolete].

Parameters:
lg- Long handle
buffer- Pointer to a buffer
len- Length of the buffer in bytes / characters
Note:
  • From version 2.0.0, this function is obsolete because OCILIB fetches now all data during OCIFetchNext() call
  • So, this call reads now the internal OCI_Long object allocated buffer
  • The internal buffer can be directly accessed with OCI_LongGetBuffer()
  • For OCI_CLONG, parameter 'len' and returned value are expressed in characters
  • For OCI_BLONG, parameter 'len' and returned value are expressed in bytes
Returns:
  • Number of bytes/characters read on success
  • 0 if there is nothing more to read
  • 0 on failure

Definition at line 154 of file long.c.

OCI_EXPORT unsigned int OCI_API OCI_LongWrite ( OCI_Long lg,
void *  buffer,
unsigned int  len 
)

Write a buffer into a Long.

Parameters:
lg- Long handle
buffer- the pointer to a buffer
len- the length of the buffer in bytes (OCI_BLONG) or character (OCI_CLONG)
Returns:
Number of bytes (OCI_BLONG) / character (OCI_CLONG) written on success
  • 0 if there is nothing more to read
  • 0 on failure

Definition at line 206 of file long.c.

OCI_EXPORT unsigned int OCI_API OCI_LongGetSize ( OCI_Long lg )

Return the buffer size of a long object in bytes (OCI_BLONG) or character (OCI_CLONG)

Parameters:
lg- Long handle

Definition at line 325 of file long.c.

OCI_EXPORT void* OCI_API OCI_LongGetBuffer ( OCI_Long lg )

Return the internal buffer of an OCI_Long object read from a fetch sequence.

Parameters:
lg- Long handle

Definition at line 348 of file long.c.

Referenced by OCI_GetString().