Oracle Direct path loading encapsulation. More...

#include <types.hpp>

Inherits ocilib::core::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 core::Enum< ConversionModeValues >	ConversionMode
	Conversion Mode.

typedef core::Enum< ResultValues >	Result
	Direct Operation Result.

Public Member Functions
	DirectPath (const TypeInfo &typeInfo, unsigned int nbCols, unsigned int nbRows, const ostring &partition=OTEXT(""))
	Constructor.

void	SetColumn (unsigned int colIndex, const ostring &name, unsigned int maxSize, const ostring &format=OTEXT(""))
	Describe a column to load into the given table.

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.

void	Reset ()
	Reset internal arrays and streams to prepare another load.

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.

DirectPath::Result	Load ()
	Loads the data converted to direct path stream format.

void	Finish ()
	Terminate a direct path operation and commit changes into the database.

void	Abort ()
	Terminate a direct path operation without committing changes.

void	Save ()
	Execute a data save-point (server side)

void	FlushRow ()
	Flushes a partially loaded row from server.

void	SetCurrentRows (unsigned int value)
	Set the current number of rows to convert and load.

unsigned int	GetCurrentRows () const
	Return the current number of rows used in the OCILIB internal arrays of rows.

unsigned int	GetMaxRows () const
	Return the maximum number of rows allocated in the OCI and OCILIB internal arrays of rows.

unsigned int	GetRowCount () const
	Return the number of rows successfully loaded into the database so far.

unsigned int	GetAffectedRows () const
	return the number of rows successfully processed during in the last conversion or loading call

void	SetDateFormat (const ostring &format)
	Set the default date format string for input conversion.

void	SetParallel (bool value)
	Set the parallel loading mode.

void	SetNoLog (bool value)
	Set the logging mode for the loading operation.

void	SetCacheSize (unsigned int value)
	Set number of elements in the date cache.

void	SetBufferSize (unsigned int value)
	Set the size of the internal stream transfer buffer.

void	SetConversionMode (ConversionMode value)
	Set the direct path conversion mode.

unsigned int	GetErrorColumn ()
	Return the index of a column which caused an error during data conversion.

unsigned int	GetErrorRow ()
	Return the index of a row which caused an error during data conversion.

Detailed Description

Oracle Direct path loading encapsulation.

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

Definition at line 8613 of file types.hpp.

Member Typedef Documentation

◆ ConversionMode

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

Conversion Mode.

Possible values are DirectPath::ConversionModeValues

Definition at line 8637 of file types.hpp.

◆ Result

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

Direct Operation Result.

Possible values are DirectPath::ResultValues

Definition at line 8665 of file types.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 8622 of file types.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 8644 of file types.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 28 of file DirectPath.hpp.

References ocilib::core::Check(), ocilib::TypeInfo::GetConnection(), and OCI_DirPathCreate().

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 39 of file DirectPath.hpp.

References ocilib::core::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 45 of file DirectPath.hpp.

References ocilib::core::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 50 of file DirectPath.hpp.

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

◆ Prepare()

void ocilib::DirectPath::Prepare ( )

inline

Prepares the OCI direct path load interface before any rows can be converted or loaded.

Definition at line 55 of file DirectPath.hpp.

References ocilib::core::Check(), and OCI_DirPathPrepare().

◆ 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 60 of file DirectPath.hpp.

References ocilib::core::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 65 of file DirectPath.hpp.

References ocilib::core::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 70 of file DirectPath.hpp.

References ocilib::core::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 75 of file DirectPath.hpp.

References ocilib::core::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 80 of file DirectPath.hpp.

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

◆ FlushRow()

void ocilib::DirectPath::FlushRow ( )

inline

Flushes a partially loaded row from server.

Definition at line 85 of file DirectPath.hpp.

References ocilib::core::Check(), and OCI_DirPathFlushRow().

◆ 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 90 of file DirectPath.hpp.

References ocilib::core::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 95 of file DirectPath.hpp.

References ocilib::core::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 100 of file DirectPath.hpp.

References ocilib::core::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 105 of file DirectPath.hpp.

References ocilib::core::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 110 of file DirectPath.hpp.

References ocilib::core::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 115 of file DirectPath.hpp.

References ocilib::core::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 120 of file DirectPath.hpp.

References ocilib::core::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 125 of file DirectPath.hpp.

References ocilib::core::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 130 of file DirectPath.hpp.

References ocilib::core::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 135 of file DirectPath.hpp.

References ocilib::core::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 140 of file DirectPath.hpp.

References ocilib::core::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 145 of file DirectPath.hpp.

References ocilib::core::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 150 of file DirectPath.hpp.

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

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ ConversionMode

◆ Result

Member Enumeration Documentation

◆ ConversionModeValues

◆ ResultValues

Constructor & Destructor Documentation

◆ DirectPath()

Member Function Documentation

◆ SetColumn()

◆ SetEntry()

◆ Reset()

◆ Prepare()

◆ Convert()

◆ Load()

◆ Finish()

◆ Abort()

◆ Save()

◆ FlushRow()

◆ SetCurrentRows()

◆ GetCurrentRows()

◆ GetMaxRows()

◆ GetRowCount()

◆ GetAffectedRows()

◆ SetDateFormat()

◆ SetParallel()

◆ SetNoLog()

◆ SetCacheSize()

◆ SetBufferSize()

◆ SetConversionMode()

◆ GetErrorColumn()

◆ GetErrorRow()