| Oracle® Call Interface Programmer's Guide 10g Release 1 (10.1) Part Number B10779-01 |
|
|
View PDF |
| Oracle® Call Interface Programmer's Guide 10g Release 1 (10.1) Part Number B10779-01 |
|
|
View PDF |
This section describes the bind, define, and describe functions.
This call sets up the skip parameters for a static array bind.
sword OCIBindArrayOfStruct ( OCIBind *bindp, OCIError *errhp, ub4 pvskip, ub4 indskip, ub4 alskip, ub4 rcskip );
The handle to a bind structure.
An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.
Skip parameter for the next data value.
Skip parameter for the next indicator value or structure.
Skip parameter for the next actual length value.
Skip parameter for the next column-level return code value.
This call sets up the skip parameters necessary for a static array bind. It follows a call to OCIBindByName() or OCIBindByPos(). The bind handle returned by that initial bind call is used as a parameter for the OCIBindArrayOfStruct() call.
| See Also:
For information about skip parameters, see the section "Binding and Defining Arrays of Structures in OCI". |
OCIBindByName(), OCIBindByPos()
Creates an association between a program variable and a placeholder in a SQL statement or PL/SQL block.
sword OCIBindByName ( OCIStmt *stmtp, OCIBind **bindpp, OCIError *errhp, CONST text *placeholder, sb4 placeh_len, 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.
A pointer to save the pointer 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 default encoding for the call depends on the UTF-16 setting in stmtp unless the mode parameter has a different 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, specified by its name, which maps to a variable in the statement associated with the statement handle. The encoding of placeholder should always be consistent with that of the environment. That is, if the statement is prepared in UTF-16, so is the placeholder. As a string type parameter, it should be cast as (text *) and terminated with NULL.
The length of the name specified in placeholder, in number of bytes regardless of the encoding.
The pointer to a data value or an array of data values of the type specified in the dty parameter. This data could be a UTF-16 (formerly known as UCS-2) string, if an OCIAttrSet() function has been called to set OCI_ATTR_CHARSET_ID as OCI_UTF16ID or the deprecated OCI_UCS2ID. OCI_UTF16ID is the new designation for OCI_UCS2ID.
Furthermore, as pointed out for OCIStmtPrepare(), the default encoding for the string type valuep will be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate(), unless users call OCIAttrSet() to manually reset the character set for the bind handle.
| See Also:
Refer to OCI_ATTR_CHARSET_ID. |
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().
The size in bytes of the data value pointed to by dvoid pointer valuep. Although the bind buffer valuep could be of string type, the length is measured in number of bytes because the pointer passed down is of (dvoid *) type. 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; sizeof(OCILobLocator *).
The datatype of the value(s) being bound. Named datatypes (SQLT_NTY) and REFs (SQLT_REF) are valid only if the application has been initialized in object mode. For named datatypes, 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 datatypes except SQLT_NTY, this is a pointer to sb2 or an array of sb2s.
For SQLT_NTY, this pointer is ignored and the actual pointer to the indicator structure or an array of indicator structures is initialized in a subsequent call to OCIBindObject(). This parameter is ignored for dynamic binds.
Pointer to array of actual lengths of array elements. Each element in alenp is the length of the data in the corresponding element in the bind value array before and after the execute. The length should be in bytes for strings passed in as a text type. 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 OCIBindDynamic() or 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.
To maintain coding consistency, theoretically, this parameter can take all three possible values used by OCIStmtPrepare(). Since the encoding of bind variables should always be same as that of the statement containing this variable, an error will be raised if the user specify an encoding other than that of the statement. So the recommended setting for mode is OCI_DEFAULT, which will make the bind variable have the same encoding as its statement.
The valid modes are:
stmtp uses whatever is specified by its parent environment handle.dty or value_sz is changed from the previous bind, this mode is ignored. An error is returned if the statement is not executed. Unexpected behavior results if the bind handle passed is not valid.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 these two ways:
OCIBindDynamic().| See Also:
For more information about using the OCI_DATA_AT_EXEC mode, see the section "Runtime Data Allocation and Piecewise Operations in OCI". |
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.
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.
Encoding is determined by either the bind handle using the setting in the statement handle as default, or you can override the setting by specifying the mode parameter explicitly.
|
Note: After using |
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 OCIBindByName().
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 in OCI" |
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 datatypes 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.alenp greater than 64 Kbytes are required, use OCIBindDynamic().OCIBindObject() must be called to specify additional necessary information.OCIBindDynamic() must follow this call.OCIBindDynamic(), OCIBindObject(), OCIBindArrayOfStruct()
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 a LOB, the buffer pointer must be a pointer to a LOB locator of type OCILobLocator. Give the address of the pointer.
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.
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 *).
For a PL/SQL block, a value_sz greater than the width of a CHAR column will cause an error, because of how PL/SQL processes the CHAR dataype.
The datatype of the value(s) being bound. Named datatypes (SQLT_NTY) and REFs (SQLT_REF) are valid only if the application has been initialized in object mode. For named datatypes, 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 datatypes, 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" |
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 OCIBindDynamic() or 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:
dty or value_sz is changed from the previous bind, this mode is ignored. An error is returned if the statement is not executed. Unexpected behavior results if the bind handle passed is not valid.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:
OCIBindDynamic().| See Also:
For more information about using the OCI_DATA_AT_EXEC mode, see the section "Runtime Data Allocation and Piecewise Operations in OCI". |
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.
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 |
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 in OCI". |
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 datatypes 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.alenp greater than 64Kbytes are required, use OCIBindDynamic().OCIBindObject() must be called to specify additional necessary information.OCIBindDynamic() must follow this call.OCIBindDynamic(), OCIBindObject(), OCIBindArrayOfStruct()
This call is used to register user callbacks for dynamic data allocation.
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 _*/) );
A bind handle returned by a call to OCIBindByName() or OCIBindByPos().
An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.
The context pointer required by the call back function icbfp.
The callback function which returns a pointer to the IN bind value or piece at run time. The callback takes in the following parameters:
curelep parameter of the bind call.*bufpp contains a pointer to the descriptor. For example if you defineOCILOBLocator *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.
sizeof(OCILobLocator *).The context pointer required by the callback function ocbfp.
The callback function which returns a pointer to the OUT bind value or piece at run time. The callback takes in the following parameters:
curelep parameter of the bind call.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 terminate processing immediately.
| See Also:
For more information about the OCI_DATA_AT_EXEC mode, see the section "Runtime Data Allocation and Piecewise Operations in OCI". |
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 |
OCIBindByName(), OCIBindByPos()
This function sets up additional attributes which are required for a named datatype (object) bind.
sword OCIBindObject ( OCIBind *bindp, OCIError *errhp, CONST OCIType *type, dvoid **pgvpp, ub4 *pvszsp, dvoid **indpp, ub4 *indszp, );
The bind handle returned by the call to OCIBindByName() or OCIBindByPos().
An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.
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.
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 Datatype 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 Datatype 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.
Points to the size of the program variable. The size of the named datatype 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 Datatypes 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.
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 pointers to these newly allocated indicator structures. 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.
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 sizes 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.
This function sets up additional attributes which binding a named datatype 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 datatype 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
ocbfp() registered by the OCIBindDynamic()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.
OCIBindByName(), OCIBindByPos()
This call specifies additional attributes necessary for a static array define, used in an array of structures (multi-row, multi-column) fetch.
sword OCIDefineArrayOfStruct ( OCIDefine *defnp, OCIError *errhp, ub4 pvskip, ub4 indskip, ub4 rlskip, ub4 rcskip );
The handle to the define structure which was returned by a call to OCIDefineByPos().
An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.
Skip parameter for the next data value.
Skip parameter for the next indicator location.
Skip parameter for the next return length value.
Skip parameter for the next return code.
This call follows a call to OCIDefineByPos(). If the application is binding an array of structures involving objects, it must call OCIDefineObject() first, and then call OCIDefineArrayOfStruct().
OCIDefineByPos(), OCIDefineObject()
Associates an item in a select-list with the type and output data buffer.
sword OCIDefineByPos ( OCIStmt *stmtp, OCIDefine **defnpp, OCIError *errhp, ub4 position, dvoid *valuep, sb4 value_sz, ub2 dty, dvoid *indp, ub2 *rlenp, ub2 *rcodep, ub4 mode );
A handle to the requested SQL query operation.
A pointer to a pointer to a define handle. If this parameter is passed as NULL, this call implicitly allocates the define handle. In the case of a redefine, a non-NULL handle can be passed in this parameter. This handle is used to store the define information for this column.
|
Note: The user must keep track of this pointer. If a second call to |
An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.
The position of this value in the select list. Positions are 1-based and are numbered from left to right.
A pointer to a buffer or an array of buffers of the type specified in the dty parameter. A number of buffers can be specified when results for more than one row are desired in a single fetch call.
For a LOB, the buffer pointer must be a pointer to a LOB locator of type OCILobLocator. Give the address of the pointer.
The size of each valuep buffer in bytes. If the data is stored internally in VARCHAR2 format, the number of characters desired, if different from the buffer size in bytes, may be additionally specified by using OCIAttrSet().
In a multibyte conversion environment, a truncation error will be generated if the number of bytes specified is insufficient to handle the number of characters desired.
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 define call is assumed to be in UTF-16 encoding.
The datatype. Named datatype (SQLT_NTY) and REF (SQLT_REF) are valid only if the environment has been initialized in object mode.
SQLT_CHAR and SQLT_LNG can be specified for CLOB columns, and SQLT_BIN sand SQLT_LBI for BLOB columns.
| See Also:
For a listing of datatype codes and values, refer to Chapter 3, "Datatypes" |
pointer to an indicator variable or array. For scalar datatypes, pointer to sb2 or an array of sb2s. Ignored for SQLT_NTY defines. For SQLT_NTY defines, a pointer to a named datatype indicator structure or an array of named datatype indicator structures is associated by a subsequent OCIDefineObject() call.
Pointer to array of length of data fetched. Each element in rlenp is the length of the data (in bytes, unless the data in valuep is in Unicode, when it is in codepoints) in the corresponding element in the row after the fetch.
Pointer to array of column-level return codes
The valid modes are:
dty or value_sz is changed from the previous define, this mode is ignored. Unexpected behavior results if a non-valid define handle is passed. An error is returned if the statement is not executed.OCIDefineDynamic() call. The value_sz parameter defines the maximum size of the data that will be provided at runtime. When the client library needs a buffer to return the fetched data, the callback will be invoked to provide a run-time buffer into which a piece or the whole data will be returned.This call defines an output buffer which will receive data retrieved from Oracle. The define is a local step which is necessary when a SELECT statement returns data to your OCI application.
|
Note: After using |
This call also implicitly allocates the define handle for the select-list item. If a non-NULL pointer is passed in *defnpp, the OCI assumes that this points to a valid handle that has been previously allocated with a call to OCIHandleAlloc() or OCIDefineByPos(). This would be true in the case of an application which is redefining a handle to a different addresses so it can reuse the same define handle for multiple fetches.
Defining attributes of a column for a fetch is done in one or more calls. The first call is to OCIDefineByPos(), which defines the minimal attributes required to specify the fetch.
Following the call to OCIDefineByPos() additional define calls may be necessary for certain datatypes or fetch modes:
OCIDefineArrayOfStruct() is necessary to set up skip parameters for an array fetch of multiple columns.REF fetch. In this case the data buffer pointer in OCIDefineByPos() is ignored.OCIDefineArrayOfStruct() and OCIDefineObject() must be called after OCIDefineByPos() in order to fetch multiple rows with a column of named datatypes.For a LOB define, the buffer pointer must be a pointer to a LOB locator of type OCILobLocator, allocated by the OCIDescriptorAlloc() call. LOB locators, and not LOB values, are always returned for a LOB column. LOB values can then be fetched using OCI LOB calls on the fetched locator. This same mechanism is true for all descriptor datatypes.
For NCHAR (fixed and varying length), the buffer pointer must point to an array of bytes sufficient for holding the required NCHAR characters.
Nested table columns are defined and fetched like any other named datatype.
When defining an array of descriptors or locators, you should pass in an array of pointers to descriptors or locators.
When doing an array define for character columns, you should pass in an array of character buffers.
If the mode parameter is this call is set to OCI_DYNAMIC_FETCH, the client application can fetch data dynamically at runtime. Runtime data can be provided in one of two ways:
OCIDefineDynamic(). When the client library needs a buffer to return the fetched data, the callback will be invoked and the runtime buffers provided will return a piece or the whole data.
See Also:
|
OCIDefineArrayOfStruct(), OCIDefineDynamic(), OCIDefineObject()
This call is used to set the additional attributes required if the OCI_DYNAMIC_FETCH mode was selected in OCIDefineByPos().
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 _*/) );
The handle to a define structure returned by a call to OCIDefineByPos().
An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.
Points to a context for the callback function.
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.
The callback parameters are listed next:
*bufpp points to some appropriate storage for the column value.*bufpp. After data is fetched into the buffer, alenpp indicates the actual size of the data in bytes.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 in OCI".
|
Note: After using |
| See Also:
Oracle Database Application Developer's Guide - Fundamentals, the chapter on Establishing Security Policies |
Sets up additional attributes necessary for a named datatype or REF define.
sword OCIDefineObject ( OCIDefine *defnp, OCIError *errhp, CONST OCIType *type, dvoid **pgvpp, ub4 *pvszsp, dvoid **indpp, ub4 *indszp );
A define handle previously allocated in a call to OCIDefineByPos().
An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.
Points to the Type Descriptor Object (TDO) which describes the type of the program variable. Only used for program variables of type SQLT_NTY. This parameter is optional, and may be passed as NULL if it is not being used.
Points to a pointer to a program variable buffer. For an array, pgvpp points to an array of pointers. Memory for the fetched named datatype instance(s) is dynamically allocated in the object cache. At the end of the fetch when all the values have been received, pgvpp points to the pointer(s) to these newly allocated named datatype instance(s). The application must call OCIObjectFree() to deallocate the named datatype instance(s) when they are no longer needed.
|
Note: If the application wants the buffer to be implicitly allocated in the cache, |
Points to the size of the program variable. For an array, it is an array of ub4s.
Points to a pointer to the program variable buffer containing the parallel indicator structure. For an array, points to an array of pointers. Memory is allocated to store the indicator structures in the object cache. At the end of the fetch when all values have been received, indpp points to the pointer(s) to these newly allocated indicator structure(s).
Points to the size(s) of the indicator structure program variable. For an array, it is an array of ub4s.
This function follows a call to OCIDefineByPos() to set initial define information. This call sets up additional attributes necessary for a Named Datatype define. 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 datatype being defined. The TDO can be retrieved with a call to OCIDescribeAny().
| See Also:
See the description of |
Describes existing schema and subschema objects.
sword OCIDescribeAny ( OCISvcCtx *svchp, OCIError *errhp, dvoid *objptr, ub4 objptr_len, ub1 objptr_typ, ub1 info_level, ub1 objtyp, OCIDescribe *dschp );
A service context handle.
An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.
This parameter can be:
charset parameter of a previous call to OCIEnvNlsCreate().REF to the TDO (for a type).These cases are distinguished by passing the appropriate value for objptr_typ. This parameter must be non-NULL.
In case 1, the string containing the object name should be in the format name1[.name2 ...][@linkname], such as hr.employees.employee_id@mydb. Database links are only allowed to Oracle8i or later databases. The object name is interpreted by the following SQL rules:
name1 is entered and objtyp is equal to OCI_PTYPE_SCHEMA, then the name refers to the named schema. The Oracle database must be release 8.1 or later.name1 is entered and objtyp is equal to OCI_PTYPE_DATABASE, then the name refers to the named database. When describing a remote database with database_name@db_link_name, the remote Oracle database must be release 8.1 or later.name1 is entered and objtyp is not equal to OCI_PTYPE_SCHEMA or OCI_PTYPE_DATABASE, then the name refers to the named object (of type table, view, procedure, function, package, type, synonym, sequence) in the current schema of the current user. When connected to an Oracle7 Server, the only valid types are procedure and function.name1.name2.name3 ... is entered, the object name refers to a schema or subschema object in the schema named name1. For example, in the string scott.emp.deptno, scott is the name of the schema, emp is the name of a table in the schema, and deptno is the name of a column in the table.The length of the name string pointed to by objptr. Must be nonzero if a name is passed. Can be zero if objptr is a pointer to a TDO or its REF.
The type of object passed in objptr. Valid values are:
objptr points to the name of a schema objectobjptr is a pointer to a REF to a TDOobjptr is a pointer to a TDOReserved for future extensions. Pass OCI_DEFAULT.
The type of schema object being described. Valid values are:
A describe handle that is populated with describe information about the object after the call. Must be non-NULL.
This is a generic describe call that describes existing schema objects: tables, views, synonyms, procedures, functions, packages, sequences, types, schemas, and databases. This call also describes subschema objects, such as a column in a table. This call populates the describe handle with the object-specific attributes which can be obtained through an OCIAttrGet() call.
An OCIParamGet() on the describe handle returns a parameter descriptor for a specified position. Parameter positions begin with 1. Calling OCIAttrGet() on the parameter descriptor returns the specific attributes of a stored procedure or function parameter, or a table column descriptor. These subsequent calls do not need an extra round trip to the server because the entire schema object description is cached on the client side by OCIDescribeAny(). Calling OCIAttrGet() on the describe handle also returns the total number of positions.
If the OCI_ATTR_DESC_PUBLIC attribute is set on the describe handle, then the object named is looked up as a public synonym when the object does not exist in the current schema and only name1 is specified.
| See Also:
For more information about describe operations, see Chapter 6, "Describing Schema Metadata" |
Gets the bind and indicator variable names.
sword OCIStmtGetBindInfo ( OCIStmt *stmtp, OCIError *errhp, ub4 size, ub4 startloc, sb4 *found, text *bvnp[], ub1 bvnl[], text *invp[], ub1 inpl[], ub1 dupl[], OCIBind *hndl[] );
The statement handle prepared by OCIStmtPrepare().
An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.
The number of elements in each array.
Position of the bind variable at which to start getting bind information.
abs(found) gives the total number of bind variables in the statement irrespective of the start position. Positive value if the number of bind variables returned is less than the size provided, otherwise negative.
Array of pointers to hold bind variable names. Will be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().
Array to hold the length of the each bvnp element. The length is in bytes.
Array of pointers to hold indicator variable names. Must be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().
Array of pointers to hold the length of the each invp element. In number of bytes.
An array whose element value is 0 or 1 depending on whether the bind position is duplicate of another.
An array which returns the bind handle if binds have been done for the bind position. No handle is returned for duplicates.
This call returns information about bind variables after a statement has been prepared. This includes bind names, indicator names, and whether or not binds are duplicate binds. This call also returns an associated bind handle if there is one. The call sets the found parameter to the total number of bind variables and not just the number of distinct bind variables.
OCI_NO_DATA will be returned if the statement has no bind variables or if the starting bind position specified by the you in the invocation does not exist in the statement.
This function does not include SELECT INTO list variables, because they are not considered to be binds.
The statement must have been prepared with a call to OCIStmtPrepare() prior to this call. The encoding setting in the statement handle will determine whether Unicode strings will be retrieved.
This call is processed locally.
|
 Copyright © 1996, 2003 Oracle Corporation All Rights Reserved. |
|