Long objects

Detailed Description

OcilibCApiFiles

Long Objects encapsulate Oracle LONGs data types 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 data type 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_BLONG : LONG RAW columns
• OCI_CLONG : LONG columns

OCI_Lob objects can be :

• Created as standalone instances
• Used for in/out binding
• Retrieved from select statement

Example

#include "ocilib.h"
 
/* requires script demo/long.sql */
 
#define FILENAME "data.lst"
#define SIZE_BUF 512
#define SIZE_LST 2345
 
void err_handler(OCI_Error *err)
{
    printf("%s\n", OCI_ErrorGetString(err));
}
 
int main(void)
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Resultset *rs;
    OCI_Long *lg;
    FILE *f;
    char buffer[SIZE_BUF];
    int i, n;
 
    if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))
    {
        return EXIT_FAILURE;
    }
 
    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);
 
    /* create the data file */
 
    f = fopen(FILENAME, "wb");
 
    if (f)
    {
        for (i = 1, n = SIZE_LST; i <= n; i++)
        {           
            fputc('A' + (i % CHAR_MAX), f);
        }
 
        fclose(f);
    }
 
    /* 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 = (int) 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_StatementFree(st);
    OCI_ConnectionFree(cn);
    OCI_Cleanup();
 
    return EXIT_SUCCESS;
}

Functions
OCI_SYM_PUBLIC OCI_Long *OCI_API	OCI_LongCreate (OCI_Statement *stmt, unsigned int type)
	Create a local temporary Long instance.
OCI_SYM_PUBLIC boolean OCI_API	OCI_LongFree (OCI_Long *lg)
	Free a local temporary long.
OCI_SYM_PUBLIC unsigned int OCI_API	OCI_LongGetType (OCI_Long *lg)
	Return the type of the given Long object.
OCI_SYM_PUBLIC 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_SYM_PUBLIC unsigned int OCI_API	OCI_LongWrite (OCI_Long *lg, void *buffer, unsigned int len)
	Write a buffer into a Long.
OCI_SYM_PUBLIC 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_SYM_PUBLIC 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_LongCreate()

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

#include <api.h>

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

Referenced by ocilib::Long< T, U >::Long().

OCI_LongFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_LongFree

(

OCI_Long *

lg

)

#include <api.h>

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

OCI_LongGetType()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_LongGetType

(

OCI_Long *

lg

)

#include <api.h>

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

OCI_LongRead()

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

#include <api.h>

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

OCI_LongWrite()

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

#include <api.h>

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 otherwise 0 on failure

Referenced by ocilib::Long< T, U >::Write().

OCI_LongGetSize()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_LongGetSize

(

OCI_Long *

lg

)

#include <api.h>

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

Parameters

lg	- Long handle

Referenced by ocilib::Long< T, U >::GetLength().

OCI_LongGetBuffer()

OCI_SYM_PUBLIC void *OCI_API OCI_LongGetBuffer

(

OCI_Long *

lg

)

#include <api.h>

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

Parameters

lg	- Long handle