ocilib::DirectPath Class Reference

Oracle Direct path loading encapsulation. More...

`#include <ocilib.hpp>`

Inherits ocilib::HandleHolder< OCI_DirPath *>.

## Public Types

enum | ConversionModeValues { Default = OCI_DCM_DEFAULT, Force = OCI_DCM_FORCE }
| Conversion mode enumerated values. More...
enum | ResultValues { ResultComplete = OCI_DPR_COMPLETE, ResultError = OCI_DPR_ERROR, ResultFull = OCI_DPR_FULL, ResultPartial = OCI_DPR_PARTIAL, ResultEmpty = OCI_DPR_EMPTY }
| Direct Operation Result enumerated values. More...
typedef Enum< ConversionModeValues > | ConversionMode
| Conversion Mode. More...
typedef Enum< ResultValues > | Result
| Direct Operation Result. More...

## Public Member Functions

| DirectPath (const TypeInfo &typeInfo, unsigned int nbCols, unsigned int nbRows, const ostring &partition=OTEXT(""))
| Constructor. More...
void | SetColumn (unsigned int colIndex, const ostring &name, unsigned int maxSize, const ostring &format=OTEXT(""))
| Describe a column to load into the given table. More...
template<class T >
void | SetEntry (unsigned int rowIndex, unsigned int colIndex, const T &value, bool complete=true)
| Set the value of the given row/column array entry from the given string. More...
void | Reset ()
| Reset internal arrays and streams to prepare another load. More...
void | Prepare ()
| Prepares the OCI direct path load interface before any rows can be converted or loaded.
DirectPath::Result | Convert ()
| Convert provided user data to the direct path stream format. More...
DirectPath::Result | Load ()
| Loads the data converted to direct path stream format. More...
void | Finish ()
| Terminate a direct path operation and commit changes into the database. More...
void | Abort ()
| Terminate a direct path operation without committing changes. More...
void | Save ()
| Execute a data save-point (server side) More...
void | FlushRow ()
| Flushes a partially loaded row from server.
void | SetCurrentRows (unsigned int value)
| Set the current number of rows to convert and load. More...
unsigned int | GetCurrentRows () const
| Return the current number of rows used in the OCILIB internal arrays of rows. More...
unsigned int | GetMaxRows () const
| Return the maximum number of rows allocated in the OCI and OCILIB internal arrays of rows. More...
unsigned int | GetRowCount () const
| Return the number of rows successfully loaded into the database so far. More...
unsigned int | GetAffectedRows () const
| return the number of rows successfully processed during in the last conversion or loading call More...
void | SetDateFormat (const ostring &format)
| Set the default date format string for input conversion. More...
void | SetParallel (bool value)
| Set the parallel loading mode. More...
void | SetNoLog (bool value)
| Set the logging mode for the loading operation. More...
void | SetCacheSize (unsigned int value)
| Set number of elements in the date cache. More...
void | SetBufferSize (unsigned int value)
| Set the size of the internal stream transfer buffer. More...
void | SetConversionMode (ConversionMode value)
| Set the direct path conversion mode. More...
unsigned int | GetErrorColumn ()
| Return the index of a column which caused an error during data conversion. More...
unsigned int | GetErrorRow ()
| Return the index of a row which caused an error during data conversion. More...

## Detailed Description

Oracle Direct path loading encapsulation.

This class wraps the OCILIB object handle OCI_DirPath and its related methods

Definition at line 8505 of file ocilib.hpp.

## Member Typedef Documentation

## ConversionMode

typedef Enum<ConversionModeValues> ocilib::DirectPath::ConversionMode

Conversion Mode.

Possible values are DirectPath::ConversionModeValues

Definition at line 8529 of file ocilib.hpp.

## Result

typedef Enum<ResultValues> ocilib::DirectPath::Result

Direct Operation Result.

Possible values are DirectPath::ResultValues

