OCIBindObject()

Purpose

This function sets up additional attributes which are required for a named data type (object) bind.

Syntax

sword OCIBindObject ( OCIBind          *bindp,
                      OCIError         *errhp, 
                      CONST OCIType    *type,
                      dvoid            **pgvpp, 
                      ub4              *pvszsp, 
                      dvoid            **indpp, 
                      ub4              *indszp, );

Parameters

bindp (IN/OUT)

The bind handle returned by the 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.

type (IN)

Points to the TDO which describes the type of the program variable being bound. Retrieved by calling OCITypeByName(). Optional for REFs in SQL, but required for REFs in PL/SQL.

pgvpp (IN/OUT)

Address of the program variable buffer. For an array, pgvpp points to an array of addresses. When the bind variable is also an OUT variable, the OUT Named Data Type value or REF is allocated in the Object Cache, and a REF is returned.

pgvpp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the Named Data Type buffers are requested at runtime. For static array binds, skip factors may be specified using the OCIBindArrayOfStruct() call. The skip factors are used to compute the address of the next pointer to the value, the indicator structure and their sizes.

pvszsp (OUT) [optional]

Points to the size of the program variable. The size of the named data type is not required on input. For an array, pvszsp is an array of ub4s. On return, for OUT bind variables, this points to size(s) of the Named Data Types and REFs received. pvszsp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the size of the buffer is taken at runtime.

indpp (IN/OUT) [optional]

Address of the program variable buffer containing the parallel indicator structure. For an array, points to an array of pointers. When the bind variable is also an OUT bind variable, memory is allocated in the object cache, to store the OUT indicator values. At the end of the execute when all OUT values have been received, indpp points to the pointer(s) to these newly allocated indicator structure(s). Required only for SQLT_NTY binds. indpp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the indicator is requested at runtime.

indszp (IN/OUT)

Points to the size of the IN indicator structure program variable. For an array, it is an array of sb2s. On return for OUT bind variables, this points to size(s) of the received OUT indicator structures. indszp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the indicator size is requested at runtime.

Comments

This function sets up additional attributes which binding a named data type or a REF. An error will be returned if this function is called when the OCI environment has been initialized in non-object mode.

This call takes as a parameter a type descriptor object (TDO) of datatype OCIType for the named data type being defined. The TDO can be retrieved with a call to OCITypeByName().

If the OCI_DATA_AT_EXEC mode was specified in OCIBindByName() or OCIBindByPos(), the pointers to the IN buffers are obtained either using the callback icbfp registered in the OCIBindDynamic() call or by the OCIStmtSetPieceInfo() call.

The buffers are dynamically allocated for the OUT data. The pointers to these buffers are returned either by

• calling ocbfp() registered by the OCIBindDynamic()
• or, by setting the pointer to the buffer in the buffer passed in by OCIStmtSetPieceInfo() called when OCIStmtExecute() returned OCI_NEED_DATA.

The memory of these client library-allocated buffers must be freed when not in use anymore by using the OCIObjectFree() call.

Related Functions

OCIBindByName(), OCIBindByPos()