OCIDefineDynamic()

Purpose

This call is used to set the additional attributes required if the OCI_DYNAMIC_FETCH mode was selected in OCIDefineByPos().

Syntax

sword OCIDefineDynamic ( OCIDefine   *defnp,
                         OCIError    *errhp,
                         dvoid       *octxp, 
                         OCICallbackDefine       (ocbfp)(/*_
                                  dvoid          *octxp,
                                  OCIDefine      *defnp,
                                  ub4            iter, 
                                  dvoid          **bufpp,
                                  ub4            **alenpp,
                                  ub1            *piecep,
                                  dvoid          **indpp,
                                  ub2            **rcodep _*/)  );

Parameters

defnp (IN/OUT)

The handle to a define structure returned by a call to OCIDefineByPos().

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

octxp (IN)

Points to a context for the callback function.

ocbfp (IN)

Points to a callback function. This is invoked at runtime to get a pointer to the buffer into which the fetched data or a piece of it will be retrieved. The callback also specifies the indicator, the return code and the lengths of the data piece and indicator.

Caution: When working with callback parameters, it is important to keep in mind what is meant by IN and OUT for the parameter mode. Normally, in an OCI function, an IN parameter refers to data being passed to Oracle, and an OUT parameter refers to data coming back from Oracle. In the case of callbacks, this is reversed. IN means data is coming from Oracle into the callback, and OUT means data is coming out of the callback and going to Oracle.

The callback parameters are listed below:

octxp (IN/OUT)

A context pointer passed as an argument to all the callback functions.

defnp (IN)

The define handle.

iter (IN)

Which row of this current fetch; 0-based.

bufpp (OUT)

Returns a pointer to a buffer to store the column value, that is, *bufpp points to some appropriate storage for the column value.

alenpp (IN/OUT)

Used by the application to set the size of the storage it is providing in *bufpp. After data is fetched into the buffer, alenpp indicates the actual size of the data in bytes.

piecep (IN/OUT)

Returns a piece value from the callback (application) to Oracle, as follows:

• IN - The value can be OCI_ONE_PIECE or OCI_NEXT_PIECE.

• OUT - Depends on the IN value:

  If IN value is OCI_ONE_PIECE, then OUT value can be OCI_ONE_PIECE or OCI_FIRST_PIECE

  If IN value is OCI_NEXT_PIECE then OUT value can be OCI_NEXT_PIECE or OCI_LAST_PIECE

indpp (IN)

Indicator variable pointer

rcodep (IN)

Return code variable pointer

Comments

This call is used to set the additional attributes required if the OCI_DYNAMIC_FETCH mode has been selected in a call to OCIDefineByPos(). If OCI_DYNAMIC_FETCH mode was selected, and the call to OCIDefineDynamic() is skipped, then the application can fetch data piecewise using OCI calls (OCIStmtGetPieceInfo() and OCIStmtSetPieceInfo()). For more information about OCI_DYNAMIC_FETCH mode, see the section "Runtime Data Allocation and Piecewise Operations".

Related Functions

OCIDefineByPos()

See Also: Oracle9i Application Developer's Guide - Fundamentals, the chapter on Establishing Security Policies