Cartridge Services -- OCI External Procedures

The following are OCI external procedure functions for C:

Table 13-1 OCI External Procedure Functions Quick Reference  

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. See "With_Context Type"[XXX ADD PAGE REF? XXX].

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.

Table 13-2 OCIExtProcAllocCallMemory Keywords/Parameters

Keyword/Parameter	Meaning
with_context (IN)	the with_context pointer that is passed to the C External Procedure
amount (IN)	the number of bytes to allocate

Example

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

Related Functions

OCIErrorGet(), OCIMemoryAlloc(). See Oracle8i Application Developer's Guide - Fundamentals for details on these calls.

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. See "With_Context Type"[XXX ADD PAGE REF? XXX].

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.

  Table 13-3 OCIExtProcRaiseExcp Keywords/Parameters

  Keyword/Parameter	Meaning
  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

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. See "With_Context Type"[XXX ADD PAGE REF? XXX].

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. See the description of OCIExtProcRaiseExcp() for more information.

Returns

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

Table 13-4 OCIExtProcRaiseExcpWithMsg Keywords/Parameters

Keyword/Parameter	Meaning
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
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

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"[XXX ADD PAGE REF? XXX].

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(). See Oracle8i Application Developer's Guide - Fundamentals for details on these calls.