OCILIB (C Driver for Oracle) 3.12.1
|
OCILIB (from version 3.2.0) support the OCI direct Path API.
Actual implementation of direct path API does not support the following elements :
All scalar datatypes (numerics, characters and date/time), including LOBs and LONG types are supported
The direct path load interface allows an application to access the direct path load engine of the Oracle database server to perform the functions of the Oracle SQL*Loader utility. This functionality provides the ability to load data from external files into Oracle database objects, either a table or a partition of a partitioned table. The OCI direct path load interface has the ability to load multiple rows by loading a direct path stream which contains data for multiple rows.
Its recommended to use direct path interface with an Oracle client that is the same version than the database. With version < 10g, it is mandatory regarding that it causes segmentation faults and it's known from Oracle that advices to use the same version for client and server (see metalink KB)
#include "ocilib.h" #define SIZE_ARRAY 100 #define NB_LOAD 10 #define SIZE_COL1 20 #define SIZE_COL2 30 #define SIZE_COL3 8 #define NUM_COLS 3 int main(void) { OCI_Connection *cn; OCI_DirPath *dp; OCI_TypeInfo *tbl; dtext val1[SIZE_COL1+1]; dtext val2[SIZE_COL2+1]; dtext val3[SIZE_COL3+1]; int i = 0, j = 0, nb_rows = SIZE_ARRAY; boolean res = TRUE; if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT)) return EXIT_FAILURE; cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT); tbl = OCI_TypeInfoGet(cn, "test_directpath", OCI_TIF_TABLE); dp = OCI_DirPathCreate(tbl, NULL, NUM_COLS, nb_rows); /* optional attributes to set */ OCI_DirPathSetBufferSize(dp, 64000); OCI_DirPathSetNoLog(dp, TRUE); OCI_DirPathSetParallel(dp, TRUE); /* describe the target table */ OCI_DirPathSetColumn(dp, 1, "VAL_INT", SIZE_COL1, NULL); OCI_DirPathSetColumn(dp, 2, "VAL_STR", SIZE_COL2, NULL); OCI_DirPathSetColumn(dp, 3, "VAL_DATE", SIZE_COL3, "YYYYMMDD"); /* prepare the load */ OCI_DirPathPrepare(dp); nb_rows = OCI_DirPathGetMaxRows(dp); for (i = 0; i < NB_LOAD ; i++) { OCI_DirPathReset(dp); for (j = 1; j <= nb_rows; j++) { /* fill test values */ sprintf(val1, "%04d", i + (i*100)); sprintf(val2, "value %05d", j + (i*100)); sprintf(val3, "%04d%02d%02d", (j%23)+1 + 2000, (j%11)+1, (j%23)+1); OCI_DirPathSetEntry(dp, j, 1, val1, (unsigned int) strlen(val1), TRUE); OCI_DirPathSetEntry(dp, j, 2, val2, (unsigned int) strlen(val2), TRUE); OCI_DirPathSetEntry(dp, j, 3, val3, (unsigned int) strlen(val3), TRUE); } /* load data to the server */ while (res) { int state = OCI_DirPathConvert(dp); if ((state == OCI_DPR_FULL) || (state == OCI_DPR_COMPLETE)) res = OCI_DirPathLoad(dp); if (state == OCI_DPR_COMPLETE) break; } } /* commits changes */ OCI_DirPathFinish(dp); printf("%04d row(s) loaded\n", OCI_DirPathGetRowCount(dp)); /* free direct path object */ OCI_DirPathFree(dp); OCI_Cleanup(); return EXIT_SUCCESS; }
Functions | |
OCI_EXPORT OCI_DirPath *OCI_API | OCI_DirPathCreate (OCI_TypeInfo *typinf, const mtext *partition, unsigned int nb_cols, unsigned int nb_rows) |
Create a direct path object. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathFree (OCI_DirPath *dp) |
Free an OCI_DirPath handle. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathSetColumn (OCI_DirPath *dp, unsigned int index, const mtext *name, unsigned int maxsize, const mtext *format) |
Describe a column to load into the given table. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathPrepare (OCI_DirPath *dp) |
Prepares the OCI direct path load interface before any rows can be converted or loaded. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathSetEntry (OCI_DirPath *dp, unsigned int row, unsigned int index, void *value, unsigned size, boolean complete) |
Set the value of the given row/column array entry. | |
OCI_EXPORT unsigned int OCI_API | OCI_DirPathConvert (OCI_DirPath *dp) |
Convert provided user data to the direct path stream format. | |
OCI_EXPORT unsigned int OCI_API | OCI_DirPathLoad (OCI_DirPath *dp) |
Loads the data converted to direct path stream format. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathReset (OCI_DirPath *dp) |
Reset internal arrays and streams to prepare another load. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathFinish (OCI_DirPath *dp) |
Terminate a direct path operation and commit changes into the database. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathAbort (OCI_DirPath *dp) |
Terminate a direct path operation without committing changes. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathSave (OCI_DirPath *dp) |
Execute a data savepoint (server side) | |
OCI_EXPORT boolean OCI_API | OCI_DirPathFlushRow (OCI_DirPath *dp) |
Flushes a partially loaded row from server. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathSetCurrentRows (OCI_DirPath *dp, unsigned int nb_rows) |
Set the current number of rows to convert and load. | |
OCI_EXPORT unsigned int OCI_API | OCI_DirPathGetCurrentRows (OCI_DirPath *dp) |
Return the current number of rows used in the OCILIB internal arrays of rows. | |
OCI_EXPORT unsigned int OCI_API | OCI_DirPathGetMaxRows (OCI_DirPath *dp) |
Return the maximum number of rows allocated in the OCI and OCILIB internal arrays of rows. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathSetDateFormat (OCI_DirPath *dp, const mtext *format) |
Set the default date format string for input conversion. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathSetParallel (OCI_DirPath *dp, boolean value) |
Set the parallel loading mode. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathSetNoLog (OCI_DirPath *dp, boolean value) |
Set the logging mode for the loading operation. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathSetCacheSize (OCI_DirPath *dp, unsigned int size) |
Set number of elements in the date cache. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathSetBufferSize (OCI_DirPath *dp, unsigned int size) |
Set the size of the internal stream transfer buffer. | |
OCI_EXPORT boolean OCI_API | OCI_DirPathSetConvertMode (OCI_DirPath *dp, unsigned int mode) |
Set the direct path conversion mode. | |
OCI_EXPORT unsigned int OCI_API | OCI_DirPathGetRowCount (OCI_DirPath *dp) |
Return the number of rows successfully loaded into the database so far. | |
OCI_EXPORT unsigned int OCI_API | OCI_DirPathGetAffectedRows (OCI_DirPath *dp) |
return the number of rows successfully processed during in the last conversion or loading call | |
OCI_EXPORT unsigned int OCI_API | OCI_DirPathGetErrorColumn (OCI_DirPath *dp) |
Return the index of a column which caused an error during data conversion. | |
OCI_EXPORT unsigned int OCI_API | OCI_DirPathGetErrorRow (OCI_DirPath *dp) |
Return the index of a row which caused an error during data conversion. |
OCI_EXPORT OCI_DirPath* OCI_API OCI_DirPathCreate | ( | OCI_TypeInfo * | typinf, |
const mtext * | partition, | ||
unsigned int | nb_cols, | ||
unsigned int | nb_rows | ||
) |
Create a direct path object.
typinf | - Table type info handle |
partition | - Partition name |
nb_cols | - Number of columns to load |
nb_rows | - Maximum of rows to handle per load operation |
Definition at line 274 of file dirpath.c.
References OCI_DirPathFree().
OCI_EXPORT boolean OCI_API OCI_DirPathFree | ( | OCI_DirPath * | dp | ) |
Free an OCI_DirPath handle.
dp | - Direct path Handle |
Definition at line 439 of file dirpath.c.
Referenced by OCI_DirPathCreate().
OCI_EXPORT boolean OCI_API OCI_DirPathSetColumn | ( | OCI_DirPath * | dp, |
unsigned int | index, | ||
const mtext * | name, | ||
unsigned int | maxsize, | ||
const mtext * | format | ||
) |
Describe a column to load into the given table.
dp | - Direct path Handle |
index | - Column index |
name | - Column name |
maxsize | - Maximum input value size for a column entry |
format | - Date or numeric format to use |
OCI_EXPORT boolean OCI_API OCI_DirPathPrepare | ( | OCI_DirPath * | dp | ) |
OCI_EXPORT boolean OCI_API OCI_DirPathSetEntry | ( | OCI_DirPath * | dp, |
unsigned int | row, | ||
unsigned int | index, | ||
void * | value, | ||
unsigned | size, | ||
boolean | complete | ||
) |
Set the value of the given row/column array entry.
dp | - Direct path Handle |
row | - Row index |
index | - Column index |
value | - Value to set |
size | - Size of the input value |
complete | - Is the entry content fully provided ? |
OCI_EXPORT unsigned int OCI_API OCI_DirPathConvert | ( | OCI_DirPath * | dp | ) |
Convert provided user data to the direct path stream format.
dp | - Direct path Handle |
OCI_EXPORT unsigned int OCI_API OCI_DirPathLoad | ( | OCI_DirPath * | dp | ) |
Loads the data converted to direct path stream format.
dp | - Direct path Handle |
OCI_EXPORT boolean OCI_API OCI_DirPathReset | ( | OCI_DirPath * | dp | ) |
Reset internal arrays and streams to prepare another load.
dp | - Direct path Handle |
OCI_EXPORT boolean OCI_API OCI_DirPathFinish | ( | OCI_DirPath * | dp | ) |
Terminate a direct path operation and commit changes into the database.
dp | - Direct path Handle |
OCI_EXPORT boolean OCI_API OCI_DirPathAbort | ( | OCI_DirPath * | dp | ) |
Terminate a direct path operation without committing changes.
dp | - Direct path Handle |
OCI_EXPORT boolean OCI_API OCI_DirPathSave | ( | OCI_DirPath * | dp | ) |
OCI_EXPORT boolean OCI_API OCI_DirPathFlushRow | ( | OCI_DirPath * | dp | ) |
OCI_EXPORT boolean OCI_API OCI_DirPathSetCurrentRows | ( | OCI_DirPath * | dp, |
unsigned int | nb_rows | ||
) |
Set the current number of rows to convert and load.
dp | - Direct path Handle |
nb_rows | - Number of row to process |
OCI_EXPORT unsigned int OCI_API OCI_DirPathGetCurrentRows | ( | OCI_DirPath * | dp | ) |
OCI_EXPORT unsigned int OCI_API OCI_DirPathGetMaxRows | ( | OCI_DirPath * | dp | ) |
OCI_EXPORT boolean OCI_API OCI_DirPathSetDateFormat | ( | OCI_DirPath * | dp, |
const mtext * | format | ||
) |
Set the default date format string for input conversion.
dp | - Direct path Handle |
format | - date format |
OCI_EXPORT boolean OCI_API OCI_DirPathSetParallel | ( | OCI_DirPath * | dp, |
boolean | value | ||
) |
Set the parallel loading mode.
dp | - Direct path Handle |
value | - enable/disable parallel mode |
A direct load operation requires that the object being loaded is locked to prevent DML on the object. Note that queries are lock-free and are allowed while the object is being loaded.
OCI_EXPORT boolean OCI_API OCI_DirPathSetNoLog | ( | OCI_DirPath * | dp, |
boolean | value | ||
) |
Set the logging mode for the loading operation.
dp | - Direct path Handle |
value | - enable/disable logging |
The NOLOG attribute of each segment determines whether image redo or invalidation redo is generated:
OCI_EXPORT boolean OCI_API OCI_DirPathSetCacheSize | ( | OCI_DirPath * | dp, |
unsigned int | size | ||
) |
OCI_EXPORT boolean OCI_API OCI_DirPathSetBufferSize | ( | OCI_DirPath * | dp, |
unsigned int | size | ||
) |
OCI_EXPORT boolean OCI_API OCI_DirPathSetConvertMode | ( | OCI_DirPath * | dp, |
unsigned int | mode | ||
) |
Set the direct path conversion mode.
dp | - Direct path Handle |
mode | - Conversion mode |
OCI_EXPORT unsigned int OCI_API OCI_DirPathGetRowCount | ( | OCI_DirPath * | dp | ) |
Return the number of rows successfully loaded into the database so far.
dp | - Direct path Handle |
OCI_EXPORT unsigned int OCI_API OCI_DirPathGetAffectedRows | ( | OCI_DirPath * | dp | ) |
return the number of rows successfully processed during in the last conversion or loading call
dp | - Direct path Handle |
OCI_EXPORT unsigned int OCI_API OCI_DirPathGetErrorColumn | ( | OCI_DirPath * | dp | ) |
Return the index of a column which caused an error during data conversion.
dp | - Direct path Handle |
Errors may happen while data is converted to direct path stream format using OCI_DirPathConvert(). When using conversion mode OCI_DCM_DEFAULT, OCI_DirPathConvert() returns OCI_DPR_ERROR on error. OCI_DirPathGetErrorColumn() returns the column index that caused the error When using conversion mode OCI_DCM_FORCE, OCI_DirPathConvert() returns OCI_DPR_COMPLETE even on errors. In order to retrieve the list of all column indexes that have erred, the application can call OCI_DirPathGetErrorColumn() repeatedly until it returns 0.
OCI_EXPORT unsigned int OCI_API OCI_DirPathGetErrorRow | ( | OCI_DirPath * | dp | ) |
Return the index of a row which caused an error during data conversion.
dp | - Direct path Handle |
Errors may happen :
When using conversion mode OCI_DCM_DEFAULT, OCI_DirPathConvert() returns OCI_DPR_ERROR on error. OCI_DirPathGetErrorRow() returns the row index that caused the error. When using conversion mode OCI_DCM_FORCE, OCI_DirPathConvert() returns OCI_DPR_COMPLETE even on errors. In order to retrieve the list of all row indexes that have erred, the application can call OCI_DirPathGetErrorRow() repeatedly until it returns 0.