OCIBindDynamic()

Purpose

This call is used to register user callbacks for dynamic data allocation.

Syntax

sword OCIBindDynamic ( OCIBind     *bindp,
                       OCIError    *errhp,
                       dvoid       *ictxp, 
                       OCICallbackInBind         (icbfp)(/*_
                                dvoid            *ictxp,
                                OCIBind          *bindp,
                                ub4              iter, 
                                ub4              index, 
                                dvoid            **bufpp,
                                ub4              *alenp,
                                ub1              *piecep, 
                                dvoid            **indpp */),
                                dvoid            *octxp,
                       OCICallbackOutBind        (ocbfp)(/*_
                                dvoid            *octxp,
                                OCIBind          *bindp,
                                ub4              iter, 
                                ub4              index, 
                                dvoid            **bufpp, 
                                ub4              **alenpp,
                                ub1              *piecep,
                                dvoid            **indpp, 
                                ub2              **rcodepp _*/)   );

Parameters

bindp (IN/OUT)

A bind handle returned by a call to OCIBindByName() or OCIBindByPos().

errhp (IN/OUT)

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

ictxp (IN)

The context pointer required by the call back function icbfp.

icbfp (IN)

The callback function which returns a pointer to the IN bind value or piece at run time. The callback takes in the following parameters:

ictxp (IN/OUT)
The context pointer for this callback function.

bindp (IN)
The bind handle passed in to uniquely identify this bind variable.

iter (IN)
0-based execute iteration value.

index (IN)
Index of the current array, for an array bind in PL/SQL. For SQL it is the row index. The value is 0-based and not greater than curelep parameter of the bind call.

bufpp (OUT)
The pointer to the buffer or storage. For descriptors, *bufpp contains a pointer to the descriptor. For example if you define

OCILOBLocator    *lobp;

then you would set *bufpp to lobp not *lobp.

For REFs, pass the address of the ref; that is, pass &my_ref for *bufpp.

If the OCI_ATTR_CHARSET_ID attribute is set to OCI_UTF16ID (replaces the deprecated OCI_UCS2ID, which is retained for backward compatibility), all data passed to and received with the corresponding bind call is assumed to be in UTF-16 encoding.

See Also: OCI_ATTR_CHARSET_ID.

alenp (OUT)
A pointer to a storage for OCI to fill in the size of the bind value/piece after it has been read. For descriptors, pass the size of the pointer to the descriptor; for example, sizeof(OCILobLocator *).

piecep (OUT)
Which piece of the bind value. This can be one of the following values OCI_ONE_PIECE, OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE. For datatypes that do not support piecewise operations, you must pass OCI_ONE_PIECE or an error will be generated.

indp (OUT)
Contains the indicator value. This is a pointer to either an sb2 value or a pointer to an indicator structure for binding named data types.

octxp (IN)

The context pointer required by the callback function ocbfp.

ocbfp (IN)

The callback function which returns a pointer to the OUT bind value or piece at run time. The callback takes in the following parameters:

octxp (IN/OUT)
The context pointer for this call back function.

bindp (IN)
The bind handle passed in to uniquely identify this bind variable.

iter (IN)
0-based execute iteration value.

index (IN)
For PL/SQL index of the current array, for an array bind. For SQL, the index is the row number in the current iteration. It is 0-based, and must not be greater than curelep parameter of the bind call.

bufpp (OUT)
A pointer to a buffer to write the bind value/piece.

If the OCI_ATTR_CHARSET_ID attribute is set to OCI_UTF16ID (replaces the deprecated OCI_UCS2ID, which is retained for backward compatibility), all data passed to and received with the corresponding bind call is assumed to be in UTF-16 encoding. For more information, refer to OCI_ATTR_CHARSET_ID.

alenpp (IN/OUT)
A pointer to a storage for OCI to fill in the size of the bind value/piece after it has been read. It is in bytes except for Unicode encoding (if the OCI_ATTR_CHARSET_ID attribute is set to OCI_UTF16ID), when it is in codepoints.

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 (OUT)
Returns a pointer to contain the indicator value which either an sb2 value or a pointer to an indicator structure for named data types.

rcodepp (OUT)
Returns a pointer to contains the return code.

Comments

This call is used to register user-defined callback functions for providing or receiving data if OCI_DATA_AT_EXEC mode was specified in a previous call to OCIBindByName() or OCIBindByPos().

The callback function pointers must return OCI_CONTINUE if it the call is successful. Any return code other than OCI_CONTINUE signals that the client wishes to abort processing immediately.

See Also: For more information about the OCI_DATA_AT_EXEC mode, see the section "Runtime Data Allocation and Piecewise Operations".

When passing the address of a storage area, make sure that the storage area will exist even after the application returns from the callback. This means that you should not allocate such storage on the stack.

Note: After using OCIEnvNlsCreate() to create the environment handle, the actual lengths and returned lengths of bind and define handles are always in number of bytes.

Related Functions

OCIBindByName(), OCIBindByPos()