External Large Objects (FILEs)
C API

## Detailed Description

External Large Objects (FILEs) were introduced with Oracle 8i

Oracle OCI supplies a set APIs to manipulate this data type.

OCILIB encapsulates this API by supplying:

- An OCI_File C type
- A set of really easy APIs to manipulate OCI_File objects

OCILIB currently supports 2 types of Lobs :

- BFILE : Binary files
- CFILE : Character files

Warning
  FILEs are read-only.

OCI_Lob objects can be :

- Created as standalone instances
- Used for in/out binding
- Retrieved from select statements
- Used for reading server files content

Files > 4 Go

- New maximum file size limit (128 To) applies to OCI_Files objects.
- See Internal Large Objects (LOBs) section for Files > 4 Go information

Example
  #include "ocilib.h"
  /* requires script demo/file.sql */
  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_File *file;
  char buffer[256];
  int 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);
  file = OCI_FileCreate(cn, OCI_BFILE);
  /* replace 'test.txt' with any existing file on the 'test_folder' folder */
  OCI_FileSetName(file, "TEMP_FOLDER", "test.txt");
  /* check if file exists */
  if (OCI_FileExists(file))
  {
  printf("file size : %d\n", OCI_FileGetSize(file));
  printf("file dir : %s\n", OCI_FileGetDirectory(file));
  printf("file name : %s\n", OCI_FileGetName(file));
  }
  /* bind for inserting into table */
  OCI_Prepare(st, "insert into files(id, item) values (1, :f)");
  OCI_BindFile(st, ":f", file);
  OCI_Execute(st);
  /* free local file object */
  OCI_FileFree(file);
  /* fetch file data from table */
  OCI_ExecuteStmt(st, "select * from files");
  rs = OCI_GetResultset(st);
  while (OCI_FetchNext(rs))
  {
  file = OCI_GetFile(rs, 2);
  OCI_FileOpen(file);
  printf("file size %d\n", OCI_FileGetSize(file));
  printf("file dir %s\n", OCI_FileGetDirectory(file));
  printf("file name %s\n", OCI_FileGetName(file));
  while (n = OCI_FileRead(file, buffer, sizeof(buffer) - 1))
  {
  buffer[n] = 0;
  printf(buffer);
  }
  OCI_FileClose(file);
  }
  OCI_StatementFree(st);
  OCI_ConnectionFree(cn);
  OCI_Cleanup();
  return EXIT_SUCCESS;
  }

## Functions

OCI_EXPORT OCI_File *OCI_API | OCI_FileCreate (OCI_Connection *con, unsigned int type)
| Create a file object instance. More...
OCI_EXPORT boolean OCI_API | OCI_FileFree (OCI_File *file)
| Free a local File object. More...
OCI_EXPORT OCI_File **OCI_API | OCI_FileArrayCreate (OCI_Connection *con, unsigned int type, unsigned int nbelem)
| Create an array of file object. More...
OCI_EXPORT boolean OCI_API | OCI_FileArrayFree (OCI_File **files)
| Free an array of file objects. More...
OCI_EXPORT unsigned int OCI_API | OCI_FileGetType (OCI_File *file)
| Return the type of the given File object. More...
OCI_EXPORT boolean OCI_API | OCI_FileSeek (OCI_File *file, big_uint offset, unsigned int mode)
| Perform a seek operation on the OCI_File content buffer. More...
OCI_EXPORT big_uint OCI_API | OCI_FileGetOffset (OCI_File *file)
| Return the current position in the file. More...
OCI_EXPORT unsigned int OCI_API | OCI_FileRead (OCI_File *file, void *buffer, unsigned int len)
| Read a portion of a file into the given buffer. More...
OCI_EXPORT big_uint OCI_API | OCI_FileGetSize (OCI_File *file)
| Return the size in bytes of a file. More...
OCI_EXPORT boolean OCI_API | OCI_FileExists (OCI_File *file)
| Check if the given file exists on server. More...
OCI_EXPORT boolean OCI_API | OCI_FileSetName (OCI_File *file, const otext *dir, const otext *name)
| Set the directory and file name of FILE handle. More...
OCI_EXPORT const otext *OCI_API | OCI_FileGetDirectory (OCI_File *file)
| Return the directory of the given file. More...
OCI_EXPORT const otext *OCI_API | OCI_FileGetName (OCI_File *file)
| Return the name of the given file. More...
OCI_EXPORT boolean OCI_API | OCI_FileOpen (OCI_File *file)
| Open a file for reading. More...
OCI_EXPORT boolean OCI_API | OCI_FileIsOpen (OCI_File *file)
| Check if the specified file is opened within the file handle. More...
OCI_EXPORT boolean OCI_API | OCI_FileClose (OCI_File *file)
| Close a file. More...
OCI_EXPORT boolean OCI_API | OCI_FileIsEqual (OCI_File *file, OCI_File *file2)
| Compare two file handle for equality. More...
OCI_EXPORT boolean OCI_API | OCI_FileAssign (OCI_File *file, OCI_File *file_src)
| Assign a file to another one. More...
OCI_EXPORT OCI_Connection *OCI_API | OCI_FileGetConnection (OCI_File *file)
| Retrieve connection handle from the file handle. More...

