1. Developer's Guide
  2. Oracle Database Access C API

26 Oracle Database Access C API

This chapter begins to describe the Oracle Database Access C API and in particular the OCI relational functions for C.

This chapter includes information about calling OCI functions in your application, along with detailed descriptions of each function call.

See Also:

For code examples, see the demonstration programs included with your Oracle Database installation. For additional information, see OCI Demonstration Programs.

This chapter contains these topics:

26.1 OCI Pipelining Functions

Lists and describes the OCI pipelining functions.

Table 26-1 OCI Pipelining Functions

Function Purpose
OCIPipelineBegin() Specifies the beginning of the pipelining block of operations.
OCIPipelineProcess() Processes an operation.
OCIPipelineEnd() Specifies the end of pipelining block of operations.

See Also:

OCI Pipelining

26.1.1 OCIPipelineBegin()

This function indicates the beginning of the OCI pipelining block of operations.

Purpose

OCIPipelineBegin() function indicates the beginning of the OCI pipeline operations. All the prologue activities to set the service context in pipeline mode.

Syntax

sword OCIPipelineBegin(OCISvcCtx  *svchp,
                        ub4                  errSetID,
                        boolean              errSetMode,
                        OCIPipelineOpCbk     pipeOpCbk,
                        void                *pipeOpCbkCtx,
                        OCIError            *errhp,
                        ub4                  mode);

Parameters

svchp (IN)

OCI service context.

cbk (IN)

Call to be executed for each OCI pipeline operation.

cbkCtx (IN)

The callback context.

errhp (IN/OUT)

Error handle

mode (IN)
Modes supported:
  • OCI_PIPELINE_CONT_ON_ERROR
  • OCI_PIPELINE_ABORT_ON_ERROR

Returns

  • OCI_SUCCESS: When the function is successful.
  • OCI_ERROR: When the function fails, the actual error can be retrieved from errhp.
26.1.1.1 Callback and Context

This section describes callback and callback context used in the OCI pipeline operation.

Callback and context are provided to OCIPipelineBegin() function to allow the application to process the result of the operation. This callback is executed for every operation that is executed on a server and returned with a response. This is one standard callback for every operation in the pipeline block.

Syntax

typedef sword (*OCIPipelineOperationCallback) (
OCISvcCtxt       	*svchp, 
ub4                      operationIndex, 
OCIPipelineOperation    *hndlp, 
ub4                      operationStatus, 
void                    *callbackCtx, 
OCIError                *errhp);

Parameters

  • svchp: The service context on which the operation is executing.
  • operationIndex: Index of the operation in the operation queue of the service context.
  • hndlp: Operation handle pointer.
  • operationStatus: Status of the operation (OCI_ERROR/OCI_SUCCESS) can be any of the valid return values of the OCI function.
  • callbackCtx: Callback context is an application provided context.
  • errhp: Error handle pointer.

    Note:

    An application cannot pipeline another OCI operation in the callback. It creates a non trivial recursion.

26.1.2 OCIPipelineProcess()

Process a pipeline operation or operations given by the OCIoperationID.

Purpose

OCIPipelineProcess() processes the pending operations obtained from the earlier operations. When an application uses OCIPipelineProcess() function on a pipelined operation handle, all the pipelined bottom halve operations are queued up till this operation handle is processed. The respective callbacks are also processed. All the operations prior to the provided operation are completed before returning.

The execution of the operations is performed according to the following semantics:
  • If the application processes the first operation, only the first operation is processed.
  • If the application processes the kth operation, then all the operations prior to the kth operation are processed.
  • If the application processes the last operation, then all the operations prior the last operation are processed.

Syntax

sword OCIPipelineProcess (OCISvcCtx     *svchp,
                          OCIPipelineOperationID  opID,
	                   ub4              	timeout,
                          OCIError               *errhp,
                          ub4            	  mode);

Parameters

svchp (IN)

OCI service context.

hndl (IN/OUT)

Operation handle.

timeout (IN)

Timeout in milliseconds for this function complete or exit from the operation. If the value is set to 0, then it waits forever or till the operation is complete.

errhp (OUT)

Error handle.

mode (IN)
The supported modes are:
  • OCI_DEFAULT

The timeout specified in this function is for the set of operations executed in this call. If there are operations before the supplied operation, then all the operations are read before this one.

The following code snippet demonstrates the application executing three statements in pipeline mode and processing the bottom halves of all the three statements in order.

OCIPipelineBegin(svchp …);
OCIStmtExecute(stmthp1, ….,  OCI_DEFAULT) – Send
OCIStmtExecute(stmthp2, … ,OCI_DEFAULT) - Send
OCIStmtExecute(stmthp3, …, OCI_DEFAULT) – Send
			
OCIPipelineOperations *oparr = NULL;
ub4 arrlen = 0;
status = OCIAttrGet(svchp, OCI_HTYPE_SVC, &oparr, &arrlen, OCI_ATTR_PIPELINE_OPERATIONS, errhp, OCI_DEFAULT);
for(int i =0; i < arrlen, i< arrlen)
{  
rc = OCIPipelineProcess(svchp, oparr[i], 1000, errhp, 
                        OCI_DEFAULT); // recv (ith statement)
     if(!rc)
       break;
}
 OCIPipelineEnd(svchp, timeout …);

26.1.3 OCIPipelineEnd()

This function indicates the end of the pipeline block of operations.

Purpose

This function indicates the end of the pipeline block of operations. By default, this function is blocking. It means the function OCIPipelineEnd() is also queued up along with other operations in the pipeline. In this mode, the queued-up operations are not processed. It is the responsibility of applications to introduce the sync points. By default, this function is blocking. It reads all the operations, and sends and receives "Pipeline End" RPC. In blocking mode, it is used to process all the OCI pipeline operations associated with this service context and end the pipeline block created by OCIPipelineBegin(). The callback is called for every operation successfully executed on the server.

Syntax


sword OCIPipelineEnd (OCISvcCtx *svchp,
      	              ub4        timeout,
                      OCIError  *errhp,
        	      ub4        mode);

Parameters

svchp (IN)

OCI service context.

timeout (IN)

Timeout in milli seconds for this function to complete or quit.

errhp (OUT)

Error handle.

mode (IN)
Supported modes are:
  • OCI_DEFAULT

Returns:

  • OCI_SUCCESS: When the function is successful
  • OCI_ERROR: When this fails, the actual error can be retrieved through errhp.
The following code snippet demonstrates the usage of OCIPipelineEnd function in a service context:
OCIPipelineBegin(svchp … OCI_DEFAULT);
OCIStmtExecute(stmthp1, .. , OCI_DEFAULT) – Send
OCIStmtExecute(stmthp2, .. , OCI_DEFAULT) - Send
OCIStmtExecute(stmthp3, .. , OCI_DEFAULT) – Send

OCIPipelineEnd(svchp, timeout, errhp, OCI_DEFAULT);  
/*All 3 stmts are complete here */