Skip Headers
Oracle® Call Interface Programmer's Guide
11g Release 1 (11.1)

B28395-12
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

Cartridge Services — OCI External Procedures

The OCI external procedure functions for C:

Table 20-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

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

See Also:

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.

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)

Pointer to a variable to store the OCI environment handle.

svch (OUT)

Pointer to a variable to store the OCI service handle.

errh (OUT)

Pointer to a variable to store 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.

Example of a call:

OCIEnv    *envh;
OCISvcCtx *svch;
OCIError  *errh;
...
OCIExtProcGetEnv(ctx,&envh,&svch,&errh);

Returns

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