Oracle Call Interface Programmer's Guide, Volumes 1 & 2
Release 8.0

A58234-01

Library

Product

Contents

Index

Prev Next

16
OCI External Procedure Functions

The chapter contains the following sections:


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
Oracle
Copyright © 1997 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index