## Function Documentation

## OCI_FileCreate()

OCI_EXPORT OCI_File* OCI_API OCI_FileCreate | ( | OCI_Connection * | con,
|  | unsigned int | type
| ) |  |

`#include <ocilib.h>`

Create a file object instance.

Parameters

  con | - Connection handle
  type | - File type

Supported file types :

- OCI_BFILE : Binary file
- OCI_CFILE : Character file

Returns
  Return the lob handle on success otherwise NULL on failure

Referenced by ocilib::File::File().

## OCI_FileFree()

OCI_EXPORT boolean OCI_API OCI_FileFree | ( | OCI_File * | file | ) |

`#include <ocilib.h>`

Free a local File object.

Parameters

  file | - File handle

Warning
  Only Files created with OCI_FileCreate() should be freed by OCI_FileFree()

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::File::File().

## OCI_FileArrayCreate()

OCI_EXPORT OCI_File** OCI_API OCI_FileArrayCreate | ( | OCI_Connection * | con,
|  | unsigned int | type,
|  | unsigned int | nbelem
| ) |  |

`#include <ocilib.h>`

Create an array of file object.

Parameters

  con | - Connection handle
  type | - File type
  nbelem | - number of elements in the array

Note
  see OCI_FileCreate() for more details

Returns
  Return the file handle array on success otherwise NULL on failure

## OCI_FileArrayFree()

OCI_EXPORT boolean OCI_API OCI_FileArrayFree | ( | OCI_File ** | files | ) |

`#include <ocilib.h>`

Free an array of file objects.

Parameters

  files | - Array of file objects

Warning
  Only arrays of lobs created with OCI_FileArrayCreate() should be freed by OCI_FileArrayFree()

Returns
  TRUE on success otherwise FALSE

## OCI_FileGetType()

OCI_EXPORT unsigned int OCI_API OCI_FileGetType | ( | OCI_File * | file | ) |

`#include <ocilib.h>`

Return the type of the given File object.

Parameters

  file | - File handle

Note
  For possible values, see OCI_FileCreate()

Returns
  Object type or OCI_UNKNOWN the input handle is NULL

## OCI_FileSeek()

OCI_EXPORT boolean OCI_API OCI_FileSeek | ( | OCI_File * | file,
|  | big_uint | offset,
|  | unsigned int | mode
| ) |  |

`#include <ocilib.h>`

Perform a seek operation on the OCI_File content buffer.

Parameters

  file | - File handle
  offset | - Offset from current position
  mode | - Seek mode

Mode parameter can be one of the following value :

- OCI_SEEK_SET : set the file current offset to the given absolute offset
- OCI_SEEK_END : set the file current offset to the end of the lob
- OCI_SEEK_CUR : move the file current offset to the number of bytes given by parameter 'offset'

Note
  Position in the File buffer starts at 0.

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::File::Seek().

## OCI_FileGetOffset()

OCI_EXPORT big_uint OCI_API OCI_FileGetOffset | ( | OCI_File * | file | ) |

`#include <ocilib.h>`

Return the current position in the file.

Parameters

  file | - File handle

Returns
  File position (starting with 0) or 0 on failure

