External Large Objects (FILEs)

Detailed Description

OcilibCApiLobs

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

Function Documentation

OCI_FileCreate()

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

#include <api.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_SYM_PUBLIC boolean OCI_API OCI_FileFree

(

OCI_File *

file

)

#include <api.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

OCI_FileArrayCreate()

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

#include <api.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_SYM_PUBLIC boolean OCI_API OCI_FileArrayFree

(

OCI_File **

files

)

#include <api.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_SYM_PUBLIC unsigned int OCI_API OCI_FileGetType

(

OCI_File *

file

)

#include <api.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_SYM_PUBLIC boolean OCI_API OCI_FileSeek	(	OCI_File *	file,
		big_uint	offset,
		unsigned int	mode
	)

#include <api.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_SYM_PUBLIC big_uint OCI_API OCI_FileGetOffset

(

OCI_File *

file

)

#include <api.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_SYM_PUBLIC unsigned int OCI_API OCI_FileRead	(	OCI_File *	file,
		void *	buffer,
		unsigned int	len
	)

#include <api.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_SYM_PUBLIC big_uint OCI_API OCI_FileGetSize

(

OCI_File *

file

)

#include <api.h>

Return the size in bytes of a file.

Parameters

file	- File handle

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

OCI_FileExists()

OCI_SYM_PUBLIC boolean OCI_API OCI_FileExists

(

OCI_File *

file

)

#include <api.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_SYM_PUBLIC boolean OCI_API OCI_FileSetName	(	OCI_File *	file,
		const otext *	dir,
		const otext *	name
	)

#include <api.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 cannot be assigned a new directory and name

Returns

TRUE on success otherwise FALSE

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

OCI_FileGetDirectory()

OCI_SYM_PUBLIC const otext *OCI_API OCI_FileGetDirectory

(

OCI_File *

file

)

#include <api.h>

Return the directory of the given file.

Parameters

file	- File handle

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

OCI_FileGetName()

OCI_SYM_PUBLIC const otext *OCI_API OCI_FileGetName

(

OCI_File *

file

)

#include <api.h>

Return the name of the given file.

Parameters

file	- File handle

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

OCI_FileOpen()

OCI_SYM_PUBLIC boolean OCI_API OCI_FileOpen

(

OCI_File *

file

)

#include <api.h>

Open a file for reading.

Parameters

file	- File handle

Returns

TRUE on success otherwise FALSE

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

OCI_FileIsOpen()

OCI_SYM_PUBLIC boolean OCI_API OCI_FileIsOpen

(

OCI_File *

file

)

#include <api.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_SYM_PUBLIC boolean OCI_API OCI_FileClose

(

OCI_File *

file

)

#include <api.h>

Close a file.

Parameters

file	- File handle

Returns

TRUE on success otherwise FALSE

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

OCI_FileIsEqual()

OCI_SYM_PUBLIC boolean OCI_API OCI_FileIsEqual	(	OCI_File *	file,
		OCI_File *	file2
	)

#include <api.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

OCI_FileAssign()

OCI_SYM_PUBLIC boolean OCI_API OCI_FileAssign	(	OCI_File *	file,
		OCI_File *	file_src
	)

#include <api.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_SYM_PUBLIC OCI_Connection *OCI_API OCI_FileGetConnection

(

OCI_File *

file

)

#include <api.h>

Retrieve connection handle from the file handle.

Parameters

file	- file handle

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