Release 8.0
A54656_01
 Library |
 Product |
 Contents |
 Index |
| Programmer's Guide to the Oracle Call Interface Release 8.0 A54656_01 |
|
The chapter contains the following sections:
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.
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
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 remainder of this chapter specifies the release 8.0 OCI external procedure functions for C. For each function, the following information is listed:
The descriptive name of the function from which the actual function name is derived. This can be useful for remembering the purpose of the function.
A brief description of the action performed by the function.
A code snippet showing the syntax for calling the function, including the ordering and types of the 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 in Table 16-1
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.
A list of possible return values for the function.
A complete or partial code example demonstrating the use of the function call being described. Not all function descriptions include an example.
A list of related function calls.
Allocate N bytes of memory for the duration of the External Procedure.
dvoid * OCIExtProcAllocCallMemory ( OCIExtProcContext *with_context, size_t amount )
with_context (IN) - The with_context pointer that is passed to the C External Procedure.
amount (IN) - The number of bytes to allocate.
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
An untyped (opaque) Pointer to the allocated memory.
text *ptr = (text *)OCIExtProcAllocCallMemory(wctx, 1024)
Raise an Exception to PL/SQL.
size_t OCIExtProcRaiseExcp ( OCIExtProcContext *with_context, int errnum )
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.
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.
OCIEXTPROC_SUCCESS - If the call was successful.
OCIEXTPROC_ERROR - If the call failed.
Raise an exception with a message.
size_t OCIExtProcRaiseExcpWithMsg ( OCIExtProcContext *with_context, int errnum, char *errmsg, size_t msglen )
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.
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.
OCIEXTPROC_SUCCESS - If the call was successful.
OCIEXTPROC_ERROR - If the call failed.
Get OCI Environment
sword OCIExtProcGetEnv ( OCIExtProcContext *with_context, OCIEnv envh, OCISvcCtx svch, OCIError errh )
with_context (IN) - The with_context pointer that is passed to the C External Procedure.
envh (OUT) - The OCI Environment handle.
svch (OUT) - The OCI Service handle.
errh (OUT) - The OCI Error handle.
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.
OCI_SUCCESS, on successful completion of the function.
OCI_ERROR, on error.
