Long objects
C API

## 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().