Functions

External Large Objects (FILEs)


Detailed Description

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

Oracle OCI supplies a set APIs to manipulate this datatype.

OCILIB encapsulates this API by supplying:

OCILIB currently supports 2 types of Lobs :

Warning:
FILEs are read-only.

OCI_Lob objects can be :

Files > 4 Go
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.
OCI_EXPORT boolean OCI_API OCI_FileFree (OCI_File *file)
 Free a local File object.
OCI_EXPORT OCI_File **OCI_API OCI_FileArrayCreate (OCI_Connection *con, unsigned int type, unsigned int nbelem)
 Create an array of file object.
OCI_EXPORT boolean OCI_API OCI_FileArrayFree (OCI_File **files)
 Free an array of file objects.
OCI_EXPORT unsigned int OCI_API OCI_FileGetType (OCI_File *file)
 Return the type of the given File object.
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.
OCI_EXPORT big_uint OCI_API OCI_FileGetOffset (OCI_File *file)
 Return the current position in the file.
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.
OCI_EXPORT big_uint OCI_API OCI_FileGetSize (OCI_File *file)
 Return the size in bytes of a file.
OCI_EXPORT boolean OCI_API OCI_FileExists (OCI_File *file)
 Check if the given file exists on server.
OCI_EXPORT boolean OCI_API OCI_FileSetName (OCI_File *file, const mtext *dir, const mtext *name)
 Set the directory and file name of FILE handle.
OCI_EXPORT const mtext *OCI_API OCI_FileGetDirectory (OCI_File *file)
 Return the directory of the given file.
OCI_EXPORT const mtext *OCI_API OCI_FileGetName (OCI_File *file)
 Return the name of the given file.
OCI_EXPORT boolean OCI_API OCI_FileOpen (OCI_File *file)
 Open a file for reading.
OCI_EXPORT boolean OCI_API OCI_FileIsOpen (OCI_File *file)
 Check if the specified file is opened within the file handle.
OCI_EXPORT boolean OCI_API OCI_FileClose (OCI_File *file)
 Close a file.
OCI_EXPORT boolean OCI_API OCI_FileIsEqual (OCI_File *file, OCI_File *file2)
 Compare two file handle for equality.
OCI_EXPORT boolean OCI_API OCI_FileAssign (OCI_File *file, OCI_File *file_src)
 Assign a file to another one.

Function Documentation

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

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

Definition at line 204 of file file.c.

OCI_EXPORT boolean OCI_API OCI_FileFree ( OCI_File file )

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

Definition at line 227 of file file.c.

Referenced by OCI_ElemFree().

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

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

Definition at line 259 of file file.c.

OCI_EXPORT boolean OCI_API OCI_FileArrayFree ( OCI_File **  files )

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

Definition at line 285 of file file.c.

OCI_EXPORT unsigned int OCI_API OCI_FileGetType ( OCI_File file )

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

Definition at line 413 of file file.c.

Referenced by OCI_FileRead().

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.

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

Definition at line 297 of file file.c.

References OCI_FileGetSize().

Referenced by OCI_GetString().

OCI_EXPORT big_uint OCI_API OCI_FileGetOffset ( OCI_File file )

Return the current position in the file.

Parameters:
file- File handle
Returns:
File position (starting with 0) or 0 on failure

Definition at line 331 of file file.c.

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.

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

Definition at line 347 of file file.c.

References OCI_FileGetType().

Referenced by OCI_GetString().

OCI_EXPORT big_uint OCI_API OCI_FileGetSize ( OCI_File file )

Return the size in bytes of a file.

Parameters:
file- File handle

Definition at line 429 of file file.c.

Referenced by OCI_FileSeek(), and OCI_GetString().

OCI_EXPORT boolean OCI_API OCI_FileExists ( OCI_File file )

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

Definition at line 479 of file file.c.

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

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

Definition at line 505 of file file.c.

OCI_EXPORT const mtext* OCI_API OCI_FileGetDirectory ( OCI_File file )

Return the directory of the given file.

Parameters:
file- File handle

Definition at line 548 of file file.c.

OCI_EXPORT const mtext* OCI_API OCI_FileGetName ( OCI_File file )

Return the name of the given file.

Parameters:
file- File handle

Definition at line 567 of file file.c.

OCI_EXPORT boolean OCI_API OCI_FileOpen ( OCI_File file )

Open a file for reading.

Parameters:
file- File handle
Returns:
TRUE on success otherwise FALSE

Definition at line 588 of file file.c.

OCI_EXPORT boolean OCI_API OCI_FileIsOpen ( OCI_File file )

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

Definition at line 617 of file file.c.

OCI_EXPORT boolean OCI_API OCI_FileClose ( OCI_File file )

Close a file.

Parameters:
file- File handle
Returns:
TRUE on success otherwise FALSE

Definition at line 643 of file file.c.

OCI_EXPORT boolean OCI_API OCI_FileIsEqual ( OCI_File file,
OCI_File file2 
)

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

Definition at line 671 of file file.c.

OCI_EXPORT boolean OCI_API OCI_FileAssign ( OCI_File file,
OCI_File file_src 
)

Assign a file to another one.

Parameters:
file- Destination File handle
file_src- Source File handle
Returns:
TRUE on success otherwise FALSE

Definition at line 699 of file file.c.

Referenced by OCI_ElemSetFile().