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

Detailed Description

Functions

Function Documentation

◆ OCI_FileCreate()

◆ OCI_FileFree()

◆ OCI_FileArrayCreate()

◆ OCI_FileArrayFree()

◆ OCI_FileGetType()

◆ OCI_FileSeek()

◆ OCI_FileGetOffset()

◆ OCI_FileRead()

◆ OCI_FileGetSize()

◆ OCI_FileExists()

◆ OCI_FileSetName()

◆ OCI_FileGetDirectory()

◆ OCI_FileGetName()

◆ OCI_FileOpen()

◆ OCI_FileIsOpen()

◆ OCI_FileClose()

◆ OCI_FileIsEqual()

◆ OCI_FileAssign()

◆ OCI_FileGetConnection()