Release 8.1.5
A67846-01
 Library |
 Product |
 Contents |
 Index |
| Oracle Call Interface Programmer's Guide Release 8.1.5 A67846-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 Oracle8i Application Developer's Guide - Fundamentals.
For each function, the following information is listed:
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 below:
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.
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.
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 OCI external procedure functions for C.
Allocate N bytes of memory for the duration of the External Procedure.
dvoid * OCIExtProcAllocCallMemory ( OCIExtProcContext *with_context, size_t amount )
The with_context pointer that is passed to the C External Procedure. See "With_Context Type".
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 )
The with_context pointer that is passed to the C External Procedure. See "With_Context Type".
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.
This function returns OCIEXTPROC_SUCCESS if the call was successful. It returns OCIEXTPROC_ERROR if the call has failed.
Raise an exception with a message.
size_t OCIExtProcRaiseExcpWithMsg ( OCIExtProcContext *with_context, int errnum, char *errmsg, size_t msglen )
The with_context pointer that is passed to the C External Procedure. See "With_Context Type".
Oracle Error number to signal to PL/SQL. The value of errnum must be a positive number and in the range 1 to 32767
The error message associated with the errnum.
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.
This function returns OCIEXTPROC_SUCCESS if the call was successful. It returns OCIEXTPROC_ERROR if the call has failed.
Gets the OCI environment, service context, and error handles.
sword OCIExtProcGetEnv ( OCIExtProcContext *with_context, OCIEnv envh, OCISvcCtx svch, OCIError errh )
The with_context pointer that is passed to the C External Procedure. See "With_Context Type".
The OCI Environment handle.
The OCI Service handle.
The OCI Error handle.
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.
This function returns OCI_SUCCESS if the call was successful; otherwise, it returns OCI_ERROR.
OCIEnvCreate(), OCIAttrGet(), OCIHandleAlloc()
