Oracle® Call Interface Programmer's Guide 10g Release 1 (10.1) Part Number B10779-01 |
|
|
View PDF |
This section describes the direct path loading functions.
Terminates a direct path operation.
sword OCIDirPathAbort ( OCIDirPathCtx *dpctx, OCIError *errhp );
Direct path context handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
All state maintained by the server on behalf of the direct path operation is destroyed by a termination. For a direct path load, the data loaded prior to the terminate will not be visible to any queries. However, the data may still consume space in the segments that are being loaded. Any load completion operations, such as index maintenance operations, are not performed.
OCIDirPathFinish(), OCIDirPathFlushRow(), OCIDirPathPrepare(), OCIDirPathLoadStream(), OCIDirPathStreamReset(), OCIDirPathDataSave()
Gets a specified entry in a column array.
sword OCIDirPathColArrayEntryGet ( OCIDirPathColArray *dpca, OCIError *errhp, ub4 rownum, ub2 colIdx, ub1 **cvalpp, ub4 *clenp, ub1 *cflgp );
Direct path column array handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
Zero-based row offset
Column identifier (index), the column ID is returned by OCIDirPathColAttrSet()
Pointer to pointer to column data
Pointer to length of column data
Pointer to column flag.
One of the following values is returned:
NULL
If cflgp
is set to OCI_DIRPATH_COL_NULL, the cvalp
and clenp
parameters are not set by this operation.
OCIDirPathColArrayEntrySet(), OCIDirPathColArrayRowGet(), OCIDirPathColArrayReset(), OCIDirPathColArrayToStream()
Sets a specified entry in a column array to the supplied values.
sword OCIDirPathColArrayEntrySet ( OCIDirPathColArray *dpca, OCIError *errhp, ub4 rownum, ub2 colIdx, ub1 *cvalp, ub4 clen, ub1 cflg );
Direct path column array handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
Zero-based row offset
Column identifier (index), the column ID is returned by OCIDirPathColAttrSet()
Pointer to column data
Length of column data
Column flag. One of the following values is returned:
NULL
If cflg
is set to OCI_DIRPATH_COL_NULL, the cval
and clen
parameters are not used.
This example sets the source of data for the first row in a column array to addr
, with a length of len. In this example, the column is identified by colId
.
err = OCIDirPathColArrayEntrySet(dpca, errhp, (ub2)0, colId, addr, len, OCI_DIRPATH_COL_COMPLETE);
OCIDirPathColArrayRowGet(), OCIDirPathColArrayRowGet(), OCIDirPathColArrayReset(), OCIDirPathColArrayToStream()
Gets the column array row pointers for a given row number
sword OCIDirPathColArrayRowGet ( OCIDirPathColArray *dpca, OCIError *errhp, ub4 rownum, ub1 ***cvalppp, ub4 **clenpp, ub1 **cflgpp );
Direct path column array handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
Zero-based row offset
Pointer to vector of pointers to column data
Pointer to vector of column data lengths
Pointer to vector of column flags
Returns pointers to column array entries for the given row. This allows the application to do simple pointer arithmetic to iterate across the columns of the specific row. This interface can be used to efficiently get or set the column array entries of a row, as opposed to calling OCIDirPathColArrayEntrySet()
for every column. The application is also responsible for not de-referencing memory beyond the column array boundaries. The dimensions of the column array are available as attributes of the column array.
OCIDirPathColArrayRowGet(), OCIDirPathColArrayEntrySet(), OCIDirPathColArrayReset(), OCIDirPathColArrayToStream()
Resets the column array state.
sword OCIDirPathColArrayReset ( OCIDirPathColArray *dpca, OCIError *errhp );
Direct path column array handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
Resetting the column array state is necessary when piecing in a large column and an error occurs in the middle of loading the column.
OCIDirPathColArrayEntryGet(), OCIDirPathColArrayEntrySet(), OCIDirPathColArrayRowGet(), OCIDirPathColArrayToStream()
Converts from column array format to a direct path stream format.
sword OCIDirPathColArrayToStream ( OCIDirPathColArray *dpca, OCIDirPathCtx const *dpctx, OCIDirPathStream *dpstr, OCIError *errhp, ub4 rowcnt, ub4 rowoff );
Direct path column array handle.
Direct path context handle for the object being loaded.
Direct path stream handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
Number of rows in the column array.
Starting index in the column array.
This interface is used to convert a column array representation of data in its external format as specified by OCIDirPathColAttrSet()
to a direct path stream format. The converted format is suitable for loading with OCIDirPathLoadStream()
.
The column data in direct path stream format is converted to its Oracle internal representation. All conversions are done on the client side of the two-task interface, all conversion errors occur synchronously with the call to this interface. Information concerning which row and column that an error occurred on is available as an attribute of the column array handle.
Note that in a threaded environment concurrent OCIDirPathColArrayToStream()
operations can be referencing the same direct path context handle. However, the direct path context handle is not modified by this interface.
The return codes for this call are:
OCIDirPathArrayToStream()
again to convert the remainder of the column array data. Note that the column array has internal state to know where to resume conversion from. The column array attribute OCI_ATTR_ROW_COUNT is the number of rows successfully converted in the last call.OCIDirPathColArrayEntryGet(), OCIDirPathColArrayEntrySet(), OCIDirPathColArrayRowGet(), OCIDirPathColArrayReset()
Depending on the action requested, does a data savepoint, or commits the loaded data and finishes the direct path load operation.
sword OCIDirPathDataSave ( OCIDirPathCtx *dpctx, OCIError *errhp, ub4 action );
Direct path context handle for the object loaded.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
Values for action parameter to OCIDirPathDataSave()
:
A return value of OCI_SUCCESS indicates that the back-end has properly executed a data savepoint or executed the finishing logic.
Executing a data savepoint is not allowed for LOBs.
Executing the finishing logic is not the same as properly terminating the load, because resources allocated are not freed.
OCIDirPathAbort(), OCIDirPathFinish(), OCIDirPathFlushRow(), OCIDirPathPrepare(), OCIDirPathStreamReset()
Finishes the direct path load operation.
sword OCIDirPathFinish ( OCIDirPathCtx *dpctx, OCIError *errhp );
Direct path context handle for the object loaded.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
After the load has completed, and the loaded data is to be committed, the direct path finishing function is called.
A return value of OCI_SUCCESS indicates that the back-end has properly terminated the load.
OCIDirPathAbort(), OCIDirPathDataSave(), OCIDirPathFlushRow(), OCIDirPathPrepare(), OCIDirPathStreamReset()
Flushes a partially loaded row from server.
sword OCIDirPathFlushRow ( OCIDirPathCtx *dpctx, OCIError *errhp );
Direct path context handle for the object loaded.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
This function is necessary when part of a row is loaded, but a conversion error occurs on the next piece being processed by the application. Only the row currently in partial state is discarded. If the server is not currently processing a partial row for the object associated with the direct path context, this function is basically does nothing.
OCIDirPathAbort(), OCIDirPathFinish(), OCIDirPathPrepare(), OCIDirPathLoadStream()
Loads the data converted to direct path stream format.
sword OCIDirPathLoadStream ( OCIDirPathCtx *dpctx, OCIDirPathStream *dpstr, OCIError *errhp );
Direct path context handle for the object loaded.
Direct path stream handle for the stream to load.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
When the interface returns an error, information concerning the row in the column array that sourced the stream can be obtained as an attribute of the direct path stream. Also, the offset into the stream where the error occurred can be obtained as an attribute of the stream.
Return codes for this function are:
NULL
constraint violation, function-based index evaluation error, or an out of space condition, such as cannot allocate extent. OCI_ATTR_ROW_COUNT is the number of rows successfully loaded in the last call.OCIDirPathAbort(), OCIDirPathDataSave(), OCIDirPathFinish(), OCIDirPathPrepare(), OCIDirPathStreamReset()
Prepares the direct path load interface before any rows can be converted or loaded.
sword OCIDirPathPrepare ( OCIDirPathCtx *dpctx, OCISvcCtx *svchp, OCIError *errhp );
Direct path context handle for the object loaded.
Service context.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
After the name of the object to be operated on is set, the external attributes of the column data is set, and all load options are set, the direct path interface must be prepared with OCIDirPathPrepare()
before any rows can be converted or loaded.
A return value of OCI_SUCCESS indicates that the back-end has been properly initialized for a direct path load operation. A nonzero return indicates an error. Possible errors are:
OCIDirPathAbort(), OCIDirPathDataSave(), OCIDirPathFinish(), OCIDirPathFlushRow(), OCIDirPathStreamReset()
Resets the direct path stream state.
sword OCIDirPathStreamReset ( OCIDirPathStream *dpstr, OCIError *errhp );
Direct path stream handle.
An error handle you can pass to OCIErrorGet()
for diagnostic information in the event of an error.
A direct path stream maintains the state that indicates where the next OCIDirPathColArrayToStream()
call should start writing into the stream. Normally, data is appended to the end of the stream. When the caller wants to start a new stream after a stream is successfully loaded, or discard the data in a stream, the stream must be reset with this call.
OCIDirPathAbort(), OCIDirPathDataSave(), OCIDirPathFinish(), OCIDirPathFlushRow(), OCIDirPathPrepare()