Definition at line 8557 of file ocilib.hpp.

## Member Enumeration Documentation

## ConversionModeValues

enum ocilib::DirectPath::ConversionModeValues

Conversion mode enumerated values.

Enumerator
Default | Conversion fails on error
Force | Conversion does not fail on error

Definition at line 8514 of file ocilib.hpp.

## ResultValues

enum ocilib::DirectPath::ResultValues

Direct Operation Result enumerated values.

Enumerator
ResultComplete | Conversion/load has been successful
ResultError | An error happened while converting/loading data
ResultFull | The internal stream is full
ResultPartial | A column has not been fully filled yet
ResultEmpty | No data was found to convert/load

Definition at line 8536 of file ocilib.hpp.

## Constructor & Destructor Documentation

## DirectPath()

ocilib::DirectPath::DirectPath | ( | const TypeInfo & | typeInfo,
|  | unsigned int | nbCols,
|  | unsigned int | nbRows,
|  | const ostring & | partition = `OTEXT("")`
| ) |  |

inline

Constructor.

Parameters

  typeInfo | - Table type info object
  nbCols | - Number of columns to load
  nbRows | - Maximum of rows to handle per load operation
  partition | - Partition name

Note
  The partition name is not mandatory
  Parameter 'nbRows' is ignored for Oracle 8i. Prior to Oracle 9i, it's the OCI client that decides of the number of rows to process per convert/load calls. From Oracle 9i, OCI allows application to specify this value. Note that, the OCI client might not accept the input value. After Prepare() has been successfully called, GetMaxRows() returns the final number of rows used for the given direct path operation.

Definition at line 6971 of file ocilib_impl.hpp.

References ocilib::Check(), OCI_DirPathCreate(), and OCI_DirPathFree().

## Member Function Documentation

## SetColumn()

void ocilib::DirectPath::SetColumn | ( | unsigned int | colIndex,
|  | const ostring & | name,
|  | unsigned int | maxSize,
|  | const ostring & | format = `OTEXT("")`
| ) |  |

inline

Describe a column to load into the given table.

Parameters

  colIndex | - Column index
  name | - Column name
  maxSize | - Maximum input value size for a column entry
  format | - Date or numeric format to use

Note
  An error is thrown if :
  - If the column specified by the 'name' parameter is not found in the table referenced by the type info handle passed to the constructor
  - the index is out of bounds (= 0 or >= number of columns)

Definition at line 6976 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathSetColumn().

## SetEntry()

template<class T >

void ocilib::DirectPath::SetEntry | ( | unsigned int | rowIndex,
|  | unsigned int | colIndex,
|  | const T & | value,
|  | bool | complete = `true`
| ) |  |

inline

Set the value of the given row/column array entry from the given string.

Template Parameters

  T | - type of data to set (only supported types are ostring and Raw)

Parameters

  rowIndex | - Row index
  colIndex | - Column index
  value | - Value to set
  complete | - Is the entry content fully provided ?

Note
  Rows and columns indexes start at 1.
  Direct path support piece loading for LONGs and LOBs columns. When filling these columns, it's possible to provide input buffer piece by piece. In order to do so :
  - set the 'complete' parameter to false
  - Repeat calls to SetEntry() until the data is totally provided
  - The last call that set the last piece or an entry must specify the value true for the 'complete' parameter

Warning
  Current Direct Path OCILIB implementation DOES NOT support setting entry content piece by piece as mentioned above. It was planned in the original design but not supported yet. So, always set the complete parameter to true. Setting entries content piece by piece may be supported in future releases

Definition at line 6982 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathSetEntry().

## Reset()

void ocilib::DirectPath::Reset | ( |  | ) |

inline

Reset internal arrays and streams to prepare another load.

Note
  Once some data have been converted or loaded, Reset() resets internal OCI structures in order to prepare another load operation (set entries, convert and load)

Definition at line 6987 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathReset().

