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"

int main(void)

{

OCI_Connection *cn;

OCI_Statement *st;

OCI_Resultset *rs;

OCI_File *file;

char buffer[256];

int n;

if (!OCI_Initialize(NULL, 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_CFILE);

OCI_FileSetName(file, "MYDIR", "MyfileName");

/* check if faile 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 my_bfile_table(code, value) values (1, :bfile)");

OCI_BindFile(st, ":bfile", file);

OCI_Execute(st);

OCI_Commit(cn);

/* free local file object */

OCI_FileFree(file),

/* fetch bfile data from table */

OCI_ExecuteStmt(st, "select code, value from my_bfile_table");

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_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_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_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_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_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_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_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_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_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_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_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_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

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_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_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_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_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_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_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

Note

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

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

Detailed Description

Functions

Function Documentation