|Oracle Call Interface Programmer's Guide
Release 2 (9.2)
Part Number A96584-01
OCI Relational Functions, 30 of 38
Creates an association between a program variable and a placeholder in a SQL statement or PL/SQL block.
sword OCIBindByPos ( OCIStmt *stmtp, OCIBind **bindpp, OCIError *errhp, ub4 position, dvoid *valuep, sb4 value_sz, ub2 dty, dvoid *indp, ub2 *alenp, ub2 *rcodep, ub4 maxarr_len, ub4 *curelep, ub4 mode );
The statement handle to the SQL or PL/SQL statement being processed.
An address of a bind handle which is implicitly allocated by this call. The bind handle maintains all the bind information for this particular input value. The handle is freed implicitly when the statement handle is deallocated. On input, the value of the pointer must be null or a valid bind handle.
An error handle you can pass to
OCIErrorGet() for diagnostic information in the event of an error.
The placeholder attributes are specified by position if
OCIBindByPos() is being called.
An address of a data value or an array of data values of the type specified in the
dty parameter. An array of data values can be specified for mapping into a PL/SQL table or for providing data for SQL multiple-row operations. When an array of bind values is provided, this is called an array bind in OCI terms.
For SQLT_NTY or SQLT_REF binds, the
valuep parameter is ignored. The pointers to OUT buffers are set in the
pgvpp parameter initialized by
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.
The size of a data value. In the case of an array bind, this is the maximum size of any element possible with the actual sizes being specified in the
For descriptors, locators, or
REFs, whose size is unknown to client applications use the size of the structure you are passing in; for example, sizeof (OCILobLocator *).
The data type of the value(s) being bound. Named data types (SQLT_NTY) and
REFs (SQLT_REF) are valid only if the application has been initialized in object mode. For named data types, or
REFs, additional calls must be made with the bind handle to set up the datatype-specific attributes.
Pointer to an indicator variable or array. For all data types, this is a pointer to sb2 or an array of sb2s. The only exception is SQLT_NTY, when this pointer is ignored and the actual pointer to the indicator structure or an array of indicator structures is initialized by
OCIBindObject(). Ignored for dynamic binds.
See the section "Indicator Variables"
Pointer to array of actual lengths of array elements. Each element in
alenp is the length (in bytes, unless the data in
valuep is in Unicode, when it is in codepoints) of the data in the corresponding element in the bind value array before and after the execute. This parameter is ignored for dynamic binds.
Pointer to array of column level return codes. This parameter is ignored for dynamic binds.
The maximum possible number of elements of type
dty in a PL/SQL binds. This parameter is not required for non-PL/SQL binds. If
maxarr_len is nonzero, then either
OCIBindArrayOfStruct() can be invoked to set up additional bind attributes.
A pointer to the actual number of elements. This parameter is only required for PL/SQL binds.
The valid modes for this parameter are:
OCI_DEFAULT - This is default mode.
OCI_DATA_AT_EXEC - When this mode is selected, the
value_sz parameter defines the maximum size of the data that can ever be provided at runtime. The application must be ready to provide the OCI library runtime IN data buffers at any time and any number of times. Runtime data is provided in one of the two ways:
For more information about using the OCI_DATA_AT_EXEC mode, see the section "Runtime Data Allocation and Piecewise Operations".
When mode is set to OCI_DATA_AT_EXEC, do not provide values for
rcodep in the main call. Pass zeroes for
alenp. Provide the values through the callback function registered using
When the allocated buffers are not required any more, they should be freed by the client.
This call is used to perform a basic bind operation. The bind creates an association between the address of a program variable and a placeholder in a SQL statement or PL/SQL block. The bind call also specifies the type of data which is being bound, and may also indicate the method by which data will be provided at runtime.
This function also implicitly allocates the bind handle indicated by the
bindpp parameter. If a non-null pointer is passed in
**bindpp, the OCI assumes that this points to a valid handle that has been previously allocated with a call to
Data in an OCI application can be bound to placeholders statically or dynamically. Binding is static when all the IN bind data and the OUT bind buffers are well-defined just before the execute. Binding is dynamic when the IN bind data and the OUT bind buffers are provided by the application on demand at execute time to the client library. Dynamic binding is indicated by setting the
mode parameter of this call to OCI_DATA_AT_EXEC.
For more information about dynamic binding, see the section "Runtime Data Allocation and Piecewise Operations".
OCIBindByPos() take as a parameter a bind handle, which is implicitly allocated by the bind call A separate bind handle is allocated for each placeholder the application is binding.
Additional bind calls may be required to specify particular attributes necessary when binding certain data types or handling input data in certain ways:
OCIBindArrayOfStruct()must be called to set up the necessary skip parameters.
OCIBindDynamic()must be called to register the callbacks.
alenpgreater than 64Kbytes are required, use
OCIBindObject()must be called to specify additional necessary information.
OCIBindDynamic()must follow this call.