## Convert()

DirectPath::Result ocilib::DirectPath::Convert | ( |  | ) |

inline

Convert provided user data to the direct path stream format.

Behavior
  - When using conversion mode DirectPath::Default, Convert() stops when any error is encountered and returns ResultError
  - When using conversion mode DirectPath::Force, Convert() does not stop on errors. Instead it discards any erred rows and returns ResultComplete once all rows are processed.

Note
  List of faulted rows and columns can be retrieved using GetErrorRow() and GetErrorColumn()
  GetAffectedRows() returns the number of rows converted in the last call.

Definition at line 6997 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathConvert().

## Load()

DirectPath::Result ocilib::DirectPath::Load | ( |  | ) |

inline

Loads the data converted to direct path stream format.

Note
  List of faulted rows can be retrieved using GetErrorRow()
  GetAffectedRows() returns the number of rows successfully loaded in the last call.

Definition at line 7002 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathLoad().

## Finish()

void ocilib::DirectPath::Finish | ( |  | ) |

inline

Terminate a direct path operation and commit changes into the database.

Warning
  The direct path object cannot be used anymore after this call for any more loading operations

Definition at line 7007 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathFinish().

## Abort()

void ocilib::DirectPath::Abort | ( |  | ) |

inline

Terminate a direct path operation without committing changes.

Note
  Any pending loaded data are canceled. Any load completion operations, such as index maintenance operations, are not performed.

Warning
  The direct path object cannot be used anymore after this call for any more loading operations

Definition at line 7012 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathAbort().

## Save()

void ocilib::DirectPath::Save | ( |  | ) |

inline

Execute a data save-point (server side)

Note
  Executing a data save-point is not allowed for LOBs

Definition at line 7017 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathSave().

## SetCurrentRows()

void ocilib::DirectPath::SetCurrentRows | ( | unsigned int | value | ) |

inline

Set the current number of rows to convert and load.

Parameters

  value | - Number of row to process

Warning
  An OCILIB error will be thrown if the value exceeds the maximum number of rows in the internals arrays

Definition at line 7027 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathSetCurrentRows().

## GetCurrentRows()

unsigned int ocilib::DirectPath::GetCurrentRows | ( |  | ) | const

inline

Return the current number of rows used in the OCILIB internal arrays of rows.

Returns
  Internal current array size on SUCCESS otherwise 0

Definition at line 7032 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathGetCurrentRows().

## GetMaxRows()

unsigned int ocilib::DirectPath::GetMaxRows | ( |  | ) | const

inline

Return the maximum number of rows allocated in the OCI and OCILIB internal arrays of rows.

Returns
  Internal maximum array size on SUCCESS otherwise 0

Definition at line 7037 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathGetMaxRows().

## GetRowCount()

unsigned int ocilib::DirectPath::GetRowCount | ( |  | ) | const

inline

Return the number of rows successfully loaded into the database so far.

Note
  Insertions are committed with Finish()

Definition at line 7042 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathGetRowCount().

## GetAffectedRows()

unsigned int ocilib::DirectPath::GetAffectedRows | ( |  | ) | const

inline

return the number of rows successfully processed during in the last conversion or loading call

Note
  This function called after :

- Convert(), returns the number of converted rows
- Load(), returns the number of loaded rows

Definition at line 7047 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathGetAffectedRows().

## SetDateFormat()

void ocilib::DirectPath::SetDateFormat | ( | const ostring & | format | ) |

inline

Set the default date format string for input conversion.

Parameters

  format | - date format

Note
  For string to date conversion, Oracle uses :
  - Column date format
  - Default date format (modified by this call)
  - Default global support environment setting

Definition at line 7052 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathSetDateFormat().

## SetParallel()

void ocilib::DirectPath::SetParallel | ( | bool | value | ) |

inline

Set the parallel loading mode.

Parameters

  value | - enable/disable parallel mode

