Cartridge Services -- OCI External Procedures

The OCI external procedure functions for C:

Table 19-2 External Procedures Functions

Function/Page	Purpose
OCIExtProcAllocCallMemory()	Allocates memory for the duration of the External Procedure
OCIExtProcRaiseExcp()	Raises an Exception to PL/SQL
OCIExtProcRaiseExcpWithMsg()	Raises an exception with a message
OCIExtProcGetEnv()	Gets the OCI environment, service context, and error handles

OCIExtProcAllocCallMemory()

Purpose

Allocate N bytes of memory for the duration of the External Procedure.

Syntax

dvoid * OCIExtProcAllocCallMemory ( OCIExtProcContext    *with_context,
                                    size_t                amount );
Parameters

with_context (IN)

The with_context pointer that is passed to the C External Procedure.

amount (IN)

The number of bytes to allocate.

Comments

This call allocates amount bytes of memory for the duration of the call of the external procedure.

Any memory allocated by this call is freed by PL/SQL upon return from the external procedure. The application must not use any kind of free() function on memory allocated by OCIExtProcAllocCallMemory(). Use this function to allocate memory for function returns.

A zero return value should be treated as an error

Returns

An untyped (opaque) Pointer to the allocated memory.

Example

text *ptr = (text *)OCIExtProcAllocCallMemory(wctx, 1024)

Related Functions

OCIErrorGet(), OCIMemoryAlloc().

OCIExtProcRaiseExcp()

Purpose

Raise an Exception to PL/SQL.

Syntax

size_t OCIExtProcRaiseExcp ( OCIExtProcContext    *with_context, 
                             int                   errnum );
Parameters

with_context (IN)

The with_context pointer that is passed to the C External Procedure.

errnum (IN)

Oracle Error number to signal to PL/SQL. errnum must be a positive number and in the range 1 to 32767.

Comments

Calling this function signals an exception back to PL/SQL. After a successful return from this function, the external procedure must start its exit handling and return back to PL/SQL. Once an exception is signalled to PL/SQL, IN/OUT and OUT arguments, if any, are not processed at all.

Returns

This function returns OCIEXTPROC_SUCCESS if the call was successful. It returns OCIEXTPROC_ERROR if the call has failed.

Related Functions

OCIExtProcRaiseExcpWithMsg()

OCIExtProcRaiseExcpWithMsg()

Purpose

Raise an exception with a message.

Syntax

size_t OCIExtProcRaiseExcpWithMsg ( OCIExtProcContext   *with_context,
                                    int                  errnum, 
                                    char                 *errmsg, 
                                    size_t               msglen );

Parameters

with_context (IN)

The with_context pointer that is passed to the C External Procedure.

errnum (IN)

Oracle Error number to signal to PL/SQL. The value of errnum must be a positive number and in the range 1 to 32767

errmsg (IN)

The error message associated with the errnum.

len (IN)

The length of the error message. Pass zero if errmsg is a NULL-terminated string.

Comments

Raise an exception to PL/SQL. In addition, substitute the following error message string within the standard Oracle error message string.

Returns

This function returns OCIEXTPROC_SUCCESS if the call was successful. It returns OCIEXTPROC_ERROR if the call has failed.

Related Functions

OCIExtProcRaiseExcp()

OCIExtProcGetEnv()

Purpose

Gets the OCI environment, service context, and error handles.

Syntax

sword OCIExtProcGetEnv ( OCIExtProcContext    *with_context, 
                         OCIEnv                envh, 
                         OCISvcCtx             svch, 
                         OCIError              errh );
Parameters

with_context (IN)

The with_context pointer that is passed to the C External Procedure. See "With_Context Type".

envh (OUT)

The OCI Environment handle.

svch (OUT)

The OCI Service handle.

errh (OUT)

The OCI Error handle.

Comments

The primary purpose of this function is to allow OCI callbacks to use the database in the same transaction. The OCI handles obtained by this function should be used in OCI callbacks to the database. If these handles are obtained through standard OCI calls, then these handles use a new connection to the database and cannot be used for callbacks in the same transaction. In one external procedure you can use either callbacks or a new connection, but not both.

Returns

This function returns OCI_SUCCESS if the call was successful; otherwise, it returns OCI_ERROR.

Related Functions

OCIEnvCreate(), OCIAttrGet(), OCIHandleAlloc()