Skip Headers

Oracle® Call Interface Programmer's Guide
10g Release 1 (10.1)

Part Number B10779-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to current chapter
Up
Go to next page
Next
View PDF

Miscellaneous Functions

This section describes the miscellaneous OCI functions.

Table 16-11 Miscellaneous Functions
Function Purpose

OCIBreak()

Perform an immediate asynchronous break

OCIErrorGet()

Return error message and Oracle error

OCILdaToSvcCtx()

Toggle Lda_Def to service context handle

OCIPasswordChange()

Change password

OCIReset()

Called after OCIBreak() to reset asynchronous operation and protocol

OCIRowidToChar()

Converts a Universal ROWID to character extended (base 64) representation.

OCIServerVersion()

Get the Oracle version string

OCISvcCtxToLda()

Toggle service context handle to Lda_Def

OCIUserCallbackGet()

Identifies the callback that is registered for handle

OCIUserCallbackRegister()

Registers a user-created callback function

OCIBreak()

Purpose

This call performs an immediate (asynchronous) termination of any currently executing OCI function that is associated with a server.

Syntax

sword OCIBreak ( dvoid      *hndlp,
                 OCIError   *errhp );

Parameters

hndlp (IN/OUT)

The service context handle or the server context handle.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

Comments

This call performs an immediate (asynchronous) termination of any currently executing OCI function that is associated with a server. It is normally used to stop a long-running OCI call being processed on the server.


Note:

OCIBreak() is not supported on a Windows server.


This call can take either the service context handle or the server context handle as a parameter to identify the function to be terminated.

See Also:

Related Functions

OCIReset()

OCIErrorGet()

Purpose

Returns an error message in the buffer provided and an Oracle error code.

Syntax

sword OCIErrorGet ( dvoid      *hndlp, 
                    ub4        recordno,
                    text       *sqlstate,
                    sb4        *errcodep, 
                    text       *bufp,
                    ub4        bufsiz,
                    ub4        type );

Parameters

hndlp (IN)

The error handle, in most cases, or the environment handle (for errors on OCIEnvCreate(), OCIHandleAlloc()).

recordno (IN)

Indicates the status record from which the application seeks info. Starts from 1.

sqlstate (OUT)

Not supported in release 8.x or later.

errcodep (OUT)

The error code returned.

bufp (OUT)

The error message text returned.

bufsiz (IN)

The size of the buffer provided for the error message, in number of bytes. If the error message length is less than bufsiz, a NULL string is returned. To avoid that, calculate the message length, as shown in the example which follows.

type (IN)

The type of the handle (OCI_HTYPE_ERROR or OCI_HTYPE_ENV).

Comments

This function does not support SQL statements. In most cases, hndlp is actually the error handle, or the environment handle. You should always get the message in the encoding that was set in the environment handle.This function can be called multiple times if there are more than one diagnostic record for an error.

Note that OCIErrorGet() must not be called when the return code is OCI_SUCCESS. Otherwise, an error message from a previously executed statement will be found by OCIErrorGet().

The error handle is originally allocated with a call to OCIHandleAlloc().

See Also:

For a more complete discussion of error handling see "Error Handling in OCI"

Example

Here is a simplified example of a function for error checking using OCIErrorGet():

