OCI Relational Functions, 30 of 38

OCIBindByPos()

Purpose

Creates an association between a program variable and a placeholder in a SQL statement or PL/SQL block.

Syntax

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 );

Parameters

stmtp (IN/OUT)

The statement handle to the SQL or PL/SQL statement being processed.

bindpp (IN/OUT)

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.

errhp (IN/OUT)

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

position (IN)

The placeholder attributes are specified by position if OCIBindByPos() is being called.

valuep (IN/OUT)

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 OCIBindObject().

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 .

value_sz (IN)

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 alenp parameter.

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 *).

dty (IN)

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.

indp (IN/OUT)

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 Also:

See the section "Indicator Variables"

alenp (IN/OUT)

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.

Note:

If alenp is less than value_sz, data will be skipped.

rcodep (OUT)

Pointer to array of column level return codes. This parameter is ignored for dynamic binds.

maxarr_len (IN)

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 OCIBindDynamic() or OCIBindArrayOfStruct() can be invoked to set up additional bind attributes.

curelep (IN/OUT)

A pointer to the actual number of elements. This parameter is only required for PL/SQL binds.

mode (IN)

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:

Callbacks using a user-defined function which must be registered with a subsequent call to OCIBindDynamic().
A polling mechanism using calls supplied by the OCI. This mode is assumed if no callbacks are define.

See Also:
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 valuep, indp, alenp, and rcodep in the main call. Pass zeroes for indp and alenp. Provide the values through the callback function registered using OCIBindDynamic().

When the allocated buffers are not required any more, they should be freed by the client.

Comments

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.

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.

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 OCIHandleAlloc() or OCIBindByPos().

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.

See Also:

For more information about dynamic binding, see the section "Runtime Data Allocation and Piecewise Operations".

Both OCIBindByName() and 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:

If arrays of structures are being utilized, OCIBindArrayOfStruct() must be called to set up the necessary skip parameters.
If data is being provided dynamically at runtime, and the application will be using user-defined callback functions, OCIBindDynamic() must be called to register the callbacks.
If lengths in alenp greater than 64Kbytes are required, use OCIBindDynamic().
If a named data type is being bound, OCIBindObject() must be called to specify additional necessary information.
If a statement with RETURNING clause is used, a call to OCIBindDynamic() must follow this call.

Related Functions

OCIBindDynamic(), OCIBindObject(), OCIBindArrayOfStruct()