Note
  Default value is false.
  Setting the value to TRUE allows multiple load sessions to load the same segment concurrently

Parallel loading mode (From Oracle documentation)

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.

- For a table load, if the option is set to:
  - false, then the table DML X-Lock is acquired.
  - true, then the table DML S-Lock is acquired.
- For a partition load, if the option is set to:
  - false, then the table DML SX-Lock and partition DML X-Lock is acquired.
  - true, then the table DML SS-Lock and partition DML S-Lock is acquired.

Definition at line 7057 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathSetParallel().

## SetNoLog()

void ocilib::DirectPath::SetNoLog | ( | bool | value | ) |

inline

Set the logging mode for the loading operation.

Parameters

  value | - enable/disable logging

Logging mode (from Oracle Documentation)

The NOLOG attribute of each segment determines whether image redo or invalidation redo is generated:

- false : Use the attribute of the segment being loaded.
- true : No logging. Overrides DDL statement, if necessary.

Definition at line 7062 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathSetNoLog().

## SetCacheSize()

void ocilib::DirectPath::SetCacheSize | ( | unsigned int | value | ) |

inline

Set number of elements in the date cache.

Parameters

  value | - Buffer size

Note
  Default value is 0.
  Setting the value to 0 disables the cache

Definition at line 7067 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathSetCacheSize().

## SetBufferSize()

void ocilib::DirectPath::SetBufferSize | ( | unsigned int | value | ) |

inline

Set the size of the internal stream transfer buffer.

Parameters

  value | - Buffer size

Note
  Default value is 64KB.

Definition at line 7072 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathSetBufferSize().

## SetConversionMode()

void ocilib::DirectPath::SetConversionMode | ( | ConversionMode | value | ) |

inline

Set the direct path conversion mode.

Parameters

  value | - Conversion mode

Note
  See Convert() for conversion mode details
  Default value is ConversionMode::Default

Definition at line 7077 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathSetConvertMode().

## GetErrorColumn()

unsigned int ocilib::DirectPath::GetErrorColumn | ( |  | ) |

inline

Return the index of a column which caused an error during data conversion.

Warning
  Direct path column indexes start at 1.

Note
  Errors may happen while data is converted to direct path stream format using Convert().

Usage after a Convert() call
  - When using conversion mode DirectPath::Default, Convert() returns DirectPath::ResultError on error and GetErrorColumn() returns the column index that caused the error.
  - When using conversion mode DirectPath::Force, Convert() returns DirectPath::ResultComplete even on errors. In order to retrieve the list of all column indexes that have erred, the application can call GetErrorColumn() repeatedly until it returns 0.

Note
  The internal value is reset to 0 when calling Convert()

Returns
  0 is no error occurs otherwise the index of the given column which caused an error

Definition at line 7082 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathGetErrorColumn().

## GetErrorRow()

unsigned int ocilib::DirectPath::GetErrorRow | ( |  | ) |

inline

Return the index of a row which caused an error during data conversion.

Warning
  Direct path row indexes start at 1.

Note
  Errors may happen :
  - while data is converted to direct path stream format using Convert()
  - while data is loaded to database using Load()

Usage after a Convert() call
  - When using conversion mode DirectPath::Default, Convert() returns DirectPath::ResultError on error and GetErrorRow() returns the row index that caused the error.
  - When using conversion mode DirectPath::Force, Convert() returns DirectPath::ResultComplete even on errors. In order to retrieve the list of all row indexes that have erred, the application can call GetErrorRow() repeatedly until it returns 0.

Usage after a Load() call
  After a call to Load(), in order to retrieve the list of all faulted rows indexes, the application can call GetErrorRow() repeatedly until it returns 0.

Note
  The internal value is reset to 0 when calling Convert(),Reset() or Load()

Returns
  0 is no error occurs otherwise the index of the given row which caused an error

Definition at line 7087 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_DirPathGetErrorRow().