static void checkerr(OCIError *errhp, sword status)
{
  text errbuf[512];
  ub4 buflen;
  sb4 errcode;

  if (status == OCI_SUCCESS) return;

  switch (status)
  {
  case OCI_SUCCESS_WITH_INFO:
    printf("Error - OCI_SUCCESS_WITH_INFO\n");
    OCIErrorGet ((dvoid *) errhp, (ub4) 1, (text *) NULL, &errcode,
            errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
    printf("Error - %s\n", errbuf);
    break;
  case OCI_NEED_DATA:
    printf("Error - OCI_NEED_DATA\n");
    break;
  case OCI_NO_DATA:
    printf("Error - OCI_NO_DATA\n");
    break;
  case OCI_ERROR:
    OCIErrorGet ((dvoid *) errhp, (ub4) 1, (text *) NULL, &errcode,
            errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
    printf("Error - %s\n", errbuf);
    break;
  case OCI_INVALID_HANDLE:
    printf("Error - OCI_INVALID_HANDLE\n");
    break;
  case OCI_STILL_EXECUTING:
    printf("Error - OCI_STILL_EXECUTING\n");
    break;
  case OCI_CONTINUE:
    printf("Error - OCI_CONTINUE\n");
    break;
  default:
    printf("Error - %d\n", status);
    break;
  }
}

Related Functions

OCIHandleAlloc()

OCILdaToSvcCtx()

Purpose

Converts a V7 Lda_Def to a V8 or later service context handle.

Syntax

sword OCILdaToSvcCtx ( OCISvcCtx  **svchpp,
                       OCIError   *errhp,
                       Lda_Def    *ldap );

Parameters

svchpp (IN/OUT)

The service context handle.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

ldap (IN/OUT)

The Oracle7 logon data area returned by OCISvcCtxToLda() from this service context.

Comments

Converts an Oracle7 Lda_Def to a release 8 or later service context handle. The action of this call can be reversed by passing the resulting service context handle to the OCISvcCtxToLda() function.

The OCILdaToSvcCtx() call should be used only for resetting an Lda_Def obtained from OCISvcCtxToLda() back to a service context handle. It cannot be used to transform an Lda_def which started as an Lda_def back to a service context handle.

If the service context has been converted to an Lda_Def, only Oracle7 calls may be used. It is illegal to make OCI release 8 or later calls without first resetting the Lda_Def to a service context.

The OCI_ATTR_IN_V8_MODE attribute of the server handle or service context handle enables an application to determine whether the application is currently in Oracle release 7 mode or Oracle release 8 or later mode.

See Also:

Appendix A, "Handle and Descriptor Attributes"

Related Functions

OCISvcCtxToLda()

OCIPasswordChange()

Purpose

This call allows the password of an account to be changed.

Syntax

sword OCIPasswordChange ( OCISvcCtx     *svchp,
                          OCIError      *errhp,
                          CONST text    *user_name,
                          ub4           usernm_len,
                          CONST text    *opasswd,
                          ub4           opasswd_len,
                          CONST text    *npasswd,
                          sb4           npasswd_len,
                          ub4           mode );

Parameters

svchp (IN/OUT)

A handle to a service context. The service context handle must be initialized and have a server context handle associated with it.

errhp (IN)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

user_name (IN)

Specifies the user name, which can be in UTF-16 encoding. It must be terminated with a NULL character if the service context has been initialized with an authentication handle.

usernm_len (IN)

The length of the user name string specified in user_name, in number of bytes regardless of the encoding. usernm_len must be nonzero.

opasswd (IN)

Specifies the user's old password, which can be in UTF-16 encoding.

opasswd_len (IN)

The length of the old password string specified in opasswd, in bytes. opasswd_len must be nonzero.

npasswd (IN)

Specifies the user's new password, which can be in UTF-16 encoding. If the password complexity verification routine is specified in the user's profile to verify the new password's complexity, the new password must meet the complexity requirements of the verification function.

npasswd_len (IN)

The length in bytes of the new password string specified in npasswd. For a valid password string, npasswd_len must be nonzero.

mode (IN)

Comments

This call allows the password of an account to be changed. This call is similar to OCISessionBegin() with the following differences:

This call is useful when the password of an account has expired and OCISessionBegin() returns an error (ORA-28001) or warning that indicates that the password has expired.

The mode or the environment handle determines if UTF-16 is being used.

Related Functions

OCISessionBegin()

OCIReset()

Purpose

Resets the interrupted asynchronous operation and protocol. Must be called if a OCIBreak call had been issued while a nonblocking operation was in progress.

Syntax

sword OCIReset ( dvoid      *hndlp,
                 OCIError   *errhp );

Parameters

hndlp (IN)

The service context handle or the server context handle.

errhp (IN)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

Comments

This call is called in nonblocking mode only. Resets the interrupted asynchronous operation and protocol. Must be called if an OCIBreak() call had been issued while a nonblocking operation was in progress.

Related Functions

OCIBreak()

OCIRowidToChar()

Purpose

Converts a Universal ROWID to character extended (base 64) representation.

Syntax

sword OCIRowidToChar ( OCIRowid      *rowidDesc,
                       OraText       *outbfp,
                       ub2           *outbflp
                       OCIError      *errhp );

Parameters

rowidDesc (IN)

The ROWID descriptor which is allocated by OCIDescriptorAlloc() and populated by a prior execution of a SQL statement.

outbfp (OUT)

Pointer to the buffer where the character representation is stored after successful execution of this call.

outbflp (IN/OUT)

Pointer to the output buffer length. Before execution, the buffer length contains the size of outbfp. After execution it contains the number of bytes converted.

In the event of truncation during conversion, outbfp contains the length required to make conversion successful. An error is also returned.

errhp (IN)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

Comments

After this conversion, the ROWID in character format can be bound with the OCIBindByPos() or OCIBindByName() calls, and used to query a row at the given ROWID.

OCIServerVersion()

Purpose

Returns the version string of the Oracle server.

Syntax

sword OCIServerVersion ( dvoid        *hndlp, 
                         OCIError     *errhp, 
                         text         *bufp,
                         ub4          bufsz
                         ub1          hndltype );

Parameters

hndlp (IN)

The service context handle or the server context handle.

errhp (IN)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

bufp (IN)

The buffer in which the version information is returned.

bufsz (IN)

The length of the buffer. In number of bytes.

hndltype (IN)

The type of handle passed to the function.

Comments

This call returns the version string of the Oracle server. It can be in Unicode if the environment handle so determines.

For example, the following might be returned as the version string if an application is running on an 8.1.5 SunOS server:

Oracle8i Enterprise Edition Release 8.1.5.0.0 - Production
With the Partitioning and Java options
PL/SQL Release 8.1.5.0.0 - Production

Related Functions

OCIErrorGet()

OCISvcCtxToLda()

Purpose

Toggles between a V8 or later service context handle and a V7 Lda_Def.

Syntax

sword OCISvcCtxToLda ( OCISvcCtx    *srvhp,
                       OCIError     *errhp,
                       Lda_Def      *ldap );

Parameters

svchp (IN/OUT)

The service context handle.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

ldap (IN/OUT)

A Logon Data Area for Oracle7-style OCI calls which is initialized by this call.

Comments

Toggles between an OCI release 8 or later service context handle and an Oracle7 Lda_Def.

This function can only be called after a service context has been properly initialized.

Once the service context has been translated to an Lda_Def, it can be used in release 7.x OCI calls (for example, obindps(), ofen()).

If there are multiple service contexts which share the same server handle, only one can be in Oracle7 mode at any time.

The action of this call can be reversed by passing the resulting Lda_Def to the OCILdaToSvcCtx() function.

The OCI_ATTR_IN_V8_MODE attribute of the server handle or service context handle enables an application to determine whether the application is currently in Oracle release 7 mode or Oracle release 8 or later mode.

See Also:

Appendix A, "Handle and Descriptor Attributes"

Related Functions

OCILdaToSvcCtx()

OCIUserCallbackGet()

Purpose

Determines the callback that is registered for a handle.

Syntax

sword OCIUserCallbackGet ( dvoid   *hndlp,
                           ub4     type,
                           dvoid   *ehndlp,
                           ub4     fcode,
                           ub4     when,
                           OCIUserCallback (*callbackp)
                                           (
                                             dvoid  *ctxp,
                                             dvoid  *hndlp,
                                             ub4  type,
                                             ub4  fcode,
                                             ub1  when,
                                             sword  returnCode,
                                             ub4  *errnop,
                                             va_list arglist
                                            ),
                           dvoid   **ctxpp,
                           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().

fcode (IN)

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

when (IN)

Defines when the callback is invoked. Valid modes are:

callbackp (OUT)

A pointer to a callback function pointer. This returns the function that is currently registered for these values of fcode, when, and hndlp. The value returned would be NULL if no callback is registered for this case.

See Also:

For information about the parameters of callbackp see the description of OCIUserCallbackRegister()

ctxpp (OUT)

A pointer to return context for the currently registered callback.

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 because they do not have a ucb descriptor to use.

Comments

This function finds out what callback is registered for a particular handle.

See Also:

For information on the restrictions of the use of callback functions, see "Restrictions on Callback Functions".

Related Functions

OCIUserCallbackRegister()

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 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-12, "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 in OCI".

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,
            sb4     *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-12, "OCI Function Codes". Please note that callbacks can be registered for only the OCI calls listed in Table 16-7, "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-12 OCI Function Codes   
# OCI Routine # OCI Routine # OCI Routine

1

OCIInitialize

33

OCITransStart

65

OCIDefineByPos

2

OCIHandleAlloc

34

OCITransDetach

66

OCIBindByPos

3

OCIHandleFree

35

OCITransCommit

67

OCIBindByName

4

OCIDescriptorAlloc

36

(not used)

68

OCILobAssign

5

OCIDescriptorFree

37

OCIErrorGet

69

OCILobIsEqual

6

OCIEnvInit

38

OCILobFileOpen

70

OCILobLocatorIsInit

7

OCIServerAttach

39

OCILobFileClose

71

OCILobEnableBuffering

8

OCIServerDetach

40

(not used)

72

OCILobCharSetID

9

(not used)

41

(not used)

73

OCILobCharSetForm

10

OCISessionBegin

42

OCILobCopy, OCILobCopy2

74

OCILobFileSetName

11

OCISessionEnd

43

OCILobAppend

75

OCILobFileGetName

12

OCIPasswordChange

44

OCILobErase, OCILobErase2

76

OCILogon

13

OCIStmtPrepare

45

OCILobGetLength, OCILobGetLength2

77

OCILogoff

14

(not used)

46

OCILobTrim, OCILobTrim2

78

OCILobDisableBuffering

15

(not used)

47

,OCILobRead OCILobRead2

79

OCILobFlushBuffer

16

(not used)

48

OCILobWrite, OCILobWrite2

80

OCILobLoadFromFile, OCILobLoadFromFile2

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()