Long objects

Detailed Description

OcilibCApiFiles

Long Objects encapsulate Oracle LONG data types and were used to store large buffers in Oracle databases.

They are still supported but are deprecated. 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 APIs for manipulating LONGs that is very close to the one provided for LOBs.

OCILIB currently supports 2 types of Long Objects:

• OCI_BLONG : LONG RAW columns.
• OCI_CLONG : LONG columns.

OCI_Long objects can be:

• Created as standalone instances.
• Used for in/out binding.
• Retrieved from SELECT statements.

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_SetPieceSize(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 characters (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 Long types:

• OCI_BLONG : Binary Long.
• OCI_CLONG : Character Long.

Returns

The Long handle on success, or 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 Longs 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_LongCreate().

Returns

The Long type, or OCI_UNKNOWN if 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 now fetches all data during the OCIFetchNext() call.
• This call now reads 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	- Pointer to a buffer
len	- Length of the buffer in bytes (OCI_BLONG) or characters (OCI_CLONG)

Returns

The number of bytes (OCI_BLONG) or characters (OCI_CLONG) written on success, or 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 characters (OCI_CLONG)

Parameters

lg	- Long handle

Returns

The buffer size, or 0 on failure.

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

Returns

The internal buffer pointer, or NULL on failure.