Oracle Call Interface Programmer's Guide
Release 9.0.1

Part Number A89857-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Go to previous page Go to beginning of chapter Go to next page

More OCI Relational Functions, 97 of 97


OCIUserCallbackRegister()

Purpose

Register a user-created callback function

Syntax

sword OCIUserCallbackRegister ( dvoid   *hndlp,
                                ub4      type,
                                dvoid   *ehndlp,
                                OCIUserCallback  (callback)
                                                 (/*_ 
                                                    dvoid  *ctxp,
                                                    dvoid  *hndlp,
                                                    ub4  type,
                                                    ub4  fcode,
                                                    ub1  when,
                                                    sword  returnCode,
                                                    ub4  *errnop,
                                                    va_list arglist
                                                 _*/),
                               dvoid    *ctxp,
                               ub4      fcode,
                               ub4      when 
                               OCIUcb   *ucbDesc );

Parameters

hndlp (IN)

This is the handle whose type is specified by the type parameter.

type (IN)

The handle type. The valid handle type is:

ehndlp (IN)

The OCI error or environment handle. If there is an error, it is recorded in ehndlp and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet(). Note that the because an error handle is not available within OCIEnvCallback, so the environment handle is passed in as a ehndlp.

callback (IN)

A callback function pointer. The variable argument list in the OCIUserCallback function prototype are the parameters passed to the OCI function. The typedef for OCIUserCallback is described below later.

If an entry callback returns anything other than OCI_CONTINUE, then the return code is passed to the subsequent entry or replacement callback, if there is one. If this is the last entry callback and there is no replacement callback, then the OCI code is executed and the return code is ignored.

If a replacement callback returns anything other than OCI_CONTINUE, then subsequent replacement callbacks and the OCI code are bypassed, and processing jumps to the exit callbacks.

If the exit callback returns anything other than OCI_CONTINUE, then that returned value is returned by the OCI function; otherwise, the return value from the OCI code or the replacement callback (if the replacement callback did not return OCI_CONTINUE and essentially bypassed the OCI code) is returned by the call.

If a null value is passed in for callback, then the callback is removed for the when value and the specified handle. This is the way to de-register a callback for a given ucbDesc value, including the null ucbDesc.

ctxp (IN)

A context pointer for the callback.

fcode (IN)

A unique function code of an OCI function. These are listed in Table 16-7, "OCI Function Codes".

when (IN)

Defines when the callback is invoked. Valid modes are:

ucbDesc (IN)

An OCI provided descriptor. This descriptor is passed by OCI in the environment callback. It contains the priority at which the callback would be registered at. If the ucbDesc parameter is specified as null, then this callback has the highest priority.

User callbacks registered statically (as opposed to those registered dynamically in a package) use a null descriptor as they do not have a ucb descriptor to use.

Comments

This function is used to register a user-created callback functions.s with the OCI environment.

See Also:

For a more complete discussion, see "User-Defined Callback Functions"

Such callbacks allow an application to:

  1. Trace OCI calls for debugging and performance measurements.

  2. Perform additional pre- or post-processing after selected OCI calls.

  3. Substitute the body of a given function with proprietary code to execute on a foreign data source.

The OCI supports these kinds of callbacks: entry callbacks, replacement callbacks, and exit callbacks.

The three types of callbacks are identified by the modes OCI_UCBTYPE_ENTRY, OCI_UCBTYPE_REPLACE, and OCI_UCBTYPE_EXIT.

The control flow now is:

Entry callbacks are executed when a program enters an OCI function.

Replacement callbacks are executed after entry callbacks. If the replacement callback returns a value of OCI_CONTINUE, then subsequent replacement callbacks or the normal OCI-specific code is executed. If the callback returns anything other than OCI_CONTINUE, then subsequent replacement callbacks and the OCI code do not execute.

After an OCI function successfully executes, or after a replacement callback returns something other than OCI_CONTINUE, program control transfers to the exit callback (if one is registered).

If a replacement or exit callback returns anything other than OCI_CONTINUE, then the return code from the callback is returned from the associated OCI call.

To find out the callback that is registered for the handle, you can use OCIUserCallbackGet().

The prototype of the OCIUserCallback typedef is:

typedef sword (*OCIUserCallback) 
           (dvoid   *ctxp,
            dvoid   *hndlp,
            ub4     type,
            ub4     fcode,
            ub4     when,
            sword  returnCode,
            ub4    *errnop,
            va_list arglist
            );

The parameters to the OCIUserCallback function prototype are:

ctxp (IN)

The context passed in as ctxp in the register callback function.

hndlp (IN)

This is the handle whose type is specified in the type parameter. It is the handle on which the callback is invoked. Because we only allow a type of OCI_HTYPE_ENV, therefore, the environment handle, env, would be passed-in here.

type (IN)