Referenced by ocilib::File::GetOffset().

## OCI_FileRead()

OCI_EXPORT unsigned int OCI_API OCI_FileRead | ( | OCI_File * | file,
|  | void * | buffer,
|  | unsigned int | len
| ) |  |

`#include <ocilib.h>`

Read a portion of a file into the given buffer.

Parameters

  file | - File handle
  buffer | - Pointer to a buffer
  len | - Length of the buffer in bytes

Returns
  Number of bytes read on success otherwise 0 on failure

Referenced by ocilib::File::Read().

## OCI_FileGetSize()

OCI_EXPORT big_uint OCI_API OCI_FileGetSize | ( | OCI_File * | file | ) |

`#include <ocilib.h>`

Return the size in bytes of a file.

Parameters

  file | - File handle

Referenced by ocilib::File::GetLength().

## OCI_FileExists()

OCI_EXPORT boolean OCI_API OCI_FileExists | ( | OCI_File * | file | ) |

`#include <ocilib.h>`

Check if the given file exists on server.

Parameters

  file | - File handle

Note
  For local FILEs object, OCI_LobFileSetName() must be called before to set the filename to check

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::File::Exists().

## OCI_FileSetName()

OCI_EXPORT boolean OCI_API OCI_FileSetName | ( | OCI_File * | file,
|  | const otext * | dir,
|  | const otext * | name
| ) |  |

`#include <ocilib.h>`

Set the directory and file name of FILE handle.

Parameters

  file | - File handle
  dir | - File directory
  name | - File name in

Note
  - For local FILEs only
  - Files fetched from resultset can't be assigned a new directory and name

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::File::SetInfos().

## OCI_FileGetDirectory()

OCI_EXPORT const otext* OCI_API OCI_FileGetDirectory | ( | OCI_File * | file | ) |

`#include <ocilib.h>`

Return the directory of the given file.

Parameters

  file | - File handle

Referenced by ocilib::File::GetDirectory().

## OCI_FileGetName()

OCI_EXPORT const otext* OCI_API OCI_FileGetName | ( | OCI_File * | file | ) |

`#include <ocilib.h>`

Return the name of the given file.

Parameters

  file | - File handle

Referenced by ocilib::File::GetName().

## OCI_FileOpen()

OCI_EXPORT boolean OCI_API OCI_FileOpen | ( | OCI_File * | file | ) |

`#include <ocilib.h>`

Open a file for reading.

Parameters

  file | - File handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::File::Open().

## OCI_FileIsOpen()

OCI_EXPORT boolean OCI_API OCI_FileIsOpen | ( | OCI_File * | file | ) |

`#include <ocilib.h>`

Check if the specified file is opened within the file handle.

Parameters

  file | - File handle

Returns
  TRUE if the file was opened with this handle otherwise FALSE

Referenced by ocilib::File::IsOpened().

## OCI_FileClose()

OCI_EXPORT boolean OCI_API OCI_FileClose | ( | OCI_File * | file | ) |

`#include <ocilib.h>`

Close a file.

Parameters

  file | - File handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::File::Close().

## OCI_FileIsEqual()

OCI_EXPORT boolean OCI_API OCI_FileIsEqual | ( | OCI_File * | file,
|  | OCI_File * | file2
| ) |  |

`#include <ocilib.h>`

Compare two file handle for equality.

Parameters

  file | - File handle
  file2 | - File2 handle

Returns
  TRUE is the lobs are not null and equal otherwise FALSE

Referenced by ocilib::File::Clone().

## OCI_FileAssign()

OCI_EXPORT boolean OCI_API OCI_FileAssign | ( | OCI_File * | file,
|  | OCI_File * | file_src
| ) |  |

`#include <ocilib.h>`

Assign a file to another one.

Parameters

  file | - Destination File handle
  file_src | - Source File handle

Returns
  TRUE on success otherwise FALSE

Referenced by ocilib::File::Clone().

## OCI_FileGetConnection()

OCI_EXPORT OCI_Connection* OCI_API OCI_FileGetConnection | ( | OCI_File * | file | ) |

`#include <ocilib.h>`

Retrieve connection handle from the file handle.

Parameters

  file | - file handle

Referenced by ocilib::File::GetConnection().