Oracle Call Interface Programmer's Guide, Volumes 1 & 2 Release 8.0 A58234-01 |
Library | Product | Contents | Index

# 16
OCI External Procedure Functions

The chapter contains the following sections:

- Introduction
- The OCI External Procedure Functions

## Introduction

This chapter describes the OCI External Procedure Functions. These functions enable users of external procedures to raise errors, allocate some memory, and get OCI context information. For more information about using these functions, refer to the PL/SQL User's Guide and Reference.

### Return Codes

Success and error return codes are defined for certain external procedure interface functions. If a particular interface function returns OCIEXTPROC_SUCCESS or OCIEXTPROC_ERROR, then applications must use these macros to check for return values.

OCIEXTPROC_SUCCESS - External Procedure Success Return Code

OCIEXTPROC_ERROR - External Procedure Failure Return Code

### With_Context Type

The C callable interface to PL/SQL external procedures requires the with_context parameter to be passed. The type of this structure is OCIExtProcContext, which is opaque to the user.

The user can declare the with_context parameter in the application as

    OCIExtProcContext *with_context;

## The OCI External Procedure Functions

The remainder of this chapter specifies the release 8.0 OCI external procedure functions for C. For each function, the following information is listed:

### Purpose

A brief description of the action performed by the function.

### Syntax

A code snippet showing the syntax for calling the function, including the ordering and types of the parameters.

### Parameters

A description of each of the function's parameters. This includes the parameter's mode. The mode of a parameter has three possible values, as described below:

Mode | Description
--- | ---
IN | A parameter that passes data to Oracle
OUT | A parameter that receives data from Oracle on this or a subsequent call
IN/OUT | A parameter that passes data on the call and receives data on the return from this or a subsequent call.

### Comments

More detailed information about the function (if available). This may include restrictions on the use of the function, or other information that might be useful when using the function in an application.

### Returns

A list of possible return values for the function.

### Example

A complete or partial code example demonstrating the use of the function call being described. Not all function descriptions include an example.

### Related Functions

A list of related function calls.

## 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" on page 16-2.

##### 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

## 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" on page 16-2.

##### 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

OCIEXTPROC_SUCCESS - If the call was successful.

OCIEXTPROC_ERROR - If the call 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. See "With_Context Type" on page 16-2.

##### 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

OCIEXTPROC_SUCCESS - If the call was successful.

OCIEXTPROC_ERROR - If the call failed.

### Related Functions

OCIExtProcRaiseExcp()

## OCIExtProcGetEnv()

### Purpose

Get OCI Environment

### 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" on page 16-2.

##### envh (OUT)

The OCI Environment handle.

##### svch (OUT)

The OCI Service handle.

##### errh (OUT)

The OCI Error handle.

### Comments

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

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

OCI_SUCCESS, on successful completion of the function.

OCI_ERROR, on error.

### Related Functions

Prev | Next
| Copyright © 1997 Oracle Corporation. All Rights Reserved. |
Library | Product | Contents | Index