The type registered for the hndlp. The valid handle type is:

fcode (IN)

The function code of the OCI call. These are listed in Table 16-7, "OCI Function Codes". Please note that callbacks can be registered for only the OCI calls listed in Table 16-2, "Advanced Queuing and Publish-Subscribe Functions".

when (IN)

The when value of the callback.

returnCode (IN)

This is the return code from the previous callback or the OCI code. For the first entry callback, OCI_SUCCESS will always be passed in. For the subsequent callbacks, the return code from the OCI code or the previous callback is passed in.

errnop (IN/OUT)

When the first entry callback is called, the input value of *errnop is 0. If the callback is returning any value other than an OCI_CONTINUE, then it must also set an error number in *errnop. This value is the set in the error handle passed in the OCI call.

For all subsequent callbacks, the input value of *errnop is the value of error number in the error handle. Therefore, if the previous callback did not return OCI_CONTINUE, then the out value of *errnop from the previous callback would be the one in the error handle, and that value would be passed in here to the subsequent callback. If, on the other hand, the previous callback returned OCI_CONTINUE, then whatever value that is in the error handle would be passed in here.

Note that if a non-Oracle error number is returned in *errnop, then a callback must also be registered for the OCIErrorGet() function to return appropriate text for the error number.

arglist (IN)

These are the parameters to the OCI call passed in here as variable number of arguments. They should be de-referenced using va_arg, as illustrated in the user callback demonstration programs.

See Also:

See Appendix B, "OCI Demonstration Programs" for a list of the available demonstration programs. 

Table 16-7 OCI Function Codes   
#  OCI Routine  #  OCI Routine  #  OCI Routine 

OCIInitialize 

33 

OCITransStart 

65 

OCIDefineByPos 

OCIHandleAlloc 

34 

OCITransDetach 

66 

OCIBindByPos 

OCIHandleFree 

35 

OCITransCommit 

67 

OCIBindByName 

OCIDescriptorAlloc 

36 

(not used) 

68 

OCILobAssign 

OCIDescriptorFree 

37 

OCIErrorGet 

69 

OCILobIsEqual 

OCIEnvInit 

38 

OCILobFileOpen 

70 

OCILobLocatorIsInit 

OCIServerAttach 

39 

OCILobFileClose 

71 

OCILobEnableBuffering 

OCIServerDetach 

40 

(not used) 

72 

OCILobCharSetID 

(not used) 

41 

(not used) 

73 

OCILobCharSetForm 

10 

OCISessionBegin 

42 

OCILobCopy 

74 

OCILobFileSetName 

11 

OCISessionEnd 

43 

OCILobAppend 

75 

OCILobFileGetName 

12 

OCIPasswordChange 

44 

OCILobErase 

76 

OCILogon 

13 

OCIStmtPrepare 

45 

OCILobGetLength 

77 

OCILogoff 

14 

(not used) 

46 

OCILobTrim 

78 

OCILobDisableBuffering 

15 

(not used) 

47 

OCILobRead 

79 

OCILobFlushBuffer 

16 

(not used) 

48 

OCILobWrite 

80 

OCILobLoadFromFile 

17 

OCIBindDynamic 

49 

(not used) 

81 

OCILobOpen 

18 

OCIBindObject 

50 

OCIBreak 

82 

OCILobClose 

19 

(not used) 

51 

OCIServerVersion 

83 

OCILobIsOpen 

20 

OCIBindArrayOfStruct 

52 

(not used) 

84 

OCILobFileIsOpen 

21 

OCIStmtExecute 

53 

(not used) 

85 

OCILobFileExists 

22 

(not used) 

54 

OCIAttrGet 

86 

OCILobFileCloseAll 

23 

(not used) 

55 

OCIAttrSet 

87 

OCILobCreateTemporary 

24 

(not used) 

56 

OCIParamSet 

88 

OCILobFreeTemporary 

25 

OCIDefineObject 

57 

OCIParamGet 

89 

OCILobIsTemporary 

26 

OCIDefineDynamic 

58 

OCIStmtGetPieceInfo 

90 

OCIAQEnq 

27 

OCIDefineArrayOfStruct 

59 

OCILdaToSvcCtx 

91 

OCIAQDeq 

28 

OCIStmtFetch 

60 

(not used) 

92 

OCIReset 

29 

OCIStmtGetBindInfo 

61 

OCIStmtSetPieceInfo 

93 

OCISvcCtxToLda 

30 

(not used) 

62 

OCITransForget 

94 

OCILobLocatorAssign 

31 

(not used) 

63 

OCITransPrepare 

95 

(not used) 

32 

OCIDescribeAny 

64 

OCITransRollback 

96 

OCIAQListen 

Related Functions

OCIUserCallbackGet()


Go to previous page Go to beginning of chapter Go to next page
Oracle
Copyright © 1996-2001, Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback