Long objects

Detailed Description

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_EXPORT OCI_Long *OCI_API	OCI_LongCreate (OCI_Statement *stmt, unsigned int type)
	Create a local temporary Long instance. More...
OCI_EXPORT boolean OCI_API	OCI_LongFree (OCI_Long *lg)
	Free a local temporary long. More...
OCI_EXPORT unsigned int OCI_API	OCI_LongGetType (OCI_Long *lg)
	Return the type of the given Long object. More...
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]. More...
OCI_EXPORT unsigned int OCI_API	OCI_LongWrite (OCI_Long *lg, void *buffer, unsigned int len)
	Write a buffer into a Long. More...
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) More...
OCI_EXPORT void *OCI_API	OCI_LongGetBuffer (OCI_Long *lg)
	Return the internal buffer of an OCI_Long object read from a fetch sequence. More...

Function Documentation

OCI_LongCreate()

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

#include <ocilib.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_EXPORT boolean OCI_API OCI_LongFree

(

OCI_Long *

lg

)

#include <ocilib.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

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

OCI_LongGetType()

OCI_EXPORT unsigned int OCI_API OCI_LongGetType

(

OCI_Long *

lg

)

#include <ocilib.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_EXPORT unsigned int OCI_API OCI_LongRead	(	OCI_Long *	lg,
		void *	buffer,
		unsigned int	len
	)

#include <ocilib.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_EXPORT unsigned int OCI_API OCI_LongWrite	(	OCI_Long *	lg,
		void *	buffer,
		unsigned int	len
	)

#include <ocilib.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_EXPORT unsigned int OCI_API OCI_LongGetSize

(

OCI_Long *

lg

)

#include <ocilib.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_EXPORT void* OCI_API OCI_LongGetBuffer

(

OCI_Long *

lg

)

#include <ocilib.h>

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

Parameters

lg	- Long handle

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