Oracle Call Interface Programmer's Guide
Release 8.1.5

A67846-01

Library

Product

Contents

Index

Prev Next

15
OCI Relational Functions

This chapter describes the Oracle OCI relational functions for C. It includes information about calling OCI functions in your application, along with detailed descriptions of each function call. This chapter contains the following sections:

Introduction

This chapter describes the OCI relational function calls. This chapter covers those functions in the basic OCI. The function calls for manipulating objects are described in the next three chapters. For information about return codes and error handling, refer to the section "Error Handling".

Function Syntax

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 the OCI  

OUT  

A parameter that receives data from the OCI on this 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.

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.

Calling OCI Functions

Unlike earlier versions of the OCI, in release 8i you cannot pass -1 for the string length parameter of a null-terminated string.

When you pass string lengths as parameters, do not include the NULL terminator byte in the length. The OCI does not expect strings to be NULL-terminated.

Server Roundtrips for LOB Functions

For a table showing the number of server roundtrips required for individual OCI LOB functions, refer to Appendix C, "OCI Function Server Roundtrips".

Advanced Queuing and Publish-Subscribe Functions

This section describes the advanced queuing and publish-subscribe functions.

Table 15-1 OCI Quick Reference
Function  Purpose 

OCIAQDeq()  

Advanced queueing dequeue  

OCIAQEnq()  

Advanced queueing enqueue  

OCIAQListen()  

Listens on one or more queues on behalf of a list of agents  

OCISubscriptionEnable()  

Enables notifications on a subscription  

OCISubscriptionPost()  

Posts to a subscription to receive notifications  

OCISubscriptionRegister()  

Registers a subscription  

OCISubscriptionUnRegister()  

Unregisters a subscription  


OCIAQDeq()

Purpose

This call is used for an Advanced Queueing dequeue operation using the OCI.

Syntax

sword OCIAQDeq ( OCISvcCtx           *svch,
                 OCIError            *errh,
                 text                *queue_name,
                 OCIAQDeqOptions     *dequeue_options,
                 OCIAQMsgProperties  *message_properties,
                 OCIType             *payload_tdo,
                 dvoid               **payload,
                 dvoid               **payload_ind,
                 OCIRaw              **msgid,
                 ub4                 flags );

Parameters

svch (IN)

OCI service context.

errh (IN)

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

queue_name (IN)

The target queue for the dequeue operation.

dequeue_options (IN)

The options for the dequeue operation; stored in an OCIAQDeqOptions descriptor.

message_properties (OUT)

The message properties for the message; stored in an OCIAQMsgProperties descriptor.

payload_tdo (IN)

The TDO (type descriptor object) of an object type. For a raw queue, this parameter should point to the TDO of SYS.RAW.

payload (IN/OUT)

A pointer to a pointer to a program variable buffer that is an instance of an object type. For a raw queue, this parameter should point to an instance of OCIRaw.

Memory for the payload is dynamically allocated in the object cache. The application can optionally call OCIObjectFree() to deallocate the payload instance when it is no longer needed. If the pointer to the program variable buffer ( *payload) is passed as NULL, the buffer is implicitly allocated in the cache.

The application may choose to pass NULL for payload the first time OCIAQDeq() is called, and let the OCI allocate the memory for the payload. It can then use a pointer to that previously allocated memory in subsequent calls to OCIAQDeq().

To obtain a TDO for the payload, use OCITypeByName(), or OCITypeByRef().

The OCI provides functions which allow the user to set attributes of the payload, such as its text. For information about setting these attributes, refer to "Manipulating Object Attributes".

payload_ind (IN/OUT)

A pointer to a pointer to the program variable buffer containing the parallel indicator structure for the object type.

The memory allocation rules for payload_ind are the same as those for payload, above.

msgid (OUT)

The message ID.

flags (IN)

Not currently used; pass as OCI_DEFAULT.

Comments

Users must have the aq_user_role or privileges to execute the dbms_aq package in order to use this call. The OCI environment must be initialized in object mode (using OCIInitialize()) to use this call.

For more information about OCI and Advanced Queueing, refer to "OCI and Advanced Queuing".

For additional information about Advanced Queueing, refer to Oracle8i Application Developer's Guide - Advanced Queuing.

Examples

For code examples, refer to the description of OCIAQEnq().

Related Functions

OCIAQEnq(), OCIAQListen(), OCIInitialize()


OCIAQEnq()

Purpose

This call is used for an advanced queueing enqueue.

Syntax

sword OCIAQEnq ( OCISvcCtx           *svch,
                 OCIError            *errh,
                 text                *queue_name,
                 OCIAQEnqOptions     *enqueue_options,
                 OCIAQMsgProperties  *message_properties,
                 OCIType             *payload_tdo,
                 dvoid               **payload,
                 dvoid               **payload_ind,
                 OCIRaw              **msgid,
                 ub4                 flags );

Parameters

svch (IN)

OCI service context.

errh (IN)

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

queue_name (IN)

The target queue for the enqueue operation.

enqueue_options (IN)

The options for the enqueue operation; stored in an OCIAQEnqOptions descriptor.

message_properties (IN)

The message properties for the message; stored in an OCIAQMsgProperties descriptor.

payload_tdo (IN)

The TDO (type descriptor object) of an object type. For a raw queue, this parameter should point to the TDO of SYS.RAW.

payload (IN)

A pointer to a pointer to an instance of an object type. For a raw queue, this parameter should point to an instance of OCIRaw.

The OCI provides functions which allow the user to set attributes of the payload, such as its text. For information about setting these attributes, refer to "Manipulating Object Attributes".

payload_ind (IN)

A pointer to a pointer to the program variable buffer containing the parallel indicator structure for the object type.

msgid (OUT)

The message ID.

flags (IN)

Not currently used; pass as OCI_DEFAULT.

Comments

Users must have the aq_user_role or privileges to execute the dbms_aq package in order to use this call.

The OCI environment must be initialized in object mode (using OCIInitialize()) to use this call.

For more information about OCI and Advanced Queueing, refer to "OCI and Advanced Queuing".

For additional information about Advanced Queueing, refer to Oracle8i Application Developer's Guide - Advanced Queuing.

To obtain a TDO for the payload, use OCITypeByName(), or OCITypeByRef().

Examples

The following four examples demonstrate the use of OCIAQEnq() and OCIAQDeq() in several different situations.

These examples assume that the database is set up as illustrated in the section "Oracle Advanced Queueing By Example" in the advanced queueing chapter of the Oracle8i Application Developer's Guide - Advanced Queuing.

Example 1

Enqueue and dequeue of a payload object.

struct message
{
  OCIString   *subject;
  OCIString   *data;
};
typedef struct message message;

struct null_message
{
  OCIInd    null_adt;
  OCIInd    null_subject;
  OCIInd    null_data;
};
typedef struct null_message null_message;

int main()
{
  OCIEnv *envhp;
  OCIServer *srvhp;
  OCIError *errhp;
  OCISvcCtx *svchp;
  dvoid     *tmp;
  OCIType *mesg_tdo = (OCIType *) 0;
  message  msg;
  null_message nmsg;
  message *mesg = &msg;
  null_message *nmesg = &nmsg;
  message *deqmesg = (message *)0;
  null_message *ndeqmesg = (null_message *)0;
  
  OCIInitialize((ub4) OCI_OBJECT, (dvoid *)0,  (dvoid * (*)()) 0,
                (dvoid * (*)()) 0,  (void (*)()) 0 );
  
  OCIHandleAlloc( (dvoid *) NULL, (dvoid **) &envhp, (ub4) OCI_HTYPE_ENV,
                  52, (dvoid **) &tmp);
  
  OCIEnvInit( &envhp, (ub4) OCI_DEFAULT, 21, (dvoid **) &tmp  );
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, (ub4) OCI_HTYPE_ERROR,
                    52, (dvoid **) &tmp);
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4) OCI_HTYPE_SERVER,
                    52, (dvoid **) &tmp);
  
  OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4) OCI_HTYPE_SVCCTX,
                  52, (dvoid **) &tmp);
  OCIAttrSet( (dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX, (dvoid *)srvhp, (ub4) 0,
                  (ub4) OCI_ATTR_SERVER, (OCIError *) errhp);
 
  OCILogon(envhp, errhp, &svchp, "AQ", strlen("AQ"), "AQ", strlen("AQ"), 0, 0);

  /* obtain TDO of message_type */
  OCITypeByName(envhp, errhp, svchp, (CONST text *)"AQ", strlen("AQ"),
                (CONST text *)"MESSAGE_TYPE", strlen("MESSAGE_TYPE"), 
                (text *)0, 0, OCI_DURATION_SESSION, OCI_TYPEGET_ALL, &mesg_tdo);

  /* prepare the message payload */
  mesg->subject = (OCIString *)0;
  mesg->data = (OCIString *)0;
  OCIStringAssignText(envhp, errhp, (CONST text *)"NORMAL MESSAGE",
                 strlen("NORMAL MESSAGE"), &mesg->subject);
  OCIStringAssignText(envhp, errhp,(CONST text *)"OCI ENQUEUE",
                 strlen("OCI ENQUEUE"), &mesg->data);
  nmesg->null_adt = nmesg->null_subject = nmesg->null_data = OCI_IND_NOTNULL;  

  /* enqueue into the msg_queue */
  OCIAQEnq(svchp, errhp, (CONST text *)"msg_queue", 0, 0,
                  mesg_tdo, (dvoid **)&mesg, (dvoid **)&nmesg, 0, 0);
  OCITransCommit(svchp, errhp, (ub4) 0);

  /* dequeue from the msg_queue */
  OCIAQDeq(svchp, errhp, (CONST text *)"msg_queue", 0, 0,
                   mesg_tdo, (dvoid **)&deqmesg, (dvoid **)&ndeqmesg, 0, 0);
  printf("Subject: %s\n", OCIStringPtr(envhp, deqmesg->subject));
  printf("Text: %s\n", OCIStringPtr(envhp, deqmesg->data));
  OCITransCommit(svchp, errhp, (ub4) 0);
}
Example 2

Enqueue and dequeue using correlation IDs.

struct message
{
  OCIString   *subject;
  OCIString   *data;
};
typedef struct message message;

struct null_message
{
  OCIInd    null_adt;
  OCIInd    null_subject;
  OCIInd    null_data;
};
typedef struct null_message null_message;

int main()
{
  OCIEnv *envhp;
  OCIServer *srvhp;
  OCIError *errhp;
  OCISvcCtx *svchp;
  dvoid     *tmp;
  OCIType *mesg_tdo = (OCIType *) 0;
  message  msg;
  null_message nmsg;
  message *mesg = &msg;
  null_message *nmesg = &nmsg;
  message *deqmesg = (message *)0;
  null_message *ndeqmesg = (null_message *)0;
  OCIRaw*firstmsg = (OCIRaw *)0;
  OCIAQMsgProperties *msgprop = (OCIAQMsgProperties *)0;
  OCIAQDeqOptions *deqopt = (OCIAQDeqOptions *)0;
  text correlation1[30], correlation2[30];
  
  OCIInitialize((ub4) OCI_OBJECT, (dvoid *)0,  (dvoid * (*)()) 0,
                (dvoid * (*)()) 0,  (void (*)()) 0 );
  OCIHandleAlloc( (dvoid *) NULL, (dvoid **) &envhp, (ub4) OCI_HTYPE_ENV,
                 52, (dvoid **) &tmp);
  
  OCIEnvInit( &envhp, (ub4) OCI_DEFAULT, 21, (dvoid **) &tmp  );
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, (ub4) OCI_HTYPE_ERROR,
                 52, (dvoid **) &tmp);
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4) OCI_HTYPE_SERVER,
                 52, (dvoid **) &tmp);
  
  OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4) OCI_HTYPE_SVCCTX,
                 52, (dvoid **) &tmp);
  OCIAttrSet( (dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX, (dvoid *)srvhp, (ub4) 0,
                 (ub4) OCI_ATTR_SERVER, (OCIError *) errhp);
 
  OCILogon(envhp, errhp, &svchp, "AQ", strlen("AQ"), "AQ", strlen("AQ"), 0, 0);

  /* allocate message properties descriptor */
  OCIDescriptorAlloc(envhp, (dvoid **)&msgprop, 
                   OCI_DTYPE_AQMSG_PROPERTIES, 0, (dvoid **)0);
  strcpy(correlation1, "1st message");
  OCIAttrSet(msgprop, OCI_DTYPE_AQMSG_PROPERTIES, (dvoid *)&correlation1, 
                   strlen(correlation1), OCI_ATTR_CORRELATION, errhp);

  /* obtain TDO of message_type */
  OCITypeByName(envhp, errhp, svchp, (CONST text *)"AQ", strlen("AQ"),
                (CONST text *)"MESSAGE_TYPE", strlen("MESSAGE_TYPE"), 
                (text *)0, 0, OCI_DURATION_SESSION, OCI_TYPEGET_ALL, &mesg_tdo);

  /* prepare the message payload */
  mesg->subject = (OCIString *)0;
  mesg->data = (OCIString *)0;
  OCIStringAssignText(envhp, errhp, (CONST text *)"NORMAL ENQUEUE1", 
                  strlen("NORMAL ENQUEUE1"), &mesg->subject);
  OCIStringAssignText(envhp, errhp,(CONST text *)"OCI ENQUEUE",
                  strlen("OCI ENQUEUE"), &mesg->data);
  nmesg->null_adt = nmesg->null_subject = nmesg->null_data = OCI_IND_NOTNULL;  

  /* enqueue into the msg_queue, store the message id into firstmsg */
  OCIAQEnq(svchp, errhp, (CONST text *)"msg_queue", 0, msgprop,
                   mesg_tdo, (dvoid **)&mesg, (dvoid **)&nmesg, &firstmsg, 0);

  /* enqueue into the msg_queue with a different correlation id */
  strcpy(correlation2, "2nd message");
  OCIAttrSet(msgprop, OCI_DTYPE_AQMSG_PROPERTIES, (dvoid*)&correlation2, 
                  strlen(correlation2), OCI_ATTR_CORRELATION, errhp);
  OCIStringAssignText(envhp, errhp, (CONST text *)"NORMAL ENQUEUE2", 
                  strlen("NORMAL ENQUEUE2"), &mesg->subject);
  OCIAQEnq(svchp, errhp, (CONST text *)"msg_queue", 0, msgprop,
                  mesg_tdo, (dvoid **)&mesg, (dvoid **)&nmesg, 0, 0);

  OCITransCommit(svchp, errhp, (ub4) 0);

  /* first dequeue by correlation id "2nd message" */
  /* allocate dequeue options descriptor and set the correlation option */
  OCIDescriptorAlloc(envhp, (dvoid **)&deqopt, 
                   OCI_DTYPE_AQDEQ_OPTIONS, 0, (dvoid **)0);
  OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS, (dvoid *)correlation2, 
strlen(correlation2), OCI_ATTR_CORRELATION, errhp); /* dequeue from the msg_queue */ OCIAQDeq(svchp, errhp, (CONST text *)"msg_queue", deqopt, 0, mesg_tdo, (dvoid **)&deqmesg, (dvoid **)&ndeqmesg, 0, 0); printf("Subject: %s\n", OCIStringPtr(envhp, deqmesg->subject)); printf("Text: %s\n", OCIStringPtr(envhp, deqmesg->data)); OCITransCommit(svchp, errhp, (ub4) 0); /* second dequeue by message id */ OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS, (dvoid *)&firstmsg, OCIRawSize(envhp, firstmsg), OCI_ATTR_DEQ_MSGID, errhp); /* clear correlation id option */ OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS, (dvoid *)correlation2, 0, OCI_ATTR_CORRELATION, errhp); /* dequeue from the msg_queue */ OCIAQDeq(svchp, errhp, (CONST text *)"msg_queue", deqopt, 0, mesg_tdo, (dvoid **)&deqmesg, (dvoid **)&ndeqmesg, 0, 0); printf("Subject: %s\n", OCIStringPtr(envhp, deqmesg->subject)); printf("Text: %s\n", OCIStringPtr(envhp, deqmesg->data)); OCITransCommit(svchp, errhp, (ub4) 0); }
Example 3

Enqueue and dequeue of a raw queue.

int main()
{
  OCIEnv *envhp;
  OCIServer *srvhp;
  OCIError *errhp;
  OCISvcCtx *svchp;
  dvoid     *tmp;
  OCIType *mesg_tdo = (OCIType *) 0;
  char  msg_text[100];
  OCIRaw  *mesg = (OCIRaw *)0;
  OCIRaw*deqmesg = (OCIRaw *)0;
  OCIInd   ind = 0;
  dvoid  *indptr = (dvoid *)&ind;
  inti;
  
  OCIInitialize((ub4) OCI_OBJECT, (dvoid *)0,  (dvoid * (*)()) 0,
               (dvoid * (*)()) 0,  (void (*)()) 0 );
  OCIHandleAlloc( (dvoid *) NULL, (dvoid **) &envhp, (ub4) OCI_HTYPE_ENV,
                  52, (dvoid **) &tmp);
  
  OCIEnvInit( &envhp, (ub4) OCI_DEFAULT, 21, (dvoid **) &tmp  );
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, (ub4) OCI_HTYPE_ERROR,
                  52, (dvoid **) &tmp);
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4) OCI_HTYPE_SERVER,
                  52, (dvoid **) &tmp);
  
  OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4) OCI_HTYPE_SVCCTX,
                  52, (dvoid **) &tmp);
  OCIAttrSet( (dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX, (dvoid *)srvhp, (ub4) 0,
                  (ub4) OCI_ATTR_SERVER, (OCIError *) errhp);
 
  OCILogon(envhp, errhp, &svchp, "AQ", strlen("AQ"), "AQ", strlen("AQ"), 0, 0);

  /* obtain the TDO of the RAW data type */
  OCITypeByName(envhp, errhp, svchp, (CONST text *)"SYS", strlen("SYS"),
                (CONST text *)"RAW", strlen("RAW"), 
                (text *)0, 0, OCI_DURATION_SESSION, OCI_TYPEGET_ALL, &mesg_tdo);

  /* prepare the message payload */
  strcpy(msg_text, "Enqueue to a RAW queue");
  OCIRawAssignBytes(envhp, errhp, msg_text, strlen(msg_text), &mesg);

  /* enqueue the message into raw_msg_queue */
  OCIAQEnq(svchp, errhp, (CONST text *)"raw_msg_queue", 0, 0,
                 mesg_tdo, (dvoid **)&mesg, (dvoid **)&indptr, 0, 0);
  OCITransCommit(svchp, errhp, (ub4) 0);

  /* dequeue the same message into C variable deqmesg */
  OCIAQDeq(svchp, errhp, (CONST text *)"raw_msg_queue", 0, 0, 
   mesg_tdo, (dvoid **)&deqmesg, (dvoid **)&indptr, 0, 0);
  for (i = 0; i < OCIRawSize(envhp, deqmesg); i++)
    printf("%c", *(OCIRawPtr(envhp, deqmesg) + i));
  OCITransCommit(svchp, errhp, (ub4) 0);
}
Example 4

Enqueue and dequeue using OCIAQAgent.

struct message
{
  OCIString   *subject;
  OCIString   *data;
};
typedef struct message message;

struct null_message
{
  OCIInd    null_adt;
  OCIInd    null_subject;
  OCIInd    null_data;
};
typedef struct null_message null_message;

int main()
{
  OCIEnv *envhp;
  OCIServer *srvhp;
  OCIError *errhp;
  OCISvcCtx *svchp;
  dvoid     *tmp;
  OCIType *mesg_tdo = (OCIType *) 0;
  message  msg;
  null_message nmsg;
  message *mesg = &msg;
  null_message *nmesg = &nmsg;
  message *deqmesg = (message *)0;
  null_message *ndeqmesg = (null_message *)0;
  OCIAQMsgProperties *msgprop = (OCIAQMsgProperties *)0;
  OCIAQAgent *agents[2];
  OCIAQDeqOptions *deqopt = (OCIAQDeqOptions *)0;
  ub4wait = OCI_DEQ_NO_WAIT;
  ub4 navigation = OCI_DEQ_FIRST_MSG;
  
  OCIInitialize((ub4) OCI_OBJECT, (dvoid *)0,  (dvoid * (*)()) 0,
                (dvoid * (*)()) 0,  (void (*)()) 0 );
  
  OCIHandleAlloc( (dvoid *) NULL, (dvoid **) &envhp, (ub4) OCI_HTYPE_ENV,
                52, (dvoid **) &tmp);
  
  OCIEnvInit( &envhp, (ub4) OCI_DEFAULT, 21, (dvoid **) &tmp  );
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, (ub4) OCI_HTYPE_ERROR,
                   52, (dvoid **) &tmp);
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4) OCI_HTYPE_SERVER,
                   52, (dvoid **) &tmp);
  
  OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4) OCI_HTYPE_SVCCTX,
                   52, (dvoid **) &tmp);
  
  OCIAttrSet( (dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX, (dvoid *)srvhp, (ub4) 0,
                   (ub4) OCI_ATTR_SERVER, (OCIError *) errhp);
 
  OCILogon(envhp, errhp, &svchp, "AQ", strlen("AQ"), "AQ", strlen("AQ"), 0, 0);

  /* obtain TDO of message_type */
  OCITypeByName(envhp, errhp, svchp, (CONST text *)"AQ", strlen("AQ"),
       (CONST text *)"MESSAGE_TYPE", strlen("MESSAGE_TYPE"), 
       (text *)0, 0, OCI_DURATION_SESSION, OCI_TYPEGET_ALL, &mesg_tdo);

  /* prepare the message payload */
  mesg->subject = (OCIString *)0;
  mesg->data = (OCIString *)0;
  OCIStringAssignText(envhp, errhp,
                    (CONST text *)"MESSAGE 1", strlen("MESSAGE 1"), 
                    &mesg->subject);
  OCIStringAssignText(envhp, errhp,
                    (CONST text *)"mesg for queue subscribers", 
                    strlen("mesg for queue subscribers"), &mesg->data);
  nmesg->null_adt = nmesg->null_subject = nmesg->null_data = OCI_IND_NOTNULL;  

  /* enqueue MESSAGE 1 for subscribers to the queue i.e. for RED and GREEN */
  OCIAQEnq(svchp, errhp, (CONST text *)"msg_queue_multiple", 0, 0,
                       mesg_tdo, (dvoid **)&mesg, (dvoid **)&nmesg, 0, 0);

  /* enqueue MESSAGE 2 for specified recipients i.e. for RED and BLUE */
  /* prepare message payload */
  OCIStringAssignText(envhp, errhp,
                    (CONST text *)"MESSAGE 2", strlen("MESSAGE 2"), 
                    &mesg->subject);
  OCIStringAssignText(envhp, errhp,
                    (CONST text *)"mesg for two recipients", 
                    strlen("mesg for two recipients"), &mesg->data);

  /* allocate AQ message properties and agent descriptors */
  OCIDescriptorAlloc(envhp, (dvoid **)&msgprop, 
                OCI_DTYPE_AQMSG_PROPERTIES, 0, (dvoid **)0);
  OCIDescriptorAlloc(envhp, (dvoid **)&agents[0], 
                  OCI_DTYPE_AQAGENT, 0, (dvoid **)0);
  OCIDescriptorAlloc(envhp, (dvoid **)&agents[1], 
                  OCI_DTYPE_AQAGENT, 0, (dvoid **)0);

  /* prepare the recipient list, RED and BLUE */
  OCIAttrSet(agents[0], OCI_DTYPE_AQAGENT, "RED", strlen("RED"),
                     OCI_ATTR_AGENT_NAME, errhp);
  OCIAttrSet(agents[1], OCI_DTYPE_AQAGENT, "BLUE", strlen("BLUE"),
                     OCI_ATTR_AGENT_NAME, errhp);
  OCIAttrSet(msgprop, OCI_DTYPE_AQMSG_PROPERTIES, (dvoid *)agents, 2,
                      OCI_ATTR_RECIPIENT_LIST, errhp);

  OCIAQEnq(svchp, errhp, (CONST text *)"msg_queue_multiple", 0, msgprop,
                       mesg_tdo, (dvoid **)&mesg, (dvoid **)&nmesg, 0, 0);
    OCITransCommit(svchp, errhp, (ub4) 0);

  /* now dequeue the messages using different consumer names */
  /* allocate dequeue options descriptor to set the dequeue options */
  OCIDescriptorAlloc(envhp, (dvoid **)&deqopt, OCI_DTYPE_AQDEQ_OPTIONS, 0, 
                     (dvoid **)0);

  /* set wait parameter to NO_WAIT so that the dequeue returns immediately */
  OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS, (dvoid *)&wait, 0, 
                     OCI_ATTR_WAIT, errhp);

  /* set navigation to FIRST_MESSAGE so that the dequeue resets the position */
  /* after a new consumer_name is set in the dequeue options     */
  OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS, (dvoid *)&navigation, 0, 
                     OCI_ATTR_NAVIGATION, errhp);
  
  /* dequeue from the msg_queue_multiple as consumer BLUE */
  OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS, (dvoid *)"BLUE", strlen("BLUE"), 
                     OCI_ATTR_CONSUMER_NAME, errhp);
  while (OCIAQDeq(svchp, errhp, (CONST text *)"msg_queue_multiple", deqopt, 0,
 mesg_tdo, (dvoid **)&deqmesg, (dvoid **)&ndeqmesg, 0, 0) 
 == OCI_SUCCESS)
  {
    printf("Subject: %s\n", OCIStringPtr(envhp, deqmesg->subject));
    printf("Text: %s\n", OCIStringPtr(envhp, deqmesg->data));
  }
  OCITransCommit(svchp, errhp, (ub4) 0);

  /* dequeue from the msg_queue_multiple as consumer RED */
  OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS, (dvoid *)"RED", strlen("RED"), 
                     OCI_ATTR_CONSUMER_NAME, errhp);
  while (OCIAQDeq(svchp, errhp, (CONST text *)"msg_queue_multiple", deqopt, 0,
                 mesg_tdo, (dvoid **)&deqmesg, (dvoid **)&ndeqmesg, 0, 0) 
 == OCI_SUCCESS)
  {
    printf("Subject: %s\n", OCIStringPtr(envhp, deqmesg->subject));
    printf("Text: %s\n", OCIStringPtr(envhp, deqmesg->data));
  }
  OCITransCommit(svchp, errhp, (ub4) 0);

  /* dequeue from the msg_queue_multiple as consumer GREEN */
  OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS,(dvoid *)"GREEN",strlen("GREEN"), 
                     OCI_ATTR_CONSUMER_NAME, errhp);
  while (OCIAQDeq(svchp, errhp, (CONST text *)"msg_queue_multiple", deqopt, 0,
                 mesg_tdo, (dvoid **)&deqmesg, (dvoid **)&ndeqmesg, 0, 0) 
 == OCI_SUCCESS)
  {
    printf("Subject: %s\n", OCIStringPtr(envhp, deqmesg->subject));
    printf("Text: %s\n", OCIStringPtr(envhp, deqmesg->data));
  }
  OCITransCommit(svchp, errhp, (ub4) 0);
}

Related Functions

OCIAQDeq(), OCIAQListen(), OCIInitialize()


OCIAQListen()

Purpose

Listens on one or more queues on behalf of a list of agents.

Syntax

sword OCIAQListen (OCISvcCtx      *svchp, 
                   OCIError       *errhp,
                   OCIAQAgent     **agent_list, 
                   ub4            num_agents,
                   sb4            wait, 
                   OCIAQAgent     **agent,
                   ub4            flags);

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.

agent_list (IN)

List of agents for which to monitor messages.

num_agents (IN)

Number of agents in the agent list.

wait (IN)

Time-out for the listen call.

agent (OUT)

Agent for which there is a message. OCIAgent is an OCI descriptor.

flags (IN)

Not currently used; pass as OCI_DEFAULT.

Comments

This is a blocking call that returns when there is a message ready for consumption for an agent in the list. If there are no messages found when the wait time expires, an error is returned.

Related Functions

OCIAQEnq(), OCIAQDeq(), OCISvcCtxToLda(), OCISubscriptionEnable(), OCISubscriptionPost(), OCISubscriptionRegister(),OCISubscriptionUnRegister()


OCISubscriptionDisable()

Purpose

Disables a subscription registration which turns off all notifications.

Syntax

ub4 OCISubscriptionDisable ( OCISubscription   *subscrhp,
                             OCIError          *errhp
                             ub4               mode );

Parameters

subscrhp (IN)

A subscription handle with the OCI_ATTR_SUBSCR_NAME and OCI_ATTR_SUBSCR_NAMESPACE attributes set. For information, see Subscription Handle Attributes .

errhp (OUT)

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

mode (IN)

Call-specific mode. Valid values:

Comments

This call is used to temporarily turn off notifications. This is useful when the application is running a critical section of the code and should not be interrupted.

The user need not be connected or authenticated to perform this operation. A registration must have been performed to the subscription specified by the subscription handle before this call is made.

All notifications subsequent to an OCISubscriptionDisable() are discarded by the system until an OCISubscriptionEnable() is performed.

Related Functions

OCIAQListen(), OCISubscriptionEnable(), OCISubscriptionPost(), OCISubscriptionRegister(), OCISubscriptionUnRegister()


OCISubscriptionEnable()

Purpose

Enables a subscription registration that has been disabled. This turns on all notifications.

Syntax

ub4 OCISubscriptionEnable ( OCISubscription   *subscrhp,
                            OCIError          *errhp
                            ub4               mode );

Parameters

subscrhp (IN)

A subscription handle with the OCI_ATTR_SUBSCR_NAME and OCI_ATTR_SUBSCR_NAMESPACE attributes set. For information, see Subscription Handle Attributes .

errhp (OUT)

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

mode (IN)

Call-specific mode. Valid value:

Comments

This call is used to turn on notifications after a subscription registration has been disabled.

The user need not be connected or authenticated to perform this operation. A registration must have been done for the specified subscription before this call is made.

Related Functions

OCIAQListen(), OCISvcCtxToLda(), OCISubscriptionPost(), OCISubscriptionRegister(), OCISubscriptionUnRegister()


OCISubscriptionPost()

Purpose

Posts to a subscription which allows all clients who are registered for the subscription to get notifications.

Syntax

ub4 OCISubscriptionPost ( OCISvcCtx         *svchp,
                          OCISubscription   **subscrhpp,
                          ub2               count,
                          OCIError          *errhp
                          ub4               mode );

Parameters

svchp (IN)

A V8 OCI service context. This service context should have a valid authenticated user handle.

subscrhpp (IN)

An array of subscription handles. Each element of this array should be a subscription handle with the OCI_ATTR_SUBSCR_NAME and OCI_ATTR_SUBSCR_NAMESPACE attributes set. For information, see Subscription Handle Attributes .

The OCI_ATTR_SUBSCR_PAYLOAD attribute has to be set for each subscription handle prior to this call. If it is not set, the payload is assumed to be NULL and no payload is delivered when the notification is received by the clients that have registered interest. Note that the caller will have to preserve the payload until the post is done as the OCIAttrSet() call keeps track of the reference to the payload but does not copy the contents.

count (IN)

The number of elements in the subscription handle array.

errhp (OUT)

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

mode (IN)

Call-specific mode. Valid value:

Comments

Posting to a subscription involves identifying the subscription name and the payload if desired. If no payload is associated, the payload length can be set to 0.

This call provides a best-effort guarantee. A notification does to registered clients at most once.

This call is primarily used for light-weight notification and is useful in the case of several system events. If the application needs more rigid guarantees, it can use the Advanced Queuing functionality by enqueuing to queue.

Related Functions

OCIAQListen(), OCISvcCtxToLda(), OCISubscriptionEnable(), OCISubscriptionRegister(), OCISubscriptionUnRegister()


OCISubscriptionRegister()

Purpose

Registers a callback for message notification.

Syntax

ub4 OCISubscriptionRegister ( OCISvcCtx         *svchp,
                              OCISubscription   **subscrhpp,
                              ub2               count,
                              OCIError          *errhp
                              ub4               mode );

Parameters

svchp (IN)

A V8 OCI service context. This service context should have a valid authenticated user handle.

subscrhpp (IN)

An array of subscription handles. Each element of this array should be a subscription handle with the OCI_ATTR_SUBSCR_NAME, OCI_ATTR_SUBSCR_NAMESPACE, OCI_ATTR_SUBSCR_CBACK, and OCI_ATTR_SUBSCR_CTX attributes set; otherwise, an error will be returned. For information, see Subscription Handle Attributes .

When a notification is received for the registration denoted by the subscrhpp[i], the user defined callback function (OCI_ATTR_SUBSCR_CBACK) set for subscrhpp[i] will get invoked with the context (OCI_ATTR_SUBSCR_CTX) set for subscrhpp[i].

count (IN)

The number of elements in the subscription handle array.

errhp (OUT)

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

mode (IN)

Call-specific mode. Valid values:

Whenever a new client process comes up, or an old one goes down and comes back up, it needs to register for all subscriptions of interest. If the client stays up and the server first goes down and then comes back up, the client will continue to receive notifications for registrations that are DISCONNECTED. However, the client will not receive notifications for CONNECTED registrations as they will be lost once the server goes down and comes back up.

Comments

This call is invoked for registration to a subscription which identifies the subscription name of interest and the associated callback to be invoked. Interest in several subscriptions can be registered at one time.

This interface is only valid for the asynchronous mode of message delivery. In this mode, a subscriber issues a registration call which specifies a callback. When messages are received that match the subscription criteria, the callback is invoked. The callback may then issue an explicit message_receive (dequeue) to retrieve the message.

The user must specify a subscription handle at registration time with the namespace attribute set to OCI_SUBSCR_NAMESPACE_AQ.

The subscription name is the string 'SCHEMA.QUEUE' if the registration is for a single-consumer queue and 'SCHEMA.QUEUE:CONSUMER' if the registration is for a multi-consumer queue. Specifying the SCHEMA in the subscription string is optional. If SCHEMA is not specified, the queue is assumed to be in the login user's schema. The user needs DEQUEUE privileges on the queue to register for subscriptions.

Each namespace will have its own privilege model. If the user performing the register is not entitled to register in the namespace for the specified subscription, an error is returned.

Related Functions

OCIAQListen(), OCISvcCtxToLda(), OCISubscriptionEnable(), OCISubscriptionPost(), OCISubscriptionUnRegister()


OCISubscriptionUnRegister()

Purpose

Unregisters a subscription which turns off notifications.

Syntax

ub4 OCISubscriptionUnRegister ( OCISvcCtx         *svchp,
                                OCISubscription   *subscrhp,
                                OCIError          *errhp
                                ub4               mode );

Parameters

svchp (IN)

A V8 OCI service context. This service context should have a valid authenticated user handle.

subscrhp (IN)

A subscription handle with the OCI_ATTR_SUBSCR_NAME and OCI_ATTR_SUBSCR_NAMESPACE attributes set. For information, see Subscription Handle Attributes .

errhp (OUT)

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

mode (IN)

Call-specific mode. Valid value:

Comments

Unregistering to a subscription is going to ensure that the user will not receive notifications regarding the specified subscription in future. If the user wishes to resume notification, then the only option is to re-register to the subscription.

All notifications that would otherwise have been delivered are not delivered after a subsequent register is performed because the user is no longer in the list of interested clients.

Related Functions

OCIAQListen(), OCISvcCtxToLda(), OCISubscriptionEnable(), OCISubscriptionPost(), OCISubscriptionRegister()

Handle and Descriptor Functions

This section describes the OCI handle and descriptor functions.

Table 15-2 OCI Quick Reference
Function  Purpose 

OCIAttrGet()  

Get the attributes of a handle  

OCIAttrSet()  

Set an attribute of a handle or descriptor  

OCIDescriptorAlloc()  

Allocate and initialize a descriptor or LOB locator  

OCIDescriptorFree()  

Free a previously allocated descriptor  

OCIHandleAlloc()  

Allocate and initialize a handle  

OCIHandleFree()  

Free a previously allocated handle  

OCIParamGet()  

Get a parameter descriptor  

OCIParamSet()  

Set parameter descriptor in COR handle  


OCIAttrGet()

Purpose

This call is used to get a particular attribute of a handle.

Syntax

sword OCIAttrGet ( CONST dvoid    *trgthndlp,
                   ub4            trghndltyp,
                   dvoid          *attributep,
                   ub4            *sizep,
                   ub4            attrtype,
                   OCIError       *errhp );

Parameters

trgthndlp (IN)

Pointer to a handle type.

trghndltyp (IN)

The handle type.

attributep (OUT)

Pointer to the storage for an attribute value. The attribute value is filled in.

sizep (OUT)

The size of storage for the attribute value. This can be passed in as NULL for parameters whose size is well known. For text* parameters, a pointer to a ub4 must be passed in to get the length of the string.

attrtype (IN)

The type of attribute being retrieved.

errhp (IN/OUT)

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

Comments

This call is used to get a particular attribute of a handle. See Appendix A, "Handle and Descriptor Attributes", for a list of handle types and their readable attributes.

Related Functions

OCIAttrSet()


OCIAttrSet()

Purpose

This call is used to set a particular attribute of a handle or a descriptor.

Syntax

sword OCIAttrSet ( dvoid       *trgthndlp,
                   ub4         trghndltyp,
                   dvoid       *attributep,
                   ub4         size,
                   ub4         attrtype,
                   OCIError    *errhp );

Parameters

trgthndlp (IN/OUT)

Pointer to a handle type whose attribute gets modified.

trghndltyp (IN/OUT)

The handle type.

attributep (IN)

Pointer to an attribute value. The attribute value is copied into the target handle. If the attribute value is a pointer, then only the pointer is copied, not the contents of the pointer.

size (IN)

The size of an attribute value. This can be passed in as 0 for most attributes as the size is already known by the OCI library. For text* attributes, a ub4 must be passed in set to the length of the string.

attrtype (IN)

The type of attribute being set.

errhp (IN/OUT)

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

Comments

See Appendix A, "Handle and Descriptor Attributes", for a list of handle types and their writable attributes.

Example

The following code sample demonstrates OCIAttrSet() being used several times near the beginning of an application.

int main()
{
OCIEnv *envhp;
OCIServer *srvhp;
OCIError *errhp;
OCISvcCtx *svchp;
OCIStmt *stmthp;
OCISession *usrhp; OCIInitialize((ub4) OCI_THREADED | OCI_OBJECT, (dvoid *)0,
(dvoid * (*)()) 0,(dvoid * (*)()) 0, (void (*)()) 0 ); OCIHandleAlloc( (dvoid *) NULL, (dvoid **) &envhp, (ub4) OCI_HTYPE_ENV,
0, (dvoid **) &tmp); OCIEnvInit( &envhp, (ub4) OCI_DEFAULT, 0, (dvoid **) &tmp ); OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, (ub4)
OCI_HTYPE_ERROR, 0, (dvoid **) &tmp); OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4)
OCI_HTYPE_SERVER, 0, (dvoid **) &tmp); OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT); OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp,
(ub4) OCI_HTYPE_SVCCTX, , (dvoid **) &tmp); /* set attribute server context in the service context */ OCIAttrSet( (dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX, (dvoid *) srvhp,
(ub4) 0, (ub4) OCI_ATTR_SERVER, (OCIError *) errhp); /* allocate a user session handle */ OCIHandleAlloc((dvoid *)envhp, (dvoid **)&usrhp,
(ub4) OCI_HTYPE_SESSION, (size_t) 0, (dvoid **) 0); OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"sherry",
(ub4)strlen("sherry"), OCI_ATTR_USERNAME, errhp); OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"penfield",
(ub4)strlen("penfield"), OCI_ATTR_PASSWORD, errhp); checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
OCI_DEFAULT)); OCIAttrSet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX, (dvoid *)usrhp,
(ub4)0, OCI_ATTR_SESSION, errhp);

Related Functions

OCIAttrGet()


OCIDescriptorAlloc()

Purpose

Allocates storage to hold descriptors or LOB locators.

Syntax

sword OCIDescriptorAlloc ( CONST dvoid   *parenth,
                           dvoid         **descpp, 
                           ub4           type,
                           size_t        xtramem_sz,
                           dvoid         **usrmempp);

Parameters

parenth (IN)

An environment handle.

descpp (OUT)

Returns a descriptor or LOB locator of desired type.

type (IN)

Specifies the type of descriptor or LOB locator to be allocated:

xtramem_sz (IN)

Specifies an amount of user memory to be allocated for use by the application for the lifetime of the descriptor.

usrmempp (OUT)

Returns a pointer to the user memory of size xtramem_sz allocated by the call for the user for the lifetime of the descriptor.

Comments

Returns a pointer to an allocated and initialized descriptor, corresponding to the type specified in type. A non-NULL descriptor or LOB locator is returned on success. No diagnostics are available on error.

This call returns OCI_SUCCESS if successful, or OCI_INVALID_HANDLE if an out-of-memory error occurs.

For more information about the xtramem_sz parameter and user memory allocation, refer to "User Memory Allocation".

Related Functions

OCIDescriptorFree()


OCIDescriptorFree()

Purpose

Deallocates a previously allocated descriptor.

Syntax

sword OCIDescriptorFree ( dvoid    *descp,
                          ub4      type );

Parameters

descp (IN)

An allocated descriptor.

type (IN)

Specifies the type of storage to be freed. The specific types are:

Comments

This call frees storage associated with a descriptor. Returns OCI_SUCCESS or OCI_INVALID_HANDLE. All descriptors may be explicitly deallocated, however the OCI will deallocate a descriptor if the environment handle is deallocated.

Related Functions

OCIDescriptorAlloc()


OCIHandleAlloc()

Purpose

This call returns a pointer to an allocated and initialized handle.

Syntax

sword OCIHandleAlloc ( CONST dvoid   *parenth,
                       dvoid         **hndlpp, 
                       ub4           type, 
                       size_t        xtramem_sz,
                       dvoid         **usrmempp );

Parameters

parenth (IN)

An environment handle.

hndlpp (OUT)

Returns a handle.

type (IN)

Specifies the type of handle to be allocated. The allowed types are:

xtramem_sz (IN)

Specifies an amount of user memory to be allocated.

usrmempp (OUT)

Returns a pointer to the user memory of size xtramem_sz allocated by the call for the user.

Comments

Returns a pointer to an allocated and initialized handle, corresponding to the type specified in type. A non-NULL handle is returned on success. All handles are allocated with respect to an environment handle which is passed in as a parent handle.

No diagnostics are available on error. This call returns OCI_SUCCESS if successful, or OCI_INVALID_HANDLE if an error occurs.

Handles must be allocated using OCIHandleAlloc() before they can be passed into an OCI call.

To allocate and initialize an environment handle, call OCIEnvInit().

See Also: For more information about using the xtramem_sz parameter for user memory allocation, refer to "User Memory Allocation".

Example

The following sample code shows OCIHandleAlloc() being used to allocate a variety of handles at the beginning of an application:

OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, (ub4) 
OCI_HTYPE_ERROR, 0, (dvoid **) &tmp); OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4)
OCI_HTYPE_SERVER, 0, (dvoid **) &tmp); OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4)
OCI_HTYPE_SVCCTX, 0, (dvoid **) &tmp);

Related Functions

OCIHandleFree(), OCIEnvInit()


OCIHandleFree()

Purpose

This call explicitly deallocates a handle.

Syntax

sword OCIHandleFree ( dvoid     *hndlp,
                      ub4       type );

Parameters

hndlp (IN)

A handle allocated by OCIHandleAlloc().

type (IN)

Specifies the type of storage to be freed. The specific types are:

Comments

This call frees up storage associated with a handle, corresponding to the type specified in the type parameter.

This call returns either OCI_SUCCESS or OCI_INVALID_HANDLE.

All handles may be explicitly deallocated. The OCI will deallocate a child handle if the parent is deallocated.

Related Functions

OCIHandleAlloc(), OCIEnvInit()


OCIParamGet()

Purpose

Returns a descriptor of a parameter specified by position in the describe handle or statement handle.

Syntax

sword OCIParamGet ( CONST dvoid       *hndlp,
                    ub4               htype,
                    OCIError          *errhp,
                    dvoid             **parmdpp,
                    ub4               pos );

Parameters

hndlp (IN)

A statement handle or describe handle. The OCIParamGet() function will return a parameter descriptor for this handle.

htype (IN)

the type of the handle passed in the handle parameter. Valid types are

errhp (IN/OUT)

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

parmdpp (OUT)

A descriptor of the parameter at the position given in the pos parameter.

pos (IN)

Position number in the statement handle or describe handle. A parameter descriptor will be returned for this position.

Note: OCI_NO_DATA may be returned if there are no parameter descriptors for this position.

Comments

This call returns a descriptor of a parameter specified by position in the describe handle or statement handle. Parameter descriptors are always allocated internally by the OCI library. They are read-only.

OCI_NO_DATA may be returned if there are no parameter descriptors for this position.

See Appendix A, "Handle and Descriptor Attributes", for more detailed information about parameter descriptor attributes.

Related Functions

OCIAttrGet(), OCIAttrSet(), OCIParamSet()


OCIParamSet()

Purpose

Used to set a complex object retrieval (COR) descriptor into a COR handle.

Syntax

sword OCIParamSet ( dvoid          *hndlp,
                    ub4            htype,
                    OCIError       *errhp,
                    CONST dvoid    *dscp,
                    ub4            dtyp,
                    ub4            pos );

Parameters

hndlp (IN/OUT)

Handle pointer.

htype (IN)

Handle type.

errhp (IN/OUT)

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

dscp (IN)

Complex object retrieval descriptor pointer.

dtyp (IN)

Descriptor type. The descriptor type for a COR descriptor is OCI_DTYPE_COMPLEXOBJECTCOMP.

pos (IN)

Position number.

Comments

The COR handle must have been previously allocated using OCIHandleAlloc(), and the descriptor must have been previously allocated using OCIDescriptorAlloc(). Attributes of the descriptor are set using OCIAttrSet().

For more information about complex object retrieval, see "Complex Object Retrieval".

Related Functions

OCIParamGet()

Bind, Define, and Describe Functions

This section describes the bind, define, and describe functions.

Table 15-3 OCI Quick Reference
Function  Purpose 

OCIBindArrayOfStruct()  

Set skip parameters for static array bind  

OCIBindByName()  

Bind by name  

OCIBindByPos()  

Bind by position  

OCIBindDynamic()  

Sets additional attributes after bind with OCI_DATA_AT_EXEC mode  

OCIBindObject()  

Set additional attributes for bind of named data type  

OCIDefineArrayOfStruct()  

Set additional attributes for static array define  

OCIDefineByPos()  

Define an output variable association  

OCIDefineDynamic()  

Sets additional attributes for define in OCI_DYNAMIC_FETCH mode  

OCIDefineObject()  

Set additional attributes for define of named data type  

OCIDescribeAny()  

Describe existing schema objects  

OCIStmtGetBindInfo()  

Get bind and indicator variable names and handle  


OCIBindArrayOfStruct()

Purpose

This call sets up the skip parameters for a static array bind.

Syntax

sword OCIBindArrayOfStruct ( OCIBind     *bindp,
                             OCIError    *errhp,
                             ub4         pvskip, 
                             ub4         indskip, 
                             ub4         alskip, 
                             ub4         rcskip );

Parameters

bindp (IN/OUT)

The handle to a bind structure.

errhp (IN/OUT)

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

pvskip (IN)

Skip parameter for the next data value.

indskip (IN)

Skip parameter for the next indicator value or structure.

alskip (IN)

Skip parameter for the next actual length value.

rcskip (IN)

Skip parameter for the next column-level return code value.

Comments

This call sets up the skip parameters necessary for a static array bind. It follows a call to OCIBindByName() or OCIBindByPos(). The bind handle returned by that initial bind call is used as a parameter for the OCIBindArrayOfStruct() call. For information about skip parameters, see the section "Arrays of Structures".

Related Functions

OCIBindByName(), OCIBindByPos()


OCIBindByName()

Purpose

Creates an association between a program variable and a placeholder in a SQL statement or PL/SQL block.

Syntax

sword OCIBindByName ( OCIStmt       *stmtp, 
                      OCIBind       **bindpp,
                      OCIError      *errhp,
                      CONST text    *placeholder,
                      sb4           placeh_len,
                      dvoid         *valuep,
                      sb4           value_sz,
                      ub2           dty,
                      dvoid         *indp,
                      ub2           *alenp,
                      ub2           *rcodep,
                      ub4           maxarr_len,
                      ub4           *curelep, 
                      ub4           mode ); 

Parameters

stmtp (IN/OUT)

The statement handle to the SQL or PL/SQL statement being processed.

bindpp (IN/OUT)

An address of a bind handle which is implicitly allocated by this call. The bind handle maintains all the bind information for this particular input value. The handle is freed implicitly when the statement handle is deallocated. On input, the value of the pointer must be NULL or a valid bind handle.

errhp (IN/OUT)

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

placeholder (IN)

The placeholder attributes are specified by name if OCIBindByName() is being called.

placeh_len (IN)

The length of the placeholder name specified in placeholder.

valuep (IN/OUT)

An address of a data value or an array of data values of the type specified in the dty parameter. An array of data values can be specified for mapping into a PL/SQL table or for providing data for SQL multiple-row operations. When an array of bind values is provided, this is called an array bind in OCI terms.

For SQLT_NTY or SQLT_REF binds, the valuep parameter is ignored. The pointers to OUT buffers are set in the pgvpp parameter initialized by OCIBindObject().

If the OCI_ATTR_CHARSET_ID is attribute is set to OCI_UCS2ID (Unicode), all data passed to and received with the corresponding bind call is assumed to be in UCS-2 encoding. For more information, refer to OCI_ATTR_CHARSET_ID.

value_sz (IN)

The size of a data value. In the case of an array bind, this is the maximum size of any element possible with the actual sizes being specified in the alenp parameter.

For descriptors, locators, or REFs, whose size is unknown to client applications use the size of the structure you are passing in; e.g., sizeof (OCILobLocator *).

dty (IN)

The data type of the value(s) being bound. Named data types (SQLT_NTY) and REFs (SQLT_REF) are valid only if the application has been initialized in object mode. For named data types, or REFs, additional calls must be made with the bind handle to set up the datatype-specific attributes.

indp (IN/OUT)

Pointer to an indicator variable or array. For all data types except SQLT_NTY, this is a pointer to sb2 or an array of sb2s.

For SQLT_NTY, this pointer is ignored and the actual pointer to the indicator structure or an array of indicator structures is initialized in a subsequent call to OCIBindObject(). This parameter is ignored for dynamic binds.

See the section "Indicator Variables" for more information about indicator variables.

alenp (IN/OUT)

Pointer to array of actual lengths of array elements. Each element in alenp is the length of the data in the corresponding element in the bind value array before and after the execute. This parameter is ignored for dynamic binds.

rcodep (OUT)

Pointer to array of column level return codes. This parameter is ignored for dynamic binds.

maxarr_len (IN)

The maximum possible number of elements of type dty in a PL/SQL binds. This parameter is not required for non-PL/SQL binds. If maxarr_len is non-zero, then either OCIBindDynamic() or OCIBindArrayOfStruct() can be invoked to set up additional bind attributes.

curelep (IN/OUT)

A pointer to the actual number of elements. This parameter is only required for
PL/SQL binds.

mode (IN)

The valid modes for this parameter are:

OCI_DEFAULT - This is default mode.

OCI_DATA_AT_EXEC - When this mode is selected, the value_sz parameter defines the maximum size of the data that can be ever provided at runtime. The application must be ready to provide the OCI library runtime IN data buffers at any time and any number of times. Runtime data is provided in one of the two ways:

  • callbacks using a user-defined function which must be registered with a subsequent call to OCIBindDynamic().

  • a polling mechanism using calls supplied by the OCI. This mode is assumed if no callbacks are defined.

For more information about using the OCI_DATA_AT_EXEC mode, see the section "Run Time Data Allocation and Piecewise Operations".

When the allocated buffers are not required any more, they should be freed by the client.

Comments

This call is used to perform a basic bind operation. The bind creates an association between the address of a program variable and a placeholder in a SQL statement or PL/SQL block. The bind call also specifies the type of data which is being bound, and may also indicate the method by which data will be provided at runtime.

This function also implicitly allocates the bind handle indicated by the bindpp parameter. If a non-NULL pointer is passed in **bindpp, the OCI assumes that this points to a valid handle that has been previously allocated with a call to OCIHandleAlloc() or OCIBindByName().

Data in an OCI application can be bound to placeholders statically or dynamically. Binding is static when all the IN bind data and the OUT bind buffers are well-defined just before the execute. Binding is dynamic when the IN bind data and the OUT bind buffers are provided by the application on demand at execute time to the client library. Dynamic binding is indicated by setting the mode parameter of this call to OCI_DATA_AT_EXEC.

See Also: For more information about dynamic binding, see the section "Run Time Data Allocation and Piecewise Operations".

Both OCIBindByName() and OCIBindByPos() take as a parameter a bind handle, which is implicitly allocated by the bind call A separate bind handle is allocated for each placeholder the application is binding.

Additional bind calls may be required to specify particular attributes necessary when binding certain data types or handling input data in certain ways:

Related Functions

OCIBindDynamic(), OCIBindObject(), OCIBindArrayOfStruct()


OCIBindByPos()

Purpose

Creates an association between a program variable and a placeholder in a SQL statement or PL/SQL block.

Syntax

sword OCIBindByPos ( OCIStmt      *stmtp, 
                     OCIBind      **bindpp,
                     OCIError     *errhp,
                     ub4          position,
                     dvoid        *valuep,
                     sb4          value_sz,
                     ub2          dty,
                     dvoid        *indp,
                     ub2          *alenp,
                     ub2          *rcodep,
                     ub4          maxarr_len,
                     ub4          *curelep, 
                     ub4          mode );

Parameters

stmtp (IN/OUT)

The statement handle to the SQL or PL/SQL statement being processed.

bindpp (IN/OUT)

An address of a bind handle which is implicitly allocated by this call. The bind handle maintains all the bind information for this particular input value. The handle is freed implicitly when the statement handle is deallocated. On input, the value of the pointer must be NULL or a valid bind handle.

errhp (IN/OUT)

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

position (IN)

The placeholder attributes are specified by position if OCIBindByPos() is being called.

valuep (IN/OUT)

An address of a data value or an array of data values of the type specified in the dty parameter. An array of data values can be specified for mapping into a PL/SQL table or for providing data for SQL multiple-row operations. When an array of bind values is provided, this is called an array bind in OCI terms.

For SQLT_NTY or SQLT_REF binds, the valuep parameter is ignored. The pointers to OUT buffers are set in the pgvpp parameter initialized by OCIBindObject().

If the OCI_ATTR_CHARSET_ID is attribute is set to OCI_UCS2ID (Unicode), all data passed to and received with the corresponding bind call is assumed to be in UCS-2 encoding. For more information, refer to OCI_ATTR_CHARSET_ID.

value_sz (IN)

The size of a data value. In the case of an array bind, this is the maximum size of any element possible with the actual sizes being specified in the alenp parameter.

For descriptors, locators, or REFs, whose size is unknown to client applications use the size of the structure you are passing in; e.g., sizeof (OCILobLocator *).

dty (IN)

The data type of the value(s) being bound. Named data types (SQLT_NTY) and REFs (SQLT_REF) are valid only if the application has been initialized in object mode. For named data types, or REFs, additional calls must be made with the bind handle to set up the datatype-specific attributes.

indp (IN/OUT)

Pointer to an indicator variable or array. For all data types, this is a pointer to sb2 or an array of sb2s. The only exception is SQLT_NTY, when this pointer is ignored and the actual pointer to the indicator structure or an array of indicator structures is initialized by OCIBindObject(). Ignored for dynamic binds.

See the section "Indicator Variables" for more information about indicator variables.

alenp (IN/OUT)

Pointer to array of actual lengths of array elements. Each element in alenp is the length of the data in the corresponding element in the bind value array before and after the execute. This parameter is ignored for dynamic binds.

rcodep (OUT)

Pointer to array of column level return codes. This parameter is ignored for dynamic binds.

maxarr_len (IN)

The maximum possible number of elements of type dty in a PL/SQL binds. This parameter is not required for non-PL/SQL binds. If maxarr_len is non-zero, then either OCIBindDynamic() or OCIBindArrayOfStruct() can be invoked to set up additional bind attributes.

curelep (IN/OUT)

A pointer to the actual number of elements. This parameter is only required for PL/SQL binds.

mode (IN)

The valid modes for this parameter are:

OCI_DEFAULT - This is default mode.

OCI_DATA_AT_EXEC - When this mode is selected, the value_sz parameter defines the maximum size of the data that can be ever provided at runtime. The application must be ready to provide the OCI library runtime IN data buffers at any time and any number of times. Runtime data is provided in one of the two ways:

  • callbacks using a user-defined function which must be registered with a subsequent call to OCIBindDynamic().

  • a polling mechanism using calls supplied by the OCI. This mode is assumed if no callbacks are define.

For more information about using the OCI_DATA_AT_EXEC mode, see the section "Run Time Data Allocation and Piecewise Operations".

When the allocated buffers are not required any more, they should be freed by the client.

Comments

This call is used to perform a basic bind operation. The bind creates an association between the address of a program variable and a placeholder in a SQL statement or PL/SQL block. The bind call also specifies the type of data which is being bound, and may also indicate the method by which data will be provided at runtime.

This function also implicitly allocates the bind handle indicated by the bindpp parameter. If a non-NULL pointer is passed in **bindpp, the OCI assumes that this points to a valid handle that has been previously allocated with a call to OCIHandleAlloc() or OCIBindByPos().

Data in an OCI application can be bound to placeholders statically or dynamically. Binding is static when all the IN bind data and the OUT bind buffers are well-defined just before the execute. Binding is dynamic when the IN bind data and the OUT bind buffers are provided by the application on demand at execute time to the client library. Dynamic binding is indicated by setting the mode parameter of this call to OCI_DATA_AT_EXEC.

See Also: For more information about dynamic binding, see the section "Run Time Data Allocation and Piecewise Operations".

Both OCIBindByName() and OCIBindByPos() take as a parameter a bind handle, which is implicitly allocated by the bind call A separate bind handle is allocated for each placeholder the application is binding.

Additional bind calls may be required to specify particular attributes necessary when binding certain data types or handling input data in certain ways:

Related Functions

OCIBindDynamic(), OCIBindObject(), OCIBindArrayOfStruct()


OCIBindDynamic()

Purpose

This call is used to register user callbacks for dynamic data allocation.

Syntax

sword OCIBindDynamic ( OCIBind     *bindp,
                       OCIError    *errhp,
                       dvoid       *ictxp, 
                       OCICallbackInBind         (icbfp)(/*_
                                dvoid            *ictxp,
                                OCIBind          *bindp,
                                ub4              iter, 
                                ub4              index, 
                                dvoid            **bufpp,
                                ub4              *alenp,
                                ub1              *piecep, 
                                dvoid            **indpp */),
                       dvoid       *octxp,
                       OCICallbackOutBind        (ocbfp)(/*_
                                dvoid            *octxp,
                                OCIBind          *bindp,
                                ub4              iter, 
                                ub4              index, 
                                dvoid            **bufpp, 
                                ub4              **alenpp,
                                ub1              *piecep,
                                dvoid            **indpp, 
                                ub2              **rcodepp _*/)   );

Parameters

bindp (IN/OUT)

A bind handle returned by a call to OCIBindByName() or OCIBindByPos().

errhp (IN/OUT)

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

ictxp (IN)

The context pointer required by the call back function icbfp.

icbfp (IN)

The callback function which returns a pointer to the IN bind value or piece at run time. The callback takes in the following parameters:

ictxp (IN/OUT)

The context pointer for this callback function.

bindp (IN)

The bind handle passed in to uniquely identify this bind variable.

iter (IN)

0-based execute iteration value.

index (IN)

Index of the current array, for an array bind in PL/SQL. For SQL it is the row index. The value is 0-based and not greater than curelep parameter of the bind call.

bufpp (OUT)

The pointer to the buffer or storage. For descriptors, *bufpp contains a pointer to the descriptor. For example if you define

OCILOBLocator        *lobp;

then you would set *bufpp to lobp not *lobp.

For REFs, pass the address of the ref; i.e., pass &my_ref for *bufpp.

If the OCI_ATTR_CHARSET_ID is attribute is set to OCI_UCS2ID (Unicode), all data passed to and received with the corresponding bind call is assumed to be in UCS-2 encoding. For more information, refer to OCI_ATTR_CHARSET_ID.

alenp (OUT)

A pointer to a storage for OCI to fill in the size of the bind
value/piece after it has been read. For descriptors, pass the size of the pointer to the descriptor; e.g., sizeof(OCILobLocator *).

piecep (OUT)

Which piece of the bind value. This can be one of the following values OCI_ONE_PIECE, OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE. For datatypes that do not support piecewise operations, you must pass OCI_ONE_PIECE or an error will be generated.

indp (OUT)

Contains the indicator value. This is a pointer to either an sb2 value or a pointer to an indicator structure for binding named data types.

octxp (IN)

The context pointer required by the callback function ocbfp.

ocbfp (IN)

The callback function which returns a pointer to the OUT bind value or piece at run time. The callback takes in the following parameters:

octxp (IN/OUT)

The context pointer for this call back function.

bindp (IN)

The bind handle passed in to uniquely identify this bind variable.

iter (IN)

0-based execute iteration value.

index (IN)

For PL/SQL index of the current array, for an array bind. For SQL, the index is the row number in the current iteration. It is 0-based, and must not be greater than curelep parameter of the bind call.

bufpp (OUT)

A pointer to a buffer to write the bind value/piece.

If the OCI_ATTR_CHARSET_ID is attribute is set to OCI_UCS2ID (Unicode), all data passed to and received with the corresponding bind call is assumed to be in UCS-2 encoding. For more information, refer to OCI_ATTR_CHARSET_ID.

alenpp (IN/OUT)

A pointer to a storage for OCI to fill in the size of the bind value/piece after it has been read.

piecep (IN/OUT)

Returns a piece value from the callback (application) to Oracle, as follows:

  • IN - The value can be OCI_ONE_PIECE or OCI_NEXT_PIECE.

  • OUT - Depends on the IN value:

    If IN value is OCI_ONE_PIECE, then OUT value can be OCI_ONE_PIECE or OCI_FIRST_PIECE

    If IN value is OCI_NEXT_PIECE then OUT value can be OCI_NEXT_PIECE or OCI_LAST_PIECE

indpp (OUT)

Returns a pointer to contain the indicator value which either an sb2 value or a pointer to an indicator structure for named data types.

rcodepp (OUT)

Returns a pointer to contains the return code.

Comments

This call is used to register user-defined callback functions for providing or receiving data if OCI_DATA_AT_EXEC mode was specified in a previous call to OCIBindByName() or OCIBindByPos().

The callback function pointers must return OCI_CONTINUE if it the call is successful. Any return code other than OCI_CONTINUE signals that the client wishes to abort processing immediately.

For more information about the OCI_DATA_AT_EXEC mode, see the section "Run Time Data Allocation and Piecewise Operations".

When passing the address of a storage area, make sure that the storage area will exist even after the application returns from the callback. This means that you should not allocate such storage on the stack.

Related Functions

OCIBindByName(), OCIBindByPos()


OCIBindObject()

Purpose

This function sets up additional attributes which are required for a named data type (object) bind.

Syntax

sword OCIBindObject ( OCIBind          *bindp,
                      OCIError         *errhp, 
                      CONST OCIType    *type,
                      dvoid            **pgvpp, 
                      ub4              *pvszsp, 
                      dvoid            **indpp, 
                      ub4              *indszp, );

Parameters

bindp (IN/OUT)

The bind handle returned by the call to OCIBindByName() or OCIBindByPos().

errhp (IN/OUT)

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

type (IN)

Points to the TDO which describes the type of the program variable being bound. Retrieved by calling OCITypeByName(). Optional for REFs in SQL, but required for REFs in PL/SQL.

pgvpp (IN/OUT)

Address of the program variable buffer. For an array, pgvpp points to an array of addresses. When the bind variable is also an OUT variable, the OUT Named Data Type value or REF is allocated in the Object Cache, and a REF is returned.

pgvpp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the Named Data Type buffers are requested at runtime. For static array binds, skip factors may be specified using the OCIBindArrayOfStruct() call. The skip factors are used to compute the address of the next pointer to the value, the indicator structure and their sizes.

pvszsp (OUT) [optional]

Points to the size of the program variable. The size of the named data type is not required on input. For an array, pvszsp is an array of ub4s. On return, for OUT bind variables, this points to size(s) of the Named Data Types and REFs received. pvszsp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the size of the buffer is taken at runtime.

indpp (IN/OUT) [optional]

Address of the program variable buffer containing the parallel indicator structure. For an array, points to an array of pointers. When the bind variable is also an OUT bind variable, memory is allocated in the object cache, to store the OUT indicator values. At the end of the execute when all OUT values have been received, indpp points to the pointer(s) to these newly allocated indicator structure(s). Required only for SQLT_NTY binds. indpp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the indicator is requested at runtime.

indszp (IN/OUT)

Points to the size of the IN indicator structure program variable. For an array, it is an array of sb2s. On return for OUT bind variables, this points to size(s) of the received OUT indicator structures. indszp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the indicator size is requested at runtime.

Comments

This function sets up additional attributes which binding a named data type or a REF. An error will be returned if this function is called when the OCI environment has been initialized in non-object mode.

This call takes as a parameter a type descriptor object (TDO) of datatype OCIType for the named data type being defined. The TDO can be retrieved with a call to OCITypeByName().

If the OCI_DATA_AT_EXEC mode was specified in OCIBindByName() or OCIBindByPos(), the pointers to the IN buffers are obtained either using the callback icbfp registered in the OCIBindDynamic() call or by the OCIStmtSetPieceInfo() call. The buffers are dynamically allocated for the OUT data and the pointers to these buffers are returned either by calling ocbfp() registered by the OCIBindDynamic() or by setting the pointer to the buffer in the buffer passed in by OCIStmtSetPieceInfo() called when OCIStmtExecute() returned OCI_NEED_DATA. The memory of these client library-allocated buffers must be freed when not in use anymore by using the OCIObjectFree() call.

Related Functions

OCIBindByName(), OCIBindByPos()


OCIDefineArrayOfStruct()

Purpose

This call specifies additional attributes necessary for a static array define, used in an array of structures (multi-row, multi-column) fetch.

Syntax

sword OCIDefineArrayOfStruct ( OCIDefine   *defnp,
                               OCIError    *errhp,
                               ub4         pvskip, 
                               ub4         indskip, 
                               ub4         rlskip,
                               ub4         rcskip );

Parameters

defnp (IN/OUT)

The handle to the define structure which was returned by a call to OCIDefineByPos().

errhp (IN/OUT)

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

pvskip (IN)

Skip parameter for the next data value.

indskip (IN)

Skip parameter for the next indicator location.

rlskip (IN)

Skip parameter for the next return length value.

rcskip (IN)

Skip parameter for the next return code.

Comments

This call follows a call to OCIDefineByPos().

If the application is binding an array of structures involving objects, it must call OCIDefineObject() first, and then call OCIDefineArrayOfStruct().

For more information about skip parameters, see the section "Skip Parameters".

Related Functions

OCIDefineByPos(), OCIDefineObject()


OCIDefineByPos()

Purpose

Associates an item in a select-list with the type and output data buffer.

Syntax

sword OCIDefineByPos ( OCIStmt     *stmtp, 
                       OCIDefine   **defnpp,
                       OCIError    *errhp,
                       ub4         position,
                       dvoid       *valuep,
                       sb4         value_sz,
                       ub2         dty,
                       dvoid       *indp,
                       ub2         *rlenp,
                       ub2         *rcodep,
                       ub4         mode );

Parameters

stmtp (IN/OUT)

A handle to the requested SQL query operation.

defnpp (IN/OUT)

A pointer to a pointer to a define handle. If this parameter is passed as NULL, this call implicitly allocates the define handle. In the case of a redefine, a non-NULL handle can be passed in this parameter. This handle is used to store the define information for this column.

Note: The user must keep track of this pointer. If a second call to OCIDefineByPos() is made for the same column position, there is no guarantee that the same pointer is returned.

errhp (IN/OUT)

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

position (IN)

The position of this value in the select list. Positions are 1-based and are numbered from left to right. For example, in the SELECT statement

SELECT empno, ssn, mgrno FROM employees;

empno is at position 1, ssn is at position 2, and mgrno is at position 3.

valuep (IN/OUT)

A pointer to a buffer or an array of buffers of the type specified in the dty parameter. A number of buffers can be specified when results for more than one row are desired in a single fetch call.

value_sz (IN)

The size of each valuep buffer in bytes. If the data is stored internally in VARCHAR2 format, the number of characters desired, if different from the buffer size in bytes, may be additionally specified by the using OCIAttrSet().

In an NLS conversion environment, a truncation error will be generated if the number of bytes specified is insufficient to handle the number of characters desired.

If the OCI_ATTR_CHARSET_ID is attribute is set to OCI_UCS2ID (Unicode), all data passed to and received with the corresponding define call is assumed to be in UCS-2 encoding. For more information, refer to OCI_ATTR_CHARSET_ID.

dty (IN)

The data type. Named data type (SQLT_NTY) and REF (SQLT_REF) are valid only if the environment has been initialized with in object mode. For a listing of datatype codes and values, refer to Chapter 3, "Datatypes".

indp (IN)

pointer to an indicator variable or array. For scalar data types, pointer to sb2 or an array of sb2s. Ignored for SQLT_NTY defines. For SQLT_NTY defines, a pointer to a named data type indicator structure or an array of named data type indicator structures is associated by a subsequent OCIDefineObject() call.

See the section "Indicator Variables" for more information about indicator variables.

rlenp (IN/OUT)

Pointer to array of length of data fetched. Each element in rlenp is the length of the data in the corresponding element in the row after the fetch.

rcodep (OUT)

Pointer to array of column-level return codes

mode (IN)

The valid modes are:

Comments

This call defines an output buffer which will receive data retrieved from Oracle. The define is a local step which is necessary when a SELECT statement returns data to your OCI application.

This call also implicitly allocates the define handle for the select-list item. If a non-NULL pointer is passed in *defnpp, the OCI assumes that this points to a valid handle that has been previously allocated with a call to OCIHandleAlloc() or OCIDefineByPos(). This would be true in the case of an application which is redefining a handle to a different addresses so it can reuse the same define handle for multiple fetches.

Defining attributes of a column for a fetch is done in one or more calls. The first call is to OCIDefineByPos(), which defines the minimal attributes required to specify the fetch.

Following the call to OCIDefineByPos() additional define calls may be necessary for certain data types or fetch modes:

For a LOB define, the buffer pointer must be a pointer to a lob locator of type OCILobLocator, allocated by the OCIDescriptorAlloc() call. LOB locators, and not LOB values, are always returned for a LOB column. LOB values can then be fetched using OCI LOB calls on the fetched locator. This same mechanism is true for all descriptor datatypes.

For NCHAR (fixed and varying length), the buffer pointer must point to an array of bytes sufficient for holding the required NCHAR characters.

Nested table columns are defined and fetched like any other named data type.

When defining an array of descriptors or locators, you should pass in an array of pointers to descriptors or locators.

When doing an array define for character columns, you should pass in an array of character buffers.

If the mode parameter is this call is set to OCI_DYNAMIC_FETCH, the client application can fetch data dynamically at runtime. Runtime data can be provided in one of two ways:

Related Functions

OCIDefineArrayOfStruct(), OCIDefineDynamic(), OCIDefineObject()


OCIDefineDynamic()

Purpose

This call is used to set the additional attributes required if the OCI_DYNAMIC_FETCH mode was selected in OCIDefineByPos().

Syntax

sword OCIDefineDynamic ( OCIDefine   *defnp,
                         OCIError    *errhp,
                         dvoid       *octxp, 
                         OCICallbackDefine       (ocbfp)(/*_
                                  dvoid          *octxp,
                                  OCIDefine      *defnp,
                                  ub4            iter, 
                                  dvoid          **bufpp,
                                  ub4            **alenpp,
                                  ub1            *piecep,
                                  dvoid          **indpp,
                                  ub2            **rcodep _*/)  );

Parameters

defnp (IN/OUT)

The handle to a define structure returned by a call to OCIDefineByPos().

errhp (IN/OUT)

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

octxp (IN)

Points to a context for the callback function.

ocbfp (IN)

Points to a callback function. This is invoked at runtime to get a pointer to the buffer into which the fetched data or a piece of it will be retrieved. The callback also specifies the indicator, the return code and the lengths of the data piece and indicator.

Warning: When working with callback parameters, it is important to keep in mind what is meant by IN and OUT for the parameter mode. Normally, in an OCI function, an IN parameter refers to data being passed to Oracle, and an OUT parameter refers to data coming back from Oracle. In the case of callbacks, this is reversed. IN means data is coming from Oracle into the callback, and OUT means data is coming out of the callback and going to Oracle.

The callback parameters are listed below:

octxp (IN/OUT)

A context pointer passed as an argument to all the callback functions.

defnp (IN)

The define handle.

iter (IN)

Which row of this current fetch; 0-based.

bufpp (OUT)

Returns to Oracle a pointer to a buffer to store the column value, i.e., *bufpp points to some appropriate storage for the column value.

alenpp (IN/OUT)

Used by the application to set the size of the storage it is providing in *bufpp. After data is fetched into the buffer, alenpp indicates the actual size of the data.

piecep (IN/OUT)

Returns a piece value from the callback (application) to Oracle, as follows:

  • IN - The value can be OCI_ONE_PIECE or OCI_NEXT_PIECE.

  • OUT - Depends on the IN value:

    If IN value is OCI_ONE_PIECE, then OUT value can be OCI_ONE_PIECE or OCI_FIRST_PIECE

    If IN value is OCI_NEXT_PIECE then OUT value can be OCI_NEXT_PIECE or OCI_LAST_PIECE

indpp (IN)

Indicator variable pointer

rcodep (IN)

Return code variable pointer

Comments

This call is used to set the additional attributes required if the OCI_DYNAMIC_FETCH mode has been selected in a call to OCIDefineByPos(). If OCI_DYNAMIC_FETCH mode was selected, and the call to OCIDefineDynamic() is skipped, then the application can fetch data piecewise using OCI calls (OCIStmtGetPieceInfo() and OCIStmtSetPieceInfo()). For more information about OCI_DYNAMIC_FETCH mode, see the section "Run Time Data Allocation and Piecewise Operations".

Related Functions

OCIDefineByPos()


OCIDefineObject()

Purpose

Sets up additional attributes necessary for a Named Data Type or REF define.

Syntax

sword OCIDefineObject ( OCIDefine       *defnp,
                        OCIError        *errhp,
                        CONST OCIType   *type,
                        dvoid           **pgvpp, 
                        ub4             *pvszsp, 
                        dvoid           **indpp, 
                        ub4             *indszp );

Parameters

defnp (IN/OUT)

A define handle previously allocated in a call to OCIDefineByPos().

errhp (IN/OUT)

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

type (IN) [optional]

Points to the Type Descriptor Object (TDO) which describes the type of the program variable. Only used for program variables of type SQLT_NTY. This parameter is optional, and may be passed as NULL if it is not being used.

pgvpp (IN/OUT)

Points to a pointer to a program variable buffer. For an array, pgvpp points to an array of pointers. Memory for the fetched named data type instance(s) is dynamically allocated in the object cache. At the end of the fetch when all the values have been received, pgvpp points to the pointer(s) to these newly allocated named data type instance(s). The application must call OCIObjectFree() to deallocate the named data type instance(s) when they are no longer needed.

Note: If the application wants the buffer to be implicitly allocated in the cache, *pgvpp should be passed in as NULL.

pvszsp (IN/OUT)

Points to the size of the program variable. For an array, it is an array of ub4s.

indpp (IN/OUT)

Points to a pointer to the program variable buffer containing the parallel indicator structure. For an array, points to an array of pointers. Memory is allocated to store the indicator structures in the object cache. At the end of the fetch when all values have been received, indpp points to the pointer(s) to these newly allocated indicator structure(s).

indszp (IN/OUT)

Points to the size(s) of the indicator structure program variable. For an array, it is an array of ub4s.

Comments

This function follows a call to OCIDefineByPos() to set initial define information. This call sets up additional attributes necessary for a Named Data Type define. An error will be returned if this function is called when the OCI environment has been initialized in non-Object mode.

This call takes as a parameter a type descriptor object (TDO) of datatype OCIType for the named data type being defined. The TDO can be retrieved with a call to OCIDescribeAny().

See Also: See the description of OCIInitialize() for more information about initializing the OCI process environment.

Related Functions

OCIDefineByPos()


OCIDescribeAny()

Purpose

Describes existing schema and sub-schema objects.

Syntax

sword OCIDescribeAny ( OCISvcCtx       *svchp,
                       OCIError        *errhp,
                       dvoid           *objptr,
                       ub4             objptr_len,
                       ub1             objptr_typ,
                       ub1             info_level,
                       ub1             objtyp,
                       OCIDescribe     *dschp );

Parameters

svchp (IN)

A service context handle.

errhp (IN/OUT)

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

objptr (IN)

This parameter can be:

  1. a string containing the name of the object to be described

  2. a pointer to a REF to the TDO (for a type)

  3. a pointer to a TDO (for a type).

These cases are distinguished by passing the appropriate value for objptr_typ. This parameter must be non-NULL.

In case 1, the string containing the object name should be in the format <name1>[.<name2>.<name3>...][@<linkname>], such as scott.emp.empno@mydb. Database links are only allowed to Oracle8i databases. The object name is interpreted by the following SQL rules:

objnm_len (IN)

The length of the name string pointed to by objptr. Must be non-zero if a name is passed. Can be zero if objptr is a pointer to a TDO or its REF.

objptr_typ (IN)

The type of object passed in objptr. Valid values are:

info_level (IN)

Reserved for future extensions. Pass OCI_DEFAULT.

objtyp (IN/OUT)

The type of schema object being described. Valid values are:

A value for this argument must be specified. If OCI_PTYPE_UNK is specified, then the description of an object with the specified name in the current schema is returned, if such an object exists, along with the actual type of the object.

dschp (IN/OUT)

A describe handle that is populated with describe information about the object after the call. Must be non-NULL.

Comments

This is a generic describe call that describes existing schema objects: tables, views, synonyms, procedures, functions, packages, sequences, types, schemas, and databases. This call also describes sub-schema objects, such as a column in a table. This call populates the describe handle with the object-specific attributes which can be obtained through an OCIAttrGet() call.

An OCIParamGet() on the describe handle returns a parameter descriptor for a specified position. Parameter positions begin with 1. Calling OCIAttrGet() on the parameter descriptor returns the specific attributes of a stored procedure or function parameter, or a table column descriptor. These subsequent calls do not need an extra round trip to the server because the entire schema object description is cached on the client side by OCIDescribeAny(). Calling OCIAttrGet() on the describe handle also returns the total number of positions.

If the OCI_ATTR_DESC_PUBLIC attribute is set on the describe handle, then the object named is looked up as a public synonym when the object does not exist in the current schema and only <name1> is specified.

For more information about describe operations, see Chapter 6, "Describing Schema Metadata".

Related Functions

OCIAttrGet(), OCIParamGet()


OCIStmtGetBindInfo()

Purpose

Gets the bind and indicator variable names.

Syntax

sword OCIStmtGetBindInfo ( OCIStmt      *stmtp,
                           OCIError     *errhp,
                           ub4          size,
                           ub4          startloc,
                           sb4          *found,
                           text         *bvnp[],
                           ub1          bvnl[],
                           text         *invp[],
                           ub1          inpl[],
                           ub1          dupl[],
                           OCIBind      *hndl[] );

Parameters

stmtp (IN)

The statement handle.

errhp (IN)

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

size (IN)

The number of elements in each array.

startloc (IN)

Position of the bind variable at which to start getting bind information.

found (IN)

Abs(found) gives the total number of bind variables in the statement irrespective of the start position. Positive value if the number of bind variables returned is less than the size provided, otherwise negative.

bvnp (OUT)

Array of pointers to hold bind variable names.

bvnl (OUT)

Array to hold the length of the each bvnp element.

invp (OUT)

Array of pointers to hold indicator variable names.

inpl (OUT)

Array of pointers to hold the length of the each invp element.

dupl (OUT)

An array whose element value is 0 or 1 depending on whether the bind position is duplicate of another.

hndl (OUT)

An array which returns the bind handle if binds have been done for the bind position. No handle is returned for duplicates.

Comments

This call returns information about bind variables after a statement has been prepared. This includes bind names, indicator names, and whether or not binds are duplicate binds. This call also returns an associated bind handle if there is one. The call sets the found parameter to the total number of bind variables and not just the number of distinct bind variables.

This function does not include SELECT INTO list variables, because they are not considered to be binds.

The statement must have been prepared with a call to OCIStmtPrepare() prior to this call.

This call is processed locally.

Related Functions

OCIStmtPrepare()

Direct Path Loading Functions

This section describes the direct path loading functions.

Table 15-4 OCI Quick Reference
Function  Purpose 

OCIDirPathAbort()  

Aborts a direct path operation  

OCIDirPathColArrayEntryGet()  

Gets a specified entry in a column array  

OCIDirPathColArrayEntrySet()  

Sets a specified entry in a column array to a specific value  

OCIDirPathColArrayRowGet()  

Gets the base row pointers for a specified row number  

OCIDirPathColArrayReset()  

Resets the row array state  

OCIDirPathColArrayToStream()  

Converts from a column array to a direct path stream format  

OCIDirPathFinish()  

Finishes and commits the loaded data  

OCIDirPathLoadStream()  

Loads data that has been converted to direct path stream format  

OCIDirPathPrepare()  

Prepares direct path interface to convert or load rows  

OCIDirPathStreamReset()  

Resets the direct stream state  


OCIDirPathAbort()

Purpose

Aborts a direct path operation.

Syntax

sword OCIDirPathAbort   ( OCIDirPathCtx          *dpctx,
                          OCIError               *errhp ); 

Parameters

dpctx (IN)

Direct path context handle.

errhp (IN/OUT)

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

Comments

All state maintained by the server on behalf of the direct path operation is destroyed by an abort. For a direct path load, the data loaded prior to the abort will not be visible to any queries. However, the data may still consume space in the segments that are being loaded. Any load completion operations, such as index maintenance operations, are not performed.

Related Functions

OCIDirPathFinish(), OCIDirPathLoadStream(), OCIDirPathPrepare(), OCIDirPathLoadStream(), OCIDirPathStreamReset()


OCIDirPathColArrayEntryGet()

Purpose

Gets a specified entry in a column array.

Syntax

sword OCIDirPathColArrayEntryGet ( OCIDirPathColArray   *dpca,
                                   OCIError             *errhp,
                                   ub4                  rownum,
                                   ub2                  colIdx,
                                   ub1                  **cvalpp,
                                   ub4                  *clenp,
                                   ub1                  *cflgp );

Parameters

dpca (IN/OUT)

Direct path column array handle.

errhp (IN)

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

rownum (IN)

Zero-based row offset

colIdx (IN)

Column identifier (index), the column ID is returned by OCIDirPathColAttrSet()

cvalpp (IN/OUT)

Pointer to pointer to column data

clenp (IN/OUT)

Pointer to length of column data

cflgp (IN/OUT)

Pointer to column flag.

One of the following values is returned:

Comments

If cflgp is set to NULL, the cvalp and clenp parameters are not set by this operation.

Related Functions

OCIDirPathColArrayEntrySet(), OCIDirPathColArrayRowGet(), OCIDirPathColArrayReset(), OCIDirPathColArrayToStream()


OCIDirPathColArrayEntrySet()

Purpose

Sets a specified entry in a column array to the supplied values.

Syntax

sword OCIDirPathColArrayEntrySet ( OCIDirPathColArray   *dpca,
                                   OCIError             *errhp,
                                   ub4                  rownum,
                                   ub2                  colIdx,
                                   ub1                  *cvalp,
                                   ub4                  clen,
                                   ub1                  cflg );

Parameters

dpca (IN/OUT)

Direct path column array handle.

errhp (IN)

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

rownum (IN)

Zero-based row offset

colIdx (IN)

Column identifier (index), the column ID is returned by OCIDirPathColAttrSet()

cvalp (IN)

Pointer to column data

clen (IN)

Length of column data

cflg (IN)

Column flag. One of the following values is returned:

Comments

If cflg is set to NULL, the cval and clen parameters are not used.

Example

This example sets the source of data for the first row in a column array to addr, with a length of len. In this example, the column is identified by colId.

err = OCIDirPathColArrayEntrySet(dpca, errhp, (ub2)0, colId, addr, len,
                                OCI_DIRPATH_COL_COMPLETE);

Related Functions

OCIDirPathColArrayEntryGet(), OCIDirPathColArrayRowGet(), OCIDirPathColArrayReset(), OCIDirPathColArrayToStream()


OCIDirPathColArrayRowGet()

Purpose

Gets the column array row pointers for a given row number

Syntax

sword OCIDirPathColArrayRowGet ( OCIDirPathColArray   *dpca,
                                 OCIError             *errhp,
                                 ub4                  rownum,
                                 ub1                  ***cvalppp,
                                 ub4                  **clenpp,
                                 ub1                  **cflgpp );

Parameters

dpca (IN/OUT)

Direct path column array handle.

errhp (IN)

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

rownum (IN)

Zero-based row offset

cvalppp (IN/OUT)

Pointer to vector of pointers to column data

clenpp (IN/OUT)

Pointer to vector of column data lengths

cflgpp (IN/OUT)

Pointer to vector of column flags

Comments

The application does simple pointer arithmetic to iterate across the columns of the specific row. This interface can be used to efficiently get or set the column array entries of a row, as opposed to calling OCIDirPathColArrayEntrySet() for every column. The application is also responsible for not de-referencing memory beyond the column array boundaries. The dimensions of the column array are available as attributes of the column array.

Related Functions

OCIDirPathColArrayEntryGet(), OCIDirPathColArrayEntrySet(), OCIDirPathColArrayReset(), OCIDirPathColArrayToStream()


OCIDirPathColArrayReset()

Purpose

Resets the column array state.

Syntax

sword OCIDirPathColArrayReset ( OCIDirPathColArray   *dpca,
                                OCIError             *errhp );

Parameters

dpca (IN)

Direct path column array handle.

errhp (IN)

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

Comments

Resetting the column array state is necessary when piecing in a large column and an error occurs in the middle of loading the column.

Related Functions

OCIDirPathColArrayEntryGet(), OCIDirPathColArrayEntrySet(), OCIDirPathColArrayRowGet(), OCIDirPathColArrayToStream()


OCIDirPathColArrayToStream()

Purpose

Converts from column array format to a direct path stream format.

Syntax

sword OCIDirPathColArrayToStream ( OCIDirPathColArray     *dpca,
                                   OCIDirPathCtx  const   *dpctx,
                                   OCIDirPathStream       *dpstr,
                                   OCIError               *errhp, 
                                   ub4                    rowcnt,
                                   ub4                    rowoff );

Parameters

dpca (IN)

Direct path column array handle.

dpctx (IN)

Direct path context handle for the object being loaded.

dpstr (IN/OUT)

Direct path stream handle.

errhp (IN)

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

rowcnt (IN)

Number of rows in the column array.

rowoff (IN)

Starting index in the column array.

Comments

This interface is used to convert a column array representation of data in its external format as specified by OCIDirPathColAttrSet() to a direct path stream format. The converted format is suitable for loading with OCIDirPathLoadStream().

The column data in direct path stream format is converted to its Oracle internal representation. All conversions are done on the client side of the two-task interface, all conversion errors occur synchronously with the call to this interface. Information concerning which row and column that an error occurred on is available as an attribute of the column array handle.

Note that in a threaded environment concurrent OCIDirPathColArrayToStream() operations can be referencing the same direct path context handle. However, the direct path context handle is not modified by this interface.

The return codes for this call are:

Related Functions

OCIDirPathColArrayEntryGet(), OCIDirPathColArrayEntrySet(), OCIDirPathColArrayRowGet(), OCIDirPathColArrayReset()


OCIDirPathFinish()

Purpose

Finishes the direct path load operation.

Syntax

sword OCIDirPathFinish (   OCIDirPathCtx          *dpctx,
                           OCIError               *errhp ); 

Parameters

dpctx (IN)

Direct path context handle for the object loaded.

errhp (IN/OUT)

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

Comments

After the load has completed, and the loaded data is to be committed, the direct path finishing function is called.

A return value of OCI_SUCCESS indicates that the back-end has properly terminated the load.

Related Functions

OCIDirPathAbort(), OCIDirPathLoadStream(), OCIDirPathPrepare(), OCIDirPathLoadStream(), OCIDirPathStreamReset()


OCIDirPathLoadStream()

Purpose

Loads the data converted to direct path stream format.

Syntax

sword OCIDirPathLoadStream (   OCIDirPathCtx          *dpctx,
                               OCIDirPathStream       *dpstr,
                               OCIError               *errhp ); 

Parameters

dpctx (IN)

Direct path context handle for the object loaded.

dpstr (IN)

Direct path stream handle for the stream to load.

errhp (IN)

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

Comments

When the interface returns an error, information concerning the row in the column array that sourced the stream can be obtained as an attribute of the direct path stream. Also, the offset into the stream where the error occurred can be obtained as an attribute of the stream.

Return codes for this function are:

Related Functions

OCIDirPathAbort(), OCIDirPathFinish(), OCIDirPathLoadStream(), OCIDirPathPrepare(), OCIDirPathStreamReset()


OCIDirPathPrepare()

Purpose

Prepares the direct path load interface before any rows can be converted or loaded.

Syntax

sword OCIDirPathPrepare (   OCIDirPathCtx          *dpctx,
                            OCISvcCtx              *svchp,
                            OCIError               *errhp ); 

Parameters

dpctx (IN)

Direct path context handle for the object loaded.

svchp (IN)

Service context.

errhp (IN/OUT)

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

Comments

After the name of the object to be operated on is set, the external attributes of the column data is set, and all load options are set, the direct path interface must be prepared with OCIDirPathPrepare() before any rows can be converted or loaded.

A return value of OCI_SUCCESS indicates that the back-end has been properly initialized for a direct path load operation. A non-zero return indicates an error. Possible errors are:

Related Functions

OCIDirPathAbort(), OCIDirPathFinish(), OCIDirPathLoadStream(), OCIDirPathLoadStream(), OCIDirPathStreamReset()


OCIDirPathStreamReset()

Purpose

Resets the direct path stream state.

Syntax

sword OCIDirPathStreamReset ( OCIDirPathStream       *dpstr,
                              OCIError               *errhp,

Parameters

dpstr (IN)

Direct path stream handle.

errhp (IN)

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

Comments

A direct path stream maintains the state that indicates where the next OCIDirPathColArrayToStream() call should start writing into the stream. Normally, data is appended to the end of the stream. When the caller wants to start a new stream after a stream is successfully loaded, or discard the data in a stream, the stream must be reset with this call.

Related Functions

OCIDirPathAbort(), OCIDirPathFinish(), OCIDirPathLoadStream(), OCIDirPathPrepare(), OCIDirPathLoadStream()

Connect, Authorize, and Initialize Functions

This section describes the OCI connect, authorize, and initialize functions.

Table 15-5 OCI Quick Reference
Function  Purpose 

OCIEnvCreate()  

creates and initializes an OCI environment  

OCIEnvInit()  

Initialize an environment handle  

OCIInitialize()  

Initialize OCI process environment  

OCILogon()  

Simplified single-session logon  

OCIServerAttach()  

Attach to a server; initialize server context handle  

OCIServerDetach()  

Detach from a server; uninitialize server context handle  

OCISessionBegin()  

Authenticate a user  

OCISessionEnd()  

Terminate a user session  

OCITerminate()  

Detaches from a shared memory subsystem.  


OCIEnvCreate()

Purpose

Creates and initializes an environment for OCI functions to work under.

Syntax

sword OCIEnvCreate   ( OCIEnv        **envhpp,
                       ub4           mode,
                       CONST dvoid   *ctxp,
                       CONST dvoid   *(*malocfp)
                                     (dvoid *ctxp,
                                      size_t size),
                       CONST dvoid   *(*ralocfp)
                                     (dvoid *ctxp,
                                      dvoid *memptr,
                                      size_t newsize),
                       CONST void    (*mfreefp)
                                     (dvoid *ctxp,
                                      dvoid *memptr))
                       size_t    xtramemsz,
                       dvoid     **usrmempp );

Parameters

envhpp (OUT)

A pointer to a handle to the environment.

mode (IN)

Specifies initialization of the mode. Valid modes are:

ctxp (IN)

Specifies the user-defined context for the memory callback routines.

malocfp (IN)

Specifies the user-defined memory allocation function. If mode is OCI_THREADED, this memory allocation routine must be thread safe.

ctxp (IN)

Specifies the context pointer for the user-defined memory allocation function.

size (IN)

Specifies the size of memory to be allocated by the user-defined memory allocation function.

ralocfp (IN)

Specifies the user-defined memory re-allocation function. If the mode is OCI_THREADED, this memory allocation routine must be thread safe.

ctxp (IN)

Specifies the context pointer for the user-defined memory reallocation function.

memp (IN)

Pointer to memory block.

newsize (IN)

Specifies the new size of memory to be allocated

mfreefp (IN)

Specifies the user-defined memory free function. If mode is OCI_THREADED, this memory free routine must be thread safe.

ctxp (IN)

Specifies the context pointer for the user-defined memory free function.

memptr (IN)

Pointer to memory to be freed

xtramemsz (IN)

Specifies the amount of user memory to be allocated for the duration of the environment.

usrmempp (OUT)

Returns a pointer to the user memory of size xtramemsz allocated by the call for the user.

Comments

This call creates an environment for all the OCI calls using the modes specified by the user. This call should be invoked before any other OCI call and should be used instead of the OCIInitialize() and OCIEnvInit() calls. OCIInitialize() and OCIEnvInit() calls will be supported for backward compatibility.

This call returns an environment handle which is then used by the remaining OCI functions. There can be multiple environments in OCI, each with its own environment modes. This function also performs any process level initialization if required by any mode. For example if the user wants to initialize an environment as OCI_THREADED, then all libraries that are used by OCI are also initialized in the threaded mode.

If you are writing a DLL or a shared library using OCI library then this call should definitely be used instead of OCIInitialize() and OCIEnvInit() call.

For more information about the xtramemsz parameter and user memory allocation, refer to "User Memory Allocation".

Related Functions

OCIHandleAlloc(), OCIHandleFree(),OCIEnvInit(), OCIInitialize(), OCITerminate()


OCIEnvInit()

Purpose

Allocates and initializes an OCI environment handle.

Syntax

sword OCIEnvInit ( OCIEnv    **envhpp,
                   ub4       mode,
                   size_t    xtramemsz,
                   dvoid     **usrmempp );

Parameters

envhpp (OUT)

A pointer to a handle to the environment.

mode (IN)

Specifies initialization of an environment mode. Valid modes are:

In OCI_DEFAULT mode, the OCI library always mutexes handles. In OCI_NO_MUTEX modes, there is no mutexing in this environment.

In OCI_NO_MUTEX mode, all OCI calls done on the environment handle, or on handles derived from the environment handle, must be serialized. This can be done by either doing your own mutexing or by having only one thread operating on the environment handle.

The OCI_ENV_NO_UCB mode is used to suppress the calling of the dynamic callback routine OCIEnvCallback at environment initialization time. The default behavior is to allow such a call to be made. See "Dynamic Callback Registrations" for more information.

xtramemsz (IN)

Specifies the amount of user memory to be allocated for the duration of the environment.

usrmempp (OUT)

Returns a pointer to the user memory of size xtramemsz allocated by the call for the user for the duration of the environment.

Comments

Note: OCIEnvCreate() should be used instead of the OCIInitialize() and OCIEnvInit() calls. OCIInitialize() and OCIEnvInit() calls will be supported for backward compatibility.

This call allocates and initializes an OCI environment handle. No changes are done to an already initialized handle. If OCI_ERROR or OCI_SUCCESS_WITH_INFO is returned, the environment handle can be used to obtain ORACLE specific errors and diagnostics.

This call is processed locally, without a server round-trip.

The environment handle can be freed using OCIHandleFree().

For more information about the xtramemsz parameter and user memory allocation, refer to "User Memory Allocation".

Related Functions

OCIHandleAlloc(), OCIHandleFree(), OCIEnvCreate(), OCITerminate()


OCIInitialize()

Purpose

Initializes the OCI process environment.

Syntax

sword OCIInitialize ( ub4           mode,
                      CONST dvoid   *ctxp, 
                      CONST dvoid   *(*malocfp) 
                                    (/* dvoid *ctxp,
                                        size_t size _*/),
                      CONST dvoid   *(*ralocfp)
                                    (/*_ dvoid *ctxp,
                                       dvoid *memptr,
                                       size_t newsize _*/),
                      CONST void    (*mfreefp)
                                    (/*_ dvoid *ctxp,
                                       dvoid *memptr _*/));

Parameters

mode (IN)

Specifies initialization of the mode. The valid modes are:

ctxp (IN)

User defined context for the memory call back routines.

malocfp (IN)

User-defined memory allocation function. If mode is OCI_THREADED, this memory allocation routine must be thread safe.

ctxp (IN/OUT)

Context pointer for the user-defined memory allocation function.

size (IN)

Size of memory to be allocated by the user-defined memory allocation function

ralocfp (IN)

User-defined memory re-allocation function. If mode is OCI_THREADED, this memory allocation routine must be thread safe.

ctxp (IN/OUT)

Context pointer for the user-defined memory reallocation function.

memptr (IN/OUT)

Pointer to memory block

newsize (IN)

New size of memory to be allocated

mfreefp (IN)

User-defined memory free function. If mode is OCI_THREADED, this memory free routine must be thread safe.

ctxp (IN/OUT)

Context pointer for the user-defined memory free function.

memptr (IN/OUT)

Pointer to memory to be freed

Comments

Note: OCIEnvCreate() should be used instead of the OCIInitialize() and OCIEnvInit() calls. OCIInitialize() and OCIEnvInit() calls will be supported for backward compatibility.

This call initializes the OCI process environment. OCIInitialize() must be invoked before any other OCI call.

This function provides the ability for the application to define its own memory management functions through callbacks. If the application has defined such functions (i.e., memory allocation, memory re-allocation, memory free), they should be registered using the callback parameters in this function.

These memory callbacks are optional. If the application passes NULL values for the memory callbacks in this function, the default process memory allocation mechanism is used.

Shared Data Structures Mode

When a SQL statement is processed, certain underlying data is associated with the statement. This data includes information about statement text and bind data, as well as define and describe information for queries. This data remains the same from one execution of a statement to another, even if the statement is executed by different users.

When an OCI application is initialized in OCI_SHARED mode, common statement data is shared between multiple statement handles, thus providing memory savings for the application. This savings may be particularly valuable for applications which create multiple statement handles which execute the same SQL statement on different users' sessions, either on the same or multiple connections. For more information, refer to "Shared Data Mode".

See Also: For information about using the OCI to write multi-threaded applications, refer to "Thread Safety".

For information about OCI programming with objects, refer to Chapter 10, "OCI Object-Relational Programming".

Example

The following statement shows an example of how to call OCIInitialize() in both threaded and object mode, with no user-defined memory functions:

OCIInitialize((ub4) OCI_THREADED | OCI_OBJECT, (dvoid *)0,
(dvoid * (*)()) 0, (dvoid * (*)()) 0, (void (*)()) 0 );

Related Functions

OCIHandleAlloc(), OCIHandleFree(), OCIEnvCreate(),OCIEnvInit(), OCITerminate()


OCILogoff()

Purpose

This function is used to terminate a connection and session created with OCILogon().

Syntax

sword OCILogoff ( OCISvcCtx      *svchp
                  OCIError       *errhp );

Parameters

svchp (IN)

The service context handle which was used in the call to OCILogon().

errhp (IN/OUT)

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

Comments

This call is used to terminate a session and connection which were created with OCILogon(). This call implicitly deallocates the server, user session, and service context handles.

Note: For more information on logging on and off in an application, refer to the section "Application Initialization, Connection, and Session Creation".

Related Functions

OCILogon()


OCILogon()

Purpose

This function is used to create a simple logon session.

Syntax

sword OCILogon ( OCIEnv          *envhp,
                 OCIError        *errhp,
                 OCISvcCtx       **svchp,
                 CONST text      *username,
                 ub4             uname_len,
                 CONST text      *password,
                 ub4             passwd_len,
                 CONST text      *dbname,
                 ub4             dbname_len );

Parameters

envhp (IN)

The OCI environment handle.

errhp (IN/OUT)

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

svchp (IN/OUT)

The service context pointer.

username (IN)

The username.

uname_len (IN)

The length of username.

password (IN)

The user's password.

passwd_len (IN)

The length of password.

dbname (IN)

The name of the database to connect to.

dbname_len (IN)

The length of dbname.

Comments

This function is used to create a simple logon session for an application.

Note: Users requiring more complex sessions, such as TP monitor applications, should refer to the section "Application Initialization, Connection, and Session Creation".

This call allocates the service context handles that are passed to it. This call also implicitly allocates server and user session handles associated with the session. These handles can be retrieved by calling OCIAttrGet() on the service context handle.

Related Functions

Statement Functions


OCIServerAttach()

Purpose

Creates an access path to a data source for OCI operations.

Syntax

sword OCIServerAttach ( OCIServer     *srvhp,
                        OCIError      *errhp,
                        CONST text    *dblink,
                        sb4           dblink_len,
                        ub4           mode );

Parameters

srvhp (IN/OUT)

An uninitialized server handle, which gets initialized by this call. Passing in an initialized server handle causes an error.

errhp (IN/OUT)

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

dblink (IN)

Specifies the database (server) to use. This parameter points to a character string which specifies a connect string or a service point. If the connect string is NULL, then this call attaches to the default host. The length of dblink is specified in dblink_len. The dblink pointer may be freed by the caller on return.

dblink_len (IN)

The length of the string pointed to by dblink. For a valid connect string name or alias, dblink_len must be non-zero.

mode (IN)

Specifies the various modes of operation. For release 8.0, pass as OCI_DEFAULT. In this mode, calls made to the server on this server context are made in blocking mode.

Comments

This call is used to create an association between an OCI application and a particular server.

This call initializes a server context handle, which must have been previously allocated with a call to OCIHandleAlloc(). The server context handle initialized by this call can be associated with a service context through a call to OCIAttrSet(). Once that association has been made, OCI operations can be performed against the server.

If an application is operating against multiple servers, multiple server context handles can be maintained. OCI operations are performed against whichever server context is currently associated with the service context.

When OCIServerAttach() is successfully completed, an Oracle shadow process is started. OCISessionEnd() and OCIServerDetach() should be called to clean up the Oracle shadow process. Otherwise, the shadow processes accumulate and cause the Unix system to run out of processes. If the database is restarted and there are not enough processes, the database may not startup.

Example

The following example demonstrates the use of OCIServerAttach(). This code segment allocates the server handle, makes the attach call, allocates the service context handle, and then sets the server context into it.

OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4) 
OCI_HTYPE_SERVER, 0, (dvoid **) &tmp); OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT); OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4)
OCI_HTYPE_SVCCTX, 0, (dvoid **) &tmp); /* set attribute server context in the service context */ OCIAttrSet( (dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX, (dvoid *) srvhp,
(ub4) 0, (ub4) OCI_ATTR_SERVER, (OCIError *) errhp);

Related Functions

OCIServerDetach()


OCIServerDetach()

Purpose

Deletes an access to a data source for OCI operations.

Syntax

sword OCIServerDetach ( OCIServer   *srvhp,
                        OCIError    *errhp,
                        ub4         mode ); 

Parameters

srvhp (IN)

A handle to an initialized server context, which gets reset to uninitialized state. The handle is not de-allocated.

errhp (IN/OUT)

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

mode (IN)

Specifies the various modes of operation. The only valid mode is OCI_DEFAULT for the default mode.

Comments

This call deletes an access to data source for OCI operations, which was established by a call to OCIServerAttach().

Related Functions

OCIServerAttach()


OCISessionBegin()

Purpose

Creates a user session and begins a user session for a given server.

Syntax

sword OCISessionBegin ( OCISvcCtx     *svchp,
                        OCIError      *errhp,
                        OCISession    *usrhp,
                        ub4           credt,
                        ub4           mode );

Parameters

svchp (IN)

A handle to a service context. There must be a valid server handle set in svchp.

errhp (IN)

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

usrhp (IN/OUT)

A handle to an user session context, which is initialized by this call.

credt (IN)

Specifies the type of credentials to use for establishing the user session. Valid values for credt are:

mode (IN)

Specifies the various modes of operation. Valid modes are:

Comments

The OCISessionBegin() call is used to authenticate a user against the server set in the service context handle.

Note: Check for any errors returned when trying to start a session. For example, if the password for the account has expired, an ORA-28001 error is returned.

For Oracle8i, OCISessionBegin() must be called for any given server handle before requests can be made against it. Also, OCISessionBegin() only supports authenticating the user for access to the Oracle server specified by the server handle in the service context. In other words, after OCIServerAttach() is called to initialize a server handle, OCISessionBegin() must be called to authenticate the user for that given server.

When OCISessionBegin() is called for the first time for a given server handle, the user session may not be created in migratable (OCI_MIGRATE) mode.

After OCISessionBegin() has been called for a server handle, the application may call OCISessionBegin() again to initialize another user session handle with different (or the same) credentials and different (or the same) operation modes. If an application wants to authenticate a user in OCI_MIGRATE mode, the service handle must already be associated with a non-migratable user handle. The user ID of that user handle becomes the ownership ID of the migratable user session. Every migratable session must have a non-migratable parent session.

If the OCI_MIGRATE mode is not specified, then the user session context can only be used with the same server handle set in svchp. If OCI_MIGRATE mode is specified, then the user authentication may be set with different server handles. However, the user session context may only be used with server handles which resolve to the same database instance. Security checking is done during session switching. A process or circuit is allowed to switch to a migratable session only if the ownership ID of the session matches the user ID of a non-migratable session currently connected to that same process or circuit, unless it is the creator of the session.

OCI_SYSDBA, OCI_SYSOPER, and OCI_PRELIM_AUTH may only be used with a primary user session context.

To provide credentials for a call to OCISessionBegin(), one of two methods are supported. The first is to provide a valid username and password pair for database authentication in the user session handle passed to OCISessionBegin(). This involves using OCIAttrSet() to set the OCI_ATTR_USERNAME and OCI_ATTR_PASSWORD attributes on the user session handle. Then OCISessionBegin() is called with OCI_CRED_RDBMS.

Note: When the user session handle is terminated using OCISessionEnd(), the username and password attributes remain unchanged and thus can be re-used in a future call to OCISessionBegin(). Otherwise, they must be reset to new values before the next OCISessionBegin() call.

The second type of credentials supported are external credentials. No attributes need to be set on the user session handle before calling OCISessionBegin(). The credential type is OCI_CRED_EXT. This is equivalent to the Oracle7 'connect /' syntax. If values have been set for OCI_ATTR_USERNAME and OCI_ATTR_PASSWORD, then these are ignored if OCI_CRED_EXT is used.

Another way of setting credentials is to use the session Id of an already authenticated user with the OCI_MIGSESSION attribute. This Id can be extracted from the session handle of an authenticated user using the OCIAttrGet() call.

Example

The following example demonstrates the use of OCISessionBegin(). This code segment allocates the user session handle, sets the username and password attributes, calls OCISessionBegin(), and then sets the user session into the service context.

/* allocate a user session handle */
OCIHandleAlloc((dvoid *)envhp, (dvoid **)&usrhp, (ub4) 
OCI_HTYPE_SESSION, (size_t) 0, (dvoid **) 0); OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"jessica",
(ub4)strlen("jessica"), OCI_ATTR_USERNAME, errhp); OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"doogie",
(ub4)strlen("doogie"), OCI_ATTR_PASSWORD, errhp); checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
OCI_DEFAULT)); OCIAttrSet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX, (dvoid *)usrhp,
(ub4)0, OCI_ATTR_SESSION, errhp);

Related Functions

OCISessionEnd()


OCISessionEnd()

Purpose

Terminates a user session context created by OCISessionBegin()

Syntax

sword OCISessionEnd ( OCISvcCtx       *svchp,
                      OCIError        *errhp,
                      OCISession      *usrhp,
                      ub4             mode );

Parameters

svchp (IN/OUT)

The service context handle. There must be a valid server handle and user session handle associated with svchp.

errhp (IN/OUT)

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

usrhp (IN)

De-authenticate this user. If this parameter is passed as NULL, the user in the service context handle is de-authenticated.

mode (IN)

The only valid mode is OCI_DEFAULT.

Comments

The user security context associated with the service context is invalidated by this call. Storage for the user session context is not freed. The transaction specified by the service context is implicitly committed. The transaction handle, if explicitly allocated, may be freed if not being used. Resources allocated on the server for this user are freed. The user session handle may be reused in a new call to OCISessionBegin().

Related Functions

OCISessionBegin()


OCITerminate()

Purpose

Detaches the process from the shared memory subsystem.

Syntax

sword OCITerminate ( ub4    mode);

Parameters

mode (IN)

Call-specific mode. Valid value:

Comments

OCITerminate() should be called only once per process and is the counterpart of OCIInitialize() call. The call will try to detach the process from the shared memory subsystem and shut it down if no other process is attached to it. It also performs additional process cleanup operations.

Related Functions

OCIInitialize()

LOB Functions

This section describes the LOB functions.

Table 15-6 OCI Quick Reference
Function  Purpose 

OCIDurationBegin()  

Start user duration for temporary LOB  

OCIDurationEnd()  

End user duration for temporary LOB  

OCILobAppend()  

Append one LOB to another  

OCILobAssign()  

Assign one LOB locator to another  

OCILobCharSetForm()  

Get character set form from LOB locator  

OCILobCharSetId()  

Get character set ID from LOB locator  

OCILobClose()  

Close a previously opened LOB  

OCILobCopy()  

Copy all or part of one LOB to another  

OCILobCreateTemporary()  

Create a temporary LOB  

OCILobDisableBuffering()  

Turn LOB buffering off  

OCILobEnableBuffering()  

Turn LOB buffering on  

OCILobErase()  

Erase a portion of a LOB  

OCILobFileClose()  

Close a previously opened FILE  

OCILobFileCloseAll()  

Close all previously opened files  

OCILobFileExists()  

Check if a file exists on the server  

OCILobFileGetName()  

Get directory alias and file NaMe from the LOB locator  

OCILobFileIsOpen()  

Check if file on server is open via this locator  

OCILobFileOpen()  

Open a FILE  

OCILobFileSetName()  

Set directory alias and file name in the LOB locator  

OCILobFlushBuffer()  

Flush the LOB buffer  

OCILobFreeTemporary()  

Free a temporary LOB  

OCILobGetChunkSize()  

Get the chunk size of a LOB  

OCILobGetLength()  

Get length of a LOB  

OCILobIsEqual()  

Compare two LOB locators for Equality  

OCILobIsOpen()  

Check to see if a LOB is open  

OCILobIsTemporary()  

Determine if a given LOB is a temporary LOB  

OCILobLoadFromFile()  

Load a LOB from a FILE  

OCILobLocatorAssign()  

Assigns one LOB locator to another  

OCILobLocatorIsInit()  

Check to see if a LOB locator is initialized  

OCILobOpen()  

Open a LOB  

OCILobRead()  

Read a portion of a LOB  

OCILobTrim()  

Truncate a LOB  

OCILobWrite()  

Write into a LOB  

OCILobWriteAppend()  

Write data beginning at the end of a LOB  

Note the following for parameters in the OCI LOB calls:


OCIDurationBegin()

Purpose

Begin of a user duration

Syntax

sword OCIDurationBegin ( OCIEnv              *env,
                         OCIError            *err,
                         CONST OCISvcCtx     *svc, 
                         OCIDuration         parent,
                         OCIDuration         *duration );

Parameters

env (IN/OUT)

Pass as a NULL pointer.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

svc (IN)

An OCI service context handle. Must be non-NULL.

parent (IN)

The duration number of the parent duration.

duration (OUT)

An identifier unique to the newly created user duration.

Comments

This function starts an user duration. In Release 8.1, user durations can be used when creating temporary LOBs. An user can have multiple active user durations simultaneously. The user durations do not have to be nested. The dur parameter is used to return a number which uniquely identifies the duration created by this call. For more information about user durations, see the section "Temporary LOB Durations".

Related Functions

OCIDurationEnd()


OCIDurationEnd()

Purpose

Terminates a user duration

Syntax

sword OCIDurationEnd ( OCIEnv             *env, 
                       OCIError           *err, 
                       CONST OCISvcCtx    *svc,
                       OCIDuration        duration );

Parameters

env (IN/OUT)

Pass as a NULL pointer.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

svc (IN)

OCI service context handle. Must be non-NULL.

duration (IN)

A number to identify the user duration.

Comments

This function terminates an user duration. Temporary LOBs that are allocated for the user duration are freed.

For more information about user durations, see the section "Temporary LOB Durations".

Related Functions

OCIDurationBegin()


OCILobAppend()

Purpose

Appends a LOB value at the end of another LOB as specified.

Syntax

sword OCILobAppend ( OCISvcCtx        *svchp,
                     OCIError         *errhp,
                     OCILobLocator    *dst_locp,
                     OCILobLocator    *src_locp );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

dst_locp (IN/OUT)

An internal LOB locator uniquely referencing the destination LOB. This locator must be a locator that was obtained from the server specified by svchp.

src_locp (IN)

An internal LOB locator uniquely referencing the source LOB. This locator must be a locator that was obtained from the server specified by svchp.

Comments

Appends a LOB value at the end of another LOB as specified. The data is copied from the source to the end of the destination. The source and destination LOBs must already exist. The destination LOB is extended to accommodate the newly written data. It is an error to extend the destination LOB beyond the maximum length allowed (4 gigabytes) or to try to copy from a NULL LOB.

The source and the destination LOB locators must be of the same type (i.e., they must both be BLOBs or both be CLOBs). LOB buffering must not be enabled for either type of locator. This function does not accept a FILE locator as the source or the destination.

Related Functions

OCILobTrim(), OCILobWrite(), OCILobCopy(), OCIErrorGet(), OCILobWriteAppend()


OCILobAssign()

Purpose

Assigns one LOB/FILE locator to another.

Syntax

sword OCILobAssign ( OCIEnv                *envhp, 
                     OCIError              *errhp, 
                     CONST OCILobLocator   *src_locp, 
                     OCILobLocator         **dst_locpp );

Parameters

envhp (IN/OUT)

OCI environment handle.

errhp (IN/OUT)

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

src_locp (IN)

LOB/FILE locator to copy from.

dst_locpp (IN/OUT)

LOB/FILE locator to copy to. The caller must have allocated space for the destination locator by calling OCIDescriptorAlloc().

Comments

Assign source locator to destination locator. After the assignment, both locators refer to the same LOB value. For internal LOBs, the source locator's LOB value gets copied to the destination locator's LOB value only when the destination locator gets stored in the table. Therefore, issuing a flush of the object containing the destination locator will copy the LOB value.

OCILobAssign() cannot be used for temporary LOBs; it will generate an OCI_INVALID_HANDLE error. For temporary LOBs, use OCILobLocatorAssign().

For FILEs, only the locator that refers to the file is copied to the table. The OS file itself is not copied.

It is an error to assign a FILE locator to an internal LOB locator, and vice versa.

If the source locator is for an internal LOB that was enabled for buffering, and the source locator has been used to modify the LOB data through the LOB buffering subsystem, and the buffers have not been flushed since the write, then the source locator may not be assigned to the destination locator. This is because only one locator per LOB may modify the LOB data through the LOB buffering subsystem.

The value of the input destination locator must have already been allocated with a call to OCIDescriptorAlloc(). For example, assume the following declarations:

OCILobLocator         *source_loc = (OCILobLocator *) 0;
OCILobLocator         *dest_loc = (OCILobLocator *) 0;

An application could allocate the source_loc locator as follows:

if (OCIDescriptorAlloc((dvoid *) envhp, (dvoid **) &source_loc,
(ub4) OCI_DTYPE_LOB, (size_t) 0, (dvoid **) 0)) handle_error;

Assume that it then selects a LOB from a table into the source_loc in order to initialize it. The application must allocate the destination locator, dest_loc, before issuing the OCILobAssign() call to assign the value of source_loc to dest_loc. For example:

if (OCIDescriptorAlloc((dvoid *) envhp, (dvoid **) &dest_loc,
(ub4)OCI_DTYPE_LOB, (size_t) 0, (dvoid **) 0)) handle_error; if (OCILobAssign(envhp, errhp, source_loc, &dest_loc)) handle_error;

Related Functions

OCIErrorGet(), OCILobIsEqual(), OCILobLocatorAssign(), OCILobLocatorIsInit(), OCILobEnableBuffering()


OCILobCharSetForm()

Purpose

Gets the LOB locator's character set form, if any.

Syntax

sword OCILobCharSetForm ( OCIEnv                *envhp, 
                          OCIError              *errhp, 
                          CONST OCILobLocator   *locp, 
                          ub1                   *csfrm );

Parameters

envhp (IN/OUT)

OCI environment handle.

errhp (IN/OUT)

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

locp (IN)

LOB locator for which to get the character set form.

csfrm (OUT)

Character set form of the input LOB locator. If the input locator is for a BLOB or a BFILE, csfrm is set to 0 since there is no concept of a character set for binary LOBs/FILEs. The caller must allocate space for the csfrm ub1.

Comments

Returns the character set form of the input LOB locator in the csfrm output parameter. This function makes sense only for character LOBs (i.e., CLOBs and NCLOBs).

Related Functions

OCIErrorGet(), OCILobCharSetId(), OCILobLocatorIsInit()


OCILobCharSetId()

Purpose

Gets the LOB locator's character set ID, if any.

Syntax

sword OCILobCharSetId ( OCIEnv                  *envhp, 
                        OCIError                *errhp, 
                        CONST OCILobLocator     *locp, 
                        ub2                     *csid );

Parameters

envhp (IN/OUT)

OCI environment handle.

errhp (IN/OUT)

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

locp (IN)

LOB locator for which to get the character set ID.

csid (OUT)

Character set ID of the input LOB locator. If the input locator is for a BLOB or a BFILE, csid is set to 0 since there is no concept of a character set for binary LOBs/FILEs. The caller must allocate space for the csid ub2.

Comments

Returns the character set ID of the input LOB locator in the csid output parameter.

This function makes sense only for character LOBs (i.e., CLOBs, NCLOBs).

Related Functions

OCIErrorGet(), OCILobCharSetForm(), OCILobLocatorIsInit()


OCILobClose()

Purpose

Closes a previously opened LOB or FILE.

Syntax

sword OCILobClose ( OCISvcCtx      *svchp,
                    OCIError       *errhp, 
                    OCILobLocator  *locp );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

locp (IN/OUT)

The LOB to close. The locator can refer to an internal or external LOB.

Comments

Closes a previously opened internal or external LOB. No error is returned if the BFILE exists but is not opened. An error is returned if the internal LOB is not open.

Closing a LOB requires a round-trip to the server for both internal and external LOBs. For internal LOBs, close will trigger other code that relies on the close call and for external LOBs (BFILEs), close actually closes the server-side operating system file.

See Also: Refer to "Functions for Opening and Closing LOBs" for more information.

Related Functions

OCIErrorGet(), OCILobOpen(), OCILobIsOpen()


OCILobCopy()

Purpose

Copies all or a portion of a LOB value into another LOB value

Syntax

sword OCILobCopy ( OCISvcCtx        *svchp,
                   OCIError         *errhp,
                   OCILobLocator    *dst_locp,
                   OCILobLocator    *src_locp,
                   ub4              amount,
                   ub4              dst_offset,
                   ub4              src_offset );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

dst_locp (IN/OUT)

An internal LOB locator uniquely referencing the destination LOB. This locator must be a locator that was obtained from the server specified by svchp.

src_locp (IN)

An internal LOB locator uniquely referencing the source LOB. This locator must be a locator that was obtained from the server specified by svchp.

amount (IN)

The number of characters for CLOBs/NCLOBs or bytes for BLOBs to be copied from the source LOB to the destination LOB.

dst_offset (IN)

This is the absolute offset for the destination LOB. For character LOBs it is the number of characters from the beginning of the LOB at which to begin writing. For binary LOBs it is the number of bytes from the beginning of the LOB from which to begin writing. The offset starts at 1.

src_offset (IN)

This is the absolute offset for the source LOB. For character LOBs it is the number of characters from the beginning of the LOB, for binary LOBs it is the number of bytes. Starts at 1.

Comments

Copies all or a portion of an internal LOB value into another internal LOB as specified. The data is copied from the source to the destination. The source (src_locp) and the destination (dst_locp) LOBs must already exist.

If the data already exists at the destination's start position, it is overwritten with the source data. If the destination's start position is beyond the end of the current data, zero-byte fillers (for BLOBs) or spaces (for CLOBs) are written into the destination LOB from the end of the current data to the beginning of the newly written data from the source. The destination LOB is extended to accommodate the newly written data if it extends beyond the current length of the destination LOB. It is an error to extend the destination LOB beyond the maximum length allowed (i.e., 4 gigabytes) or to try to copy from a NULL LOB.

Both the source and the destination LOB locators must be of the same type (i.e., they must both be BLOBs or both be CLOBs). LOB buffering must not be enabled for either locator.

This function does not accept a FILE locator as the source or the destination.

Note: You can call OCILobGetLength() to determine the length of the source LOB.

Related Functions

OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobWrite(), OCILobWriteAppend()


OCILobCreateTemporary()

Purpose

Create a temporary LOB

Syntax

sword OCILobCreateTemporary(OCISvcCtx          *svchp,
                            OCIError           *errhp,
                            OCILobLocator      *locp,
                            ub2                 csid,
                            ub1                 csfrm,
                            ub1                 lobtype,
                            boolean             cache,
                            OCIDuration         duration);

Parameters

svchp (IN)

The OCI service context handle.

errhp (IN/OUT)

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

locp (IN/OUT)

A locator which points to the temporary LOB. You must allocate the locator using OCIDescriptorAlloc() before passing it to this function. It does not matter whether or not this locator already points to a LOB, it will get overwritten either way.

csid (IN)

The LOB character set ID. For Oracle8i, pass as OCI_DEFAULT.

csfrm (IN)

The LOB character set form of the buffer data. For Oracle8i, pass as OCI_DEFAULT.

lobtype (IN)

The type of LOB to create. Valid values include:

cache (IN)

Pass TRUE if the temporary LOB should be read into the cache; FALSE, if it should not. The default is FALSE for NOCACHE functionality.

duration (IN)

The duration of the temporary LOB. The following are valid values:

Comments

This function creates a temporary LOB and its corresponding index in the user's temporary tablespace.

When this function is complete, the locp parameter points to an empty temporary LOB whose length is zero.

The lifetime of the temporary LOB is determined by the duration parameter. At the end of its duration the temporary LOB is freed. An application can free a temporary LOB sooner with the OCILobFreeTemporary() call.

If the LOB is a BLOB, the csid and csfrm parameters are ignored.

For more information about temporary LOBs and their durations, refer to "Temporary LOB Support".

Related functions

OCILobFreeTemporary(), OCILobIsTemporary(), OCIDescriptorAlloc(), OCIErrorGet()


OCILobDisableBuffering()

Purpose

Disable LOB buffering for the input locator.

Syntax

sword OCILobDisableBuffering ( OCISvcCtx      *svchp, 
                               OCIError       *errhp, 
                               OCILobLocator  *locp ); 

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

locp (IN/OUT)

An internal LOB locator uniquely referencing the LOB.

Comments

Disables LOB buffering for the input internal LOB locator. The next time data is read from or written to the LOB through the input locator, the LOB buffering subsystem is not used. Note that this call does not implicitly flush the changes made in the buffering subsystem. The user must explicitly call OCILobFlushBuffer() to do this.

This function does not accept a FILE locator.

Related Functions

OCILobEnableBuffering(), OCIErrorGet(), OCILobFlushBuffer()


OCILobEnableBuffering()

Purpose

Enable LOB buffering for the input locator.

Syntax

sword OCILobEnableBuffering ( OCISvcCtx      *svchp, 
                              OCIError       *errhp, 
                              OCILobLocator  *locp ); 

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

locp (IN/OUT)

An internal LOB locator uniquely referencing the LOB.

Comments

Enables LOB buffering for the input internal LOB locator. The next time data is read from or written to the LOB through the input locator, the LOB buffering subsystem is used.

If LOB buffering is enabled for a locator and that locator is passed to one of the following routines, an error is returned: OCILobAppend(), OCILobCopy(), OCILobErase(), OCILobGetLength(), OCILobLoadFromFile(), OCILobTrim(), or OCILobWriteAppend().

This function does not accept a FILE locator.

Related Functions

OCILobDisableBuffering(), OCIErrorGet(), OCILobWrite(), OCILobRead(), OCILobFlushBuffer(), OCILobWriteAppend()


OCILobErase()

Purpose

Erases a specified portion of the internal LOB data starting at a specified offset.

Syntax

sword OCILobErase ( OCISvcCtx       *svchp,
                    OCIError        *errhp,
                    OCILobLocator   *locp,
                    ub4             *amount,
                    ub4             offset );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

locp (IN/OUT)

An internal LOB locator that uniquely references the LOB. This locator must be a locator that was obtained from the server specified by svchp.

amount (IN/OUT)

The number of characters for CLOBs/NCLOBs or bytes for BLOBs to erase. On IN, the value signifies the number of characters or bytes to erase. On OUT, the value identifies the actual number of characters or bytes erased.

offset (IN)

Absolute offset in characters for CLOBs/NCLOBs or bytes for BLOBs from the beginning of the LOB value from which to start erasing data. Starts at 1.

Comments

The actual number of characters/bytes erased is returned. For BLOBs, erasing means that zero-byte fillers overwrite the existing LOB value. For CLOBs, erasing means that spaces overwrite the existing LOB value.

This function is valid only for internal LOBs; FILEs are not allowed.

Related Functions

OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobWrite(), OCILobWriteAppend()


OCILobFileClose()

Purpose

Closes a previously opened FILE.

Syntax

sword OCILobFileClose ( OCISvcCtx            *svchp,
                        OCIError             *errhp,
                        OCILobLocator        *filep );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

filep (IN/OUT)

A pointer to a FILE locator that refers to the FILE to be closed.

Comments

Closes a previously opened FILE. It is an error if this function is called for an internal LOB. No error is returned if the FILE exists but is not opened.

This function is only meaningful the first time it is called for a particular FILE locator. Subsequent calls to this function using the same FILE locator have no effect.

See Also: For more information about FILEs, refer to the description of BFILEs in the Oracle8i Application Developer's Guide - Large Objects (LOBs).

Related Functions

OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(), OCILobFileExists(), OCILobFileIsOpen(), OCILobFileOpen(), OCILobOpen(), OCILobIsOpen()


OCILobFileCloseAll()

Purpose

Closes all open FILEs on a given service context.

Syntax

sword OCILobFileCLoseAll ( OCISvcCtx   *svchp,
                           OCIError    *errhp );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

Comments

Closes all open FILEs on a given service context. It is an error to call this function for an internal LOB.

See Also: For more information about FILEs, refer to the description of BFILEs in the Oracle8i Application Developer's Guide - Large Objects (LOBs).

Related Functions

OCILobFileClose(), OCIErrorGet(), OCILobFileExists(), OCILobFileIsOpen()


OCILobFileExists()

Purpose

Tests to see if the FILE exists on the server's operating system.

Syntax

sword OCILobFileExists ( OCISvcCtx        *svchp,
                         OCIError         *errhp,
                         OCILobLocator    *filep,
                         boolean          *flag );

Parameters

svchp (IN)

The OCI service context handle.

errhp (IN/OUT)

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

filep (IN)

Pointer to the FILE locator that refers to the file.

flag (OUT)

Returns TRUE if the FILE exists on the server; FALSE if it does not.

Comments

Checks to see if the FILE exists on the server's file system. It is an error to call this function for an internal LOB.

See Also: For more information about FILEs, refer to the description of BFILEs in the Oracle8i Application Developer's Guide - Large Objects (LOBs).

Related Functions

OCIErrorGet(), OCILobFileClose(), OCILobFileCloseAll(), OCILobFileIsOpen(), OCILobOpen(), OCILobIsOpen()


OCILobFileGetName()

Purpose

Gets the FILE locator's directory alias and file name.

Syntax

sword OCILobFileGetName ( OCIEnv                   *envhp,
                          OCIError                 *errhp, 
                          CONST OCILobLocator      *filep, 
                          text                     *dir_alias,
                          ub2                      *d_length, 
                          text                     *filename, 
                          ub2                      *f_length );

Parameters

envhp (IN/OUT)

OCI environment handle.

errhp (IN/OUT)

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

filep (IN)

FILE locator for which to get the directory alias and file name.

dir_alias (OUT)

Buffer into which the directory alias name is placed. The caller must allocate enough space for the directory alias name. The maximum length for the directory alias is 30 bytes.

d_length (IN/OUT)

Serves the following purposes

filename (OUT)

Buffer into which the file name is placed. The caller must allocate enough space for the file name. The maximum length for the file name is 255 bytes.

f_length (IN/OUT)

Serves the following purposes

Comments

Returns the directory alias and file name associated with this FILE locator. It is an error to call this function for an internal LOB.

See Also: For more information about FILEs, refer to the description of BFILEs in the Oracle8i Application Developer's Guide - Large Objects (LOBs).

Related Functions

OCILobFileSetName(), OCIErrorGet()


OCILobFileIsOpen()

Purpose

Tests to see if the FILE is open

Syntax

sword OCILobFileIsOpen ( OCISvcCtx        *svchp,
                         OCIError         *errhp,
                         OCILobLocator    *filep,
                         boolean          *flag );

Parameters

svchp (IN)

The OCI service context handle.

errhp (IN/OUT)

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

filep (IN)

Pointer to the FILE locator being examined.

flag (OUT)

Returns TRUE if the FILE was opened using this particular locator; FALSE if it was not.

Comments

Checks to see if a file on the server was opened with the filep FILE locator. It is an error to call this function for an internal LOB.

If the input FILE locator was never passed to the OCILobFileOpen() or OCILobOpen() command, the file is considered not to be opened by this locator. However, a different locator may have the file open. Openness is associated with a particular locator.

See Also: For more information about FILEs, refer to the description of BFILEs in the Oracle8i Application Developer's Guide - Large Objects (LOBs).

Related Functions

OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(), OCILobFileExists(), OCILobFileClose(), OCILobFileOpen(), OCILobOpen(), OCILobIsOpen()


OCILobFileOpen()

Purpose

Opens a FILE on the file system of the server for read-only access.

Syntax

sword OCILobFileOpen ( OCISvcCtx            *svchp,
                       OCIError             *errhp,
                       OCILobLocator        *filep,
                       ub1                  mode );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

filep (IN/OUT)

The FILE to open. It is an error if the locator does not refer to a FILE.

mode (IN)

Mode in which to open the file. The only valid mode is OCI_FILE_READONLY.

Comments

Opens a FILE on the file system of the server. The FILE can be opened for read-only access. FILEs may not be written through Oracle. It is an error to call this function for an internal LOB.

This function is only meaningful the first time it is called for a particular FILE locator. Subsequent calls to this function using the same FILE locator have no effect.

See Also: For more information about FILEs, refer to the description of BFILEs in the Oracle8i Application Developer's Guide - Large Objects (LOBs).

Related Functions

OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(), OCILobFileExists(), OCILobFileClose(), OCILobFileIsOpen(), OCILobOpen(), OCILobIsOpen()


OCILobFileSetName()

Purpose

Sets the directory alias and file name in the FILE locator.

Syntax

sword OCILobFileSetName ( OCIEnv             *envhp,
                          OCIError           *errhp,
                          OCILobLocator      **filepp,
                          CONST text         *dir_alias,
                          ub2                d_length, 
                          CONST text         *filename, 
                          ub2                f_length );

Parameters

envhp (IN/OUT)

OCI environment handle.

errhp (IN/OUT)

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

filepp (IN/OUT)

FILE locator for which to set the directory alias and file name.

dir_alias (IN)

Buffer that contains the directory alias name to set in the FILE locator.

d_length (IN)

Length of the input dir_alias parameter.

filename (IN)

Buffer that contains the file name to set in the FILE locator.

f_length (IN)

Length of the input filename parameter.

Comments

It is an error to call this function for an internal LOB.

See Also: For more information about FILEs, refer to the description of BFILEs in the Oracle8i Application Developer's Guide - Large Objects (LOBs).

Related Functions

OCILobFileGetName(), OCIErrorGet()


OCILobFlushBuffer()

Purpose

Flush/write all buffers for this lob to the server.

Syntax

sword OCILobFlushBuffer ( OCISvcCtx       *svchp, 
                          OCIError        *errhp, 
                          OCILobLocator   *locp
                          ub4             flag ); 

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.

locp (IN/OUT)

An internal locator uniquely referencing the LOB.

flag (IN)

When set to OCI_LOB_BUFFER_FREE, the buffer resources for the LOB are freed after the flush. See comments below.

Comments

Flushes to the server, changes made to the buffering subsystem that are associated with the LOB referenced by the input locator. This routine will actually write the data in the buffer to the LOB in the database. LOB buffering must have already been enabled for the input LOB locator.

The flush operation, by default, does not free the buffer resources for reallocation to another buffered LOB operation. However, if you want to free the buffer explicitly, you can set the flag parameter to OCI_LOB_BUFFER_FREE.

If the client application intends to read the buffer value after the flush and knows in advance that the current value in the buffer is the desired value, there is no need to reread the data from the server.

The effects of freeing the buffer are mostly transparent to the user, except that the next access to the same range in the LOB involves a round-trip to the server, and also the cost of acquiring buffer resources and initializing it with the data read from the LOB. This option is intended for client environments that have low on-board memory.

Related Functions

OCILobEnableBuffering(), OCIErrorGet(), OCILobWrite(), OCILobRead(), OCILobDisableBuffering(), OCILobWriteAppend()


OCILobFreeTemporary()

Purpose

Free a temporary LOB

Syntax

sword OCILobFreeTemporary( OCISvcCtx          *svchp,
                           OCIError           *errhp,
                           OCILobLocator      *locp);

Parameters

svchp (IN/OUT)

The OCI service context handle.

errhp (IN/OUT)

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

locp (IN/OUT)

A locator uniquely referencing the LOB to be freed.

Comments

This function frees the contents of the temporary LOB to which this locator points. Note that the locator itself is not freed until OCIDescriptorFree() is called.

This function returns an error if the LOB locator passed in the locp parameter does not point to a temporary LOB, which might be due to any of the following:

Related functions

OCILobCreateTemporary(), OCILobIsTemporary(), OCIErrorGet()


OCILobGetChunkSize()

Purpose

Gets the chunk size of a LOB.

Syntax

sword OCILobGetChunkSize ( OCISvcCtx       *svchp,
                           OCIError        *errhp,
                           OCILobLocator   *locp,
                           ub4             *chunk_size );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

locp (IN/OUT)

The internal LOB for which to get the usable chunk size.

chunk_size (OUT)

The amount of a chunk's space that is used to store the internal LOB value. This is the amount that users should use when reading/writing the LOB value. If possible, users should start their writes at chunk boundaries, such as the beginning of a chunk, and write a chunk at a time.

chunk_size will be returned in terms of bytes for BLOBs and in terms of characters for CLOBs and NCLOBs. For varying width character sets, the value will be the number of Unicode characters that fit in a chunk.

Comments

When creating a table that contains an internal LOB, the user can specify the chunking factor, which can be a multiple of Oracle blocks. This corresponds to the chunk size used by the LOB data layer when accessing/modifying the LOB value. Part of the chunk is used to store system-related information and the rest stores the LOB value. This function returns the amount of space used in the LOB chunk to store the LOB value. Performance will be improved if the application issues read/write requests using a multiple of this chunk size. For writes, there is an added benefit since LOB chunks are versioned and, if all writes are done on a chunk basis, no extra/excess versioning is done nor duplicated. Users could batch up the write until they have enough for a chunk instead of issuing several write calls for the same chunk.

See Also: Refer to "Functions for Improving LOB Read/Write Performance" for more information.

Related Functions

OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobWrite(), OCILobWriteAppend()


OCILobGetLength()

Purpose

Gets the length of a LOB.

Syntax

sword OCILobGetLength ( OCISvcCtx      *svchp,
                        OCIError       *errhp,
                        OCILobLocator  *locp,
                        ub4            *lenp );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

locp (IN)

A LOB locator that uniquely references the LOB. For internal LOBs, this locator must be a locator that was obtained from the server specified by svchp. For FILEs, the locator can be set via OCILobFileSetName(), via a SELECT statement, or via OCIObjectPin.

lenp (OUT)

On output, it is the length of the LOB if the LOB is not NULL. For character LOBs, it is the number of characters, for binary LOBs and BFILEs it is the number of bytes in the LOB.

Comments

Gets the length of a LOB. If the LOB is NULL, the length is undefined. The length of a FILE includes the EOF, if it exists. The length of an empty internal LOB is zero.

Regardless of whether the client-side character set is varying-width, the output length is in characters for CLOBs and NCLOBs, and in bytes for BLOBs and BFILEs.

Note: Any zero-byte or space fillers in the LOB written by previous calls to OCILobErase() or OCILobWrite() are also included in the length count.

Related Functions

OCIErrorGet(), OCILobFileSetName(), OCILobRead(), OCILobWrite(), OCILobCopy(), OCILobAppend(), OCILobLoadFromFile(), OCILobWriteAppend()


OCILobIsEqual()

Purpose

Compares two LOB/FILE locators for equality.

Syntax

sword OCILobIsEqual ( OCIEnv                  *envhp,
                      CONST OCILobLocator     *x,
                      CONST OCILobLocator     *y,
                      boolean                 *is_equal );

Parameters

envhp (IN)

The OCI environment handle.

x (IN)

LOB locator to compare.

y (IN)

LOB locator to compare.

is_equal (OUT)

TRUE, if the LOB locators are equal; FALSE if they are not.

Comments

Compares the given LOB/FILE locators for equality. Two LOB/FILE locators are equal if and only if they both refer to the same LOB/FILE value.

Two NULL locators are considered not equal by this function.

Related Functions

OCILobAssign(), OCILobLocatorIsInit()


OCILobIsOpen()

Purpose

Tests whether a LOB/FILE is open.

Syntax

sword OCILobIsOpen ( OCISvcCtx        *svchp,
                     OCIError         *errhp, 
                     OCILobLocator    *locp, 
                     boolean          *flag );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

An error handle which can be passed to OCIErrorGet() for diagnostic information in the event of an error.

locp (IN)

Pointer to the LOB locator being examined. The locator can refer to an internal or external LOB.

flag (OUT)

Returns TRUE if the internal LOB is open or if the BFILE was opened using the input locator. Returns FALSE if it was not.

Comments

Checks to see if the internal LOB is open or if the BFILE was already opened using the input locator.

For BFILES

If the input BFILE locator was never passed to OCILobOpen() or OCILobFileOpen(), the BFILE is considered not to be opened by this BFILE locator. However, a different BFILE locator may have opened the BFILE. More than one open can be performed on the same BFILE using different locators. In other words, openness is associated with a specific locator for BFILEs.

For internal LOBs

Openness is associated with the LOB, not with the locator. If locator1 opened the LOB then locator2 also sees the LOB as open.

For internal LOBs, this call requires a server round-trip because it checks the state on the server to see if the LOB is indeed open. For external LOBs (BFILEs), this call also requires a round-trip because the actual operating system file on the server side must be checked to see if it is actually open.

See Also: Refer to "Functions for Opening and Closing LOBs" for more information.

Related Functions

OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(), OCILobFileExists(), OCILobFileClose(), OCILobFileIsOpen(), OCILobFileOpen(), OCILobOpen()


OCILobIsTemporary()

Purpose

Tests if a locator points to a temporary LOB

Syntax

sword OCILobIsTemporary(OCIEnv            *envhp,
                        OCIError          *errhp,
                        OCILobLocator     *locp,
                        boolean           *is_temporary);

Parameters

envhp (IN)

The OCI environment handle.

errhp (IN/OUT)

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

locp (IN)

The locator to test.

is_temporary (OUT)

Returns TRUE if the LOB locator points to a temporary LOB; FALSE if it does not.

Comments

This function tests a locator to determine if it points to a temporary LOB. If so, is_temporary is set to TRUE. If not, is_temporary is set to FALSE.

Related Functions

OCILobCreateTemporary(), OCILobFreeTemporary()


OCILobLoadFromFile()

Purpose

Load/copy all or a portion of the file into an internal LOB.

Syntax

sword OCILobLoadFromFile ( OCISvcCtx        *svchp, 
                           OCIError         *errhp, 
                           OCILobLocator    *dst_locp, 
                           OCILobLocator    *src_locp, 
                           ub4              amount, 
                           ub4              dst_offset, 
                           ub4              src_offset ); 

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

dst_locp (IN/OUT)

A locator uniquely referencing the destination internal LOB which may be of type BLOB, CLOB, or NCLOB.

src_locp (IN/OUT)

A locator uniquely referencing the source FILE.

amount (IN)

The number of bytes to be loaded.

dst_offset (IN)

This is the absolute offset for the destination LOB. For character LOBs it is the number of characters from the beginning of the LOB at which to begin writing. For binary LOBs it is the number of bytes from the beginning of the LOB from which to begin reading. The offset starts at 1.

src_offset (IN)

This is the absolute offset for the source FILE. It is the number of bytes from the beginning of the FILE. The offset starts at 1.

Comments

Loads/copies a portion or all of a FILE value into an internal LOB as specified. The data is copied from the source FILE to the destination internal LOB (BLOB/CLOB). No character set conversions are performed when copying the FILE data to a CLOB/NCLOB. Also, when binary data is loaded into a BLOB, no character set conversions are performed. Therefore, the FILE data must already be in the same character set as the LOB in the database. No error checking is performed to verify this.

The source (src_locp) and the destination (dst_locp) LOBs must already exist. If the data already exists at the destination's start position, it is overwritten with the source data. If the destination's start position is beyond the end of the current data, zero-byte fillers (for BLOBs) or spaces (for CLOBs) are written into the destination LOB from the end of the data to the beginning of the newly written data from the source. The destination LOB is extended to accommodate the newly written data if it extends beyond the current length of the destination LOB.

It is an error to extend the destination LOB beyond the maximum length allowed (4 gigabytes) or to try to copy from a NULL FILE.

Related Functions

OCIErrorGet(), OCILobAppend(), OCILobWrite(), OCILobTrim(), OCILobCopy(), OCILobGetLength(), OCILobWriteAppend()


OCILobLocatorAssign()

Purpose

Assigns one LOB/FILE locator to another.

Syntax

sword OCILobLocatorAssign ( OCISvcCtx            *svchp,
                            OCIError             *errhp,
                            CONST OCILobLocator  *src_locp,
                            OCILobLocator         **dst_locpp );

Parameters

svchp (IN/OUT)

The OCI service context handle.

errhp (IN/OUT)

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

src_locp (IN)

The LOB/BFILE locator to copy from.

dst_locpp (IN/OUT)

The LOB/FILE locator to copy to. The caller must allocate space for the OCILobLocator by calling OCIDescriptorAlloc().

Comments

This call assigns the source locator to the destination locator. After the assignment, both locators refer to the same LOB data. For internal LOBs, the source locator's LOB data gets copied to the destination locator's LOB data only when the destination locator gets stored in the table. Therefore, issuing a flush of the object containing the destination locator copies the LOB data. For FILEs only the locator that refers to the OS file is copied to the table; the OS file is not copied.

Note that this call is similar to OCILobAssign() but OCILobLocatorAssign() takes an OCI service handle pointer instead of an OCI environment handle pointer. Also, OCILobLocatorAssign() can be used for temporary LOBs and OCILobAssign() cannot be used for temporary LOBs.

Note: If the OCILobLocatorAssign() function fails, the target locator will not be restored to its previous state. The target locator should not be used in subsequent operations unless it is reinitialized.

If the destination locator is for a temporary LOB, the destination temporary LOB is freed before assigning the source LOB locator to it. If the source LOB locator refers to a temporary LOB, the source temporary LOB is deep copied and a destination locator is created to refer to the new deep copy of the temporary LOB. To avoid this deep copy, the user should use the equal sign to ensure that two LOB locator pointers refer to the same LOB locator.

Related Functions

OCIErrorGet(), OCILobAssign(), OCILobIsEqual(), OCILobLocatorIsInit()


OCILobLocatorIsInit()

Purpose

Tests to see if a given LOB/FILE locator is initialized.

Syntax

sword OCILobLocatorIsInit ( OCIEnv               *envhp,
                            OCIError             *errhp,
                            CONST OCILobLocator  *locp,
                            boolean              *is_initialized );

Parameters

envhp (IN/OUT)

OCI environment handle.

errhp (IN/OUT)

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

locp (IN)

The LOB/FILE locator being tested

is_initialized (OUT)

Returns TRUE if the given LOB/FILE locator is initialized; FALSE if it is not.

Comments

Tests to see if a given LOB/FILE locator is initialized.

Internal LOB locators can be initialized by one of the following methods:

FILE locators can be initialized by one of the following methods:

Related Functions

OCIErrorGet(), OCILobIsEqual()


OCILobOpen()

Purpose

Opens a LOB, internal or external, in the indicated mode.

Syntax

sword OCILobOpen ( OCISvcCtx        *svchp,
                   OCIError         *errhp, 
                   OCILobLocator    *locp, 
                   ub1              mode );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

locp (IN/OUT)

The LOB to open. The locator can refer to an internal or external LOB.

mode (IN)

The mode in which to open the LOB/BFILE. In Oracle8i, valid modes for LOBs are OCI_LOB_READONLY and OCI_LOB_READWRITE. Note that OCI_FILE_READONLY exists in Oracle8 as input to OCILobFileOpen(). OCI_FILE_READONLY can be used with OCILobOpen() if the input locator is for a BFILE.

Comments

It is an error to open the same LOB twice. BFILEs cannot be opened in read-write mode. Note that if the LOB/BFILE was opened in read-only mode and the user tries to write to the LOB/BFILE, an error will be returned.

Opening a LOB requires a round-trip to the server for both internal and external LOBs. For internal LOBs, the open will trigger other code that relies on the open call. For external LOBs (BFILEs), open requires a round-trip because the actual operating system file on the server side is being opened.

See Also: Refer to "Functions for Opening and Closing LOBs" for more information.

Related Functions

OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(), OCILobFileExists(), OCILobFileClose(), OCILobFileIsOpen(), OCILobFileOpen(), OCILobIsOpen()


OCILobRead()

Purpose

Reads a portion of a LOB/FILE, as specified by the call, into a buffer.

Syntax

sword OCILobRead ( OCISvcCtx          *svchp,
                   OCIError           *errhp,
                   OCILobLocator      *locp,
                   ub4                *amtp,
                   ub4                offset,
                   dvoid              *bufp,
                   ub4                bufl,
                   dvoid              *ctxp, 
                   OCICallbackLobRead (cbfp)
                                      ( dvoid         *ctxp,
                                        CONST dvoid   *bufp,
                                        ub4           len,
                                        ub1           piece )
                   ub2                csid,
                   ub1                csfrm );

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.

locp (IN)

A LOB/FILE locator that uniquely references the LOB/FILE. This locator must be a locator that was obtained from the server specified by svchp.

amtp (IN/OUT)

On input, the number of characters (for CLOBs or NCLOBs) or bytes (for BLOBs and BFILEs) to be read. On output, the actual number of bytes or characters read.

*amtp is the total amount of data read if:

*amtp is the length of the last piece read if the data is read in streamed mode using polling.

If the amount of bytes to be read is larger than the buffer length it is assumed that the LOB is being read in a streamed mode from the input offset until the end of the LOB, or until the specified number of bytes have been read, whichever comes first. On input if this value is 0, then the data shall be read in streamed mode from the input offset until the end of the LOB.

The streamed mode (implemented with either polling or callbacks) reads the LOB value sequentially from the input offset.

If the data is read in pieces, *amtp always contains the length of the piece just read.

If a callback function is defined, then this callback function will be invoked each time bufl bytes are read off the pipe. Each piece will be written into bufp.

If the callback function is not defined, then the OCI_NEED_DATA error code will be returned. The application must call OCILobRead() over and over again to read more pieces of the LOB until the OCI_NEED_DATA error code is not returned. The buffer pointer and the length can be different in each call if the pieces are being read into different sizes and locations.

If the client-side character set is varying-width, then the input amount is in characters and the output amount is in bytes for CLOBs and NCLOBs. The input amount refers to the number of characters to read from the server-side CLOB/NCLOB. The output amount indicates how many bytes were read into the buffer bufp.

offset (IN)

On input, this is the absolute offset from the beginning of the LOB value. For character LOBs (CLOBs, NCLOBs) it is the number of characters from the beginning of the LOB, for binary LOBs/FILEs it is the number of bytes. The first position is 1.

bufp (IN/OUT)

The pointer to a buffer into which the piece will be read. The length of the allocated memory is assumed to be bufl.

bufl (IN)

The length of the buffer in octets. This value will differ from the amtp value for CLOBs and for NCLOBs (csfrm=SQLCS_NCHAR) if the amtp parameter is specified in terms of characters, while the bufl parameter is specified in terms of bytes.

ctxp (IN)

The context pointer for the callback function. Can be NULL.

cbfp (IN)

A callback that may be registered to be called for each piece. If this is NULL, then OCI_NEED_DATA will be returned for each piece.

The callback function must return OCI_CONTINUE for the read to continue. If any other error code is returned, the LOB read is aborted.

ctxp (IN)

The context for the callback function. Can be NULL.

bufp (IN/OUT)

A buffer pointer for the piece.

len (IN)

The length in bytes of the current piece in bufp.

piece (IN)

Which piece: OCI_FIRST_PIECE, OCI_NEXT_PIECE or OCI_LAST_PIECE.

csid (IN)

The character set ID of the buffer data.

csfrm (IN)

The character set form of the buffer data. The csfrm parameter must be consistent with the type of the LOB. In other words, if the LOB is a CLOB, then csfrm should not indicate NCHAR, and if the LOB is an NCLOB, then csfrm should indicate NCHAR.

Comments

Reads a portion of a LOB/FILE as specified by the call into a buffer. It is an error to try to read from a NULL LOB/FILE.

Note: When reading or writing LOBs, the character set form (csfrm) specified should match the form of the locator itself.

For FILEs, the operating system file must already exist on the server, and it must have been opened via OCILobFileOpen() or OCILobOpen() using the input locator. Oracle must have permission to read the OS file, and the user must have read permission on the directory object.

When using the polling mode for OCILobRead(), the first call needs to specify values for offset and amtp, but on subsequent polling calls to OCILobRead(), the user need not specify these values.

If the LOB is a BLOB, the csid and csfrm parameters are ignored.

Note: To abort an OCILobRead() operation and free the statement handle, use the OCIBreak() call.

The following apply to client-side varying-width character sets for CLOBs and NCLOBs:

The following applies to client-side fixed-width character sets and server-side varying-width character sets for CLOBs and NCLOBs:

To read data in UCS-2 format, set the csid parameter to OCI_UCS2ID. If the csid parameter is set, it overrides the NLS_LANG environment variable. For additional information on UCS-2 (unicode) format, see "Fixed Width Unicode Support".

See Also: For more information about FILEs, refer to the description of BFILEs in the Oracle8i Application Developer's Guide - Large Objects (LOBs).

For a code sample showing the use of LOB reads and writes, see the demonstration programs included with your Oracle installation. For additional information, refer to Appendix B, "OCI Demonstration Programs".

For general information about piecewise OCI operations, refer to "Run Time Data Allocation and Piecewise Operations".

Related Functions

OCIErrorGet(), OCILobWrite(), OCILobFileSetName(), OCILobWriteAppend()


OCILobTrim()

Purpose

Trims/truncates the LOB value to a shorter length.

Syntax

sword OCILobTrim ( OCISvcCtx       *svchp,
                   OCIError        *errhp,
                   OCILobLocator   *locp,
                   ub4             newlen );

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

locp (IN/OUT)

An internal LOB locator that uniquely references the LOB. This locator must be a locator that was obtained from the server specified by svchp.

newlen (IN)

The new length of the LOB value, which must be less than or equal to the current length.

Comments

This function trims the LOB data to a specified shorter length. The function returns an error if newlen is greater than the current LOB length. This function is valid only for internal LOBs. FILEs are not allowed.

Related Functions

OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobErase(), OCILobWrite(), OCILobWriteAppend()


OCILobWrite()

Purpose

Writes a buffer into a LOB

Syntax

sword OCILobWrite ( OCISvcCtx       *svchp,
                    OCIError        *errhp,
                    OCILobLocator   *locp,
                    ub4             *amtp,
                    ub4             offset,
                    dvoid           *bufp, 
                    ub4             buflen,
                    ub1             piece,
                    dvoid           *ctxp, 
                    OCICallbackLobWrite      (cbfp)
                                    (/*_
                                    dvoid    *ctxp,
                                    dvoid    *bufp,
                                    ub4      *lenp,
                                    ub1      *piecep */) 
                    ub2             csid,
                    ub1             csfrm );

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.

locp (IN/OUT)

An internal LOB locator that uniquely references the LOB. This locator must be a locator that was obtained from the server specified by svchp.

amtp (IN/OUT)

On input, takes the number of characters for CLOBs and NCLOBs or bytes for BLOBs to be written. On output, returns the actual number of bytes or characters written. This should always be a non-NULL pointer. If you want to specify write-until-end-of-file, then you must declare a variable, set it equal to zero, and pass its address for this parameter.

If the amount is specified on input, and the data is written in pieces, *amtp will contain the total length of the pieces written at the end of the call (last piece written) and is undefined in between. Note that it is different from the piecewise read case. An error is returned if that amount is not sent to the server.

If amtp is zero, then streaming mode is assumed, and data is written until the user specifies OCI_LAST_PIECE.

If the client-side character set is varying-width, then the input amount is in bytes and the output amount is in characters for CLOBs and NCLOBs. The input amount refers to the number of bytes of data that the user wants to write into the LOB and not the number of bytes in the bufp, which is specified by buflen. In the case where data is written in pieces, the amount of bytes to write may be larger than the buflen. The output amount refers to the number of characters written into the server-side CLOB/NCLOB.

offset (IN)

On input, it is the absolute offset from the beginning of the LOB value. For character LOBs it is the number of characters from the beginning of the LOB, for binary LOBs it is the number of bytes. The first position is 1.

bufp (IN)

The pointer to a buffer from which the piece will be written. The length of the data in the buffer is assumed to be the value passed in buflen. Even if the data is being written in pieces using the polling method, bufp must contain the first piece of the LOB when this call is invoked. If a callback is provided, bufp must not be used to provide data or an error will result.

buflen (IN)

The length, in bytes, of the data in the buffer. This value will differ from the amtp value for CLOBs and NCLOBs if the amtp parameter is specified in terms of characters, while the buflen parameter is specified in terms of bytes.

Note: This parameter assumes an 8-bit byte. If your platform uses a longer byte, you must adjust the value of buflen accordingly.

piece (IN)

Which piece of the buffer is being written. The default value for this parameter is OCI_ONE_PIECE, indicating the buffer will be written in a single piece.

The following other values are also possible for piecewise or callback mode: OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.

ctxp (IN)

The context for the callback function. Can be NULL.

cbfp (IN)

A callback that may be registered to be called for each piece in a piecewise write. If this is NULL, the standard polling method will be used.

The callback function must return OCI_CONTINUE for the write to continue. If any other error code is returned, the LOB write is aborted. The callback takes the following parameters:

ctxp (IN)

The context for the callback function. Can be NULL.

bufp (IN/OUT)

A buffer pointer for the piece. This is the same as the bufp passed as an input to the OCILobWrite() routine.

lenp (IN/OUT)

The length, in bytes, of the data in the buffer (IN), and the length in bytes of current piece in bufp (OUT).

piecep (OUT)

Which piece: OCI_NEXT_PIECE or OCI_LAST_PIECE.

csid (IN)

The character set ID of the buffer data.

csfrm (IN)

The character set form of the buffer data. The csfrm parameter must be consistent with the type of the LOB. In other words, if the LOB is a CLOB, then csfrm should not indicate NCHAR, and if the LOB is an NCLOB, then csfrm should indicate NCHAR.

Comments

Writes a buffer into an internal LOB as specified. If LOB data already exists it is overwritten with the data stored in the buffer. The buffer can be written to the LOB in a single piece with this call, or it can be provided piecewise using callbacks or a standard polling method.

Note: When reading or writing LOBs, the character set form (csfrm) specified should match the form of the locator itself.

When using the polling mode for OCILobWrite(), the first call needs to specify values for offset and amtp, but on subsequent polling calls to OCILobWrite(), the user need not specify these values.

If the value of the piece parameter is OCI_FIRST_PIECE, data may need to be provided through callbacks or polling.

If a callback function is defined in the cbfp parameter, then this callback function will be invoked to get the next piece after a piece is written to the pipe. Each piece will be written from bufp. If no callback function is defined, then OCILobWrite() returns the OCI_NEED_DATA error code. The application must call OCILobWrite() again to write more pieces of the LOB. In this mode, the buffer pointer and the length can be different in each call if the pieces are of different sizes and from different locations.

A piece value of OCI_LAST_PIECE terminates the piecewise write, regardless of whether the polling or callback method is used.

If the amount of data passed to Oracle (through either input mechanism) is less than the amount specified by the amtp parameter, an ORA-22993 error is returned.

This function is valid for internal LOBs only. FILEs are not allowed, since they are read-only. If the LOB is a BLOB, the csid and csfrm parameters are ignored.

If the client-side character set is varying-width, then the input amount is in bytes and the output amount is in characters for CLOBs and NCLOBs. The input amount refers to the number of bytes of data that the user wants to write into the LOB and not the number of bytes in the bufp, which is specified by buflen. In the case where data is written in pieces, the amount of bytes to write may be larger than the buflen. The output amount refers to the number of characters written into the server-side CLOB/NCLOB.

To write data in UCS-2 format, set the csid parameter to OCI_UCS2ID. If the csid parameter is set, it overrides the NLS_LANG environment variable. For additional information on UCS-2 (unicode) format, see "Fixed Width Unicode Support".

See Also: For a code sample showing the use of LOB reads and writes, see the demonstration programs included with your Oracle installation. For additional information, refer to Appendix B, "OCI Demonstration Programs".

For general information about piecewise OCI operations, refer to "Run Time Data Allocation and Piecewise Operations".

Related Functions

OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobWriteAppend()


OCILobWriteAppend()

Purpose

Writes data starting at the end of a LOB.

Syntax

sword   OCILobWriteAppend ( OCISvcCtx *svchp,
                            OCIError *errhp,
                            OCILobLocator *locp,
                            ub4 *amtp,
                            dvoid *bufp, 
                            ub4 buflen, 
                            ub1 piece, 
                            dvoid *ctxp, 
                            OCICallbackLobWrite     (cbfp)
                                         (/*_
                                           dvoid    *ctxp,
                                           dvoid    *bufp,
                                           ub4      *lenp,
                                           ub1      *piecep */) 
                            ub2 csid, 
                            ub1 csfrm);

Parameters

svchp (IN)

The service context handle.

errhp (IN/OUT)

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

locp (IN/OUT)

An internal LOB locator that uniquely references a LOB.

amtp (IN/OUT)

On input, takes the number of characters for CLOBs/NCLOBs or bytes for BLOBs to be written. On output, returns the actual number of bytes or characters written. If the amount specified on input, and the data is written in pieces, *amtp will contain the total length of the pieces written at the end of the call (last piece written) and is undefined in between. (Note it is different from the piecewise read case). An error is returned if that amount is not sent to the server. If amtp is zero, then streaming mode is assumed, and data is written until the user specifies OCI_LAST_PIECE.

If the client-side character set is varying-width, then the input amount is in bytes, not characters, for CLOBs/NCLOBs.

bufp (IN)

The pointer to a buffer from which the piece will be written. The length of the data in the buffer is assumed to be the value passed in buflen. Even if the data is being written in pieces, bufp must contain the first piece of the LOB when this call is invoked. If a callback is provided, bufp must not be used to provide data or an error will result.

buflen (IN)

The length, in bytes, of the data in the buffer. Note that this parameter assumes an 8-bit byte. If your platform uses a longer byte, the value of buflen must be adjusted accordingly.

piece (IN)

Which piece of the buffer is being written. The default value for this parameter is OCI_ONE_PIECE, indicating the buffer will be written in a single piece. The following other values are also possible for piecewise or callback mode: OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.

ctxp (IN)

The context for the call back function. Can be NULL.

cbfp (IN)

A callback that may be registered to be called for each piece in a piecewise write. If this is NULL, the standard polling method will be used. The callback function must return OCI_CONTINUE for the write to continue. If any other error code is returned, the LOB write is aborted. The callback takes the following parameters:

ctxp (IN)

The context for the callback function. Can be NULL.

bufp (IN/OUT)

A buffer pointer for the piece.

lenp (IN/OUT)

The length, in bytes, of the data in the buffer (IN), and the length in bytes of current piece in bufp (OUT).

piecep (OUT)

Which piece: OCI_NEXT_PIECE or OCI_LAST_PIECE.

csid (IN)

The character set ID of the buffer data.

csfrm (IN)

The character set form of the buffer data.

Comments

The buffer can be written to the LOB in a single piece with this call, or it can be provided piecewise using callbacks or a standard polling method. If the value of the piece parameter is OCI_FIRST_PIECE, data must be provided through callbacks or polling. If a callback function is defined in the cbfp parameter, then this callback function will be invoked to get the next piece after a piece is written to the pipe. Each piece will be written from bufp. If no callback function is defined, then OCILobWriteAppend() returns the OCI_NEED_DATA error code.

The application must call OCILobWriteAppend() again to write more pieces of the LOB. In this mode, the buffer pointer and the length can be different in each call if the pieces are of different sizes and from different locations. A piece value of OCI_LAST_PIECE terminates the piecewise write.

OCILobWriteAppend() is not supported if LOB buffering is enabled.

If the LOB is a BLOB, the csid and csfrm parameters are ignored.

If the client-side character set is varying-width, then the input amount is in bytes, not characters, for CLOBs/NCLOBs.

See Also: Refer to "Functions for Improving LOB Read/Write Performance" for more information.

Related Functions

OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(), OCILobWrite()

Statement Functions

This section describes the statement functions.

Table 15-7 OCI Quick Reference
Function  Purpose 

OCIStmtExecute()  

Send statements to server for execution  

OCIStmtFetch()  

Fetch rows from a query  

OCIStmtGetPieceInfo()  

Get piece information for piecewise operations  

OCIStmtPrepare()  

Establish an application request  

OCIStmtSetPieceInfo()  

Set piece information for piecewise operations  


OCIStmtExecute()

Purpose

This call associates an application request with a server.

Syntax

sword OCIStmtExecute ( OCISvcCtx           *svchp,
                       OCIStmt             *stmtp,
                       OCIError            *errhp,
                       ub4                 iters,
                       ub4                 rowoff,
                       CONST OCISnapshot   *snap_in,
                       OCISnapshot         *snap_out,
                       ub4                 mode );

Parameters

svchp (IN/OUT)

Service context handle.

stmtp (IN/OUT)

An statement handle. It defines the statement and the associated data to be executed at the server. It is invalid to pass in a statement handle that has bind of data types only supported in release 8 when svchp points to an Oracle7 server.

errhp (IN/OUT)

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

iters (IN)

For non-SELECT statements, the number of times this statement is executed.

For SELECT statements, if iters is non-zero, then defines must have been done for the statement handle. The execution fetches iters rows into these predefined buffers and prefetches more rows depending upon the prefetch row count. If you do not know how many rows the SELECT statement will retrieve, set iters to zero.

This function returns an error if iters=0 for non-SELECT statements.

rowoff (IN)

The starting index from which the data in an array bind is relevant for this multiple row execution.

snap_in (IN)

This parameter is optional. if supplied, must point to a snapshot descriptor of type OCI_DTYPE_SNAP. The contents of this descriptor must be obtained from the snap_out parameter of a previous call. The descriptor is ignored if the SQL is not a SELECT. This facility allows multiple service contexts to ORACLE to see the same consistent snapshot of the database's committed data. However, uncommitted data in one context is not visible to another context even using the same snapshot.

snap_out (OUT)

This parameter optional. if supplied, must point to a descriptor of type OCI_DTYPE_SNAP. This descriptor is filled in with an opaque representation which is the current ORACLE "system change number" suitable as a snap_in input to a subsequent call to OCIStmtExecute(). This descriptor should not be used longer than necessary in order to avoid "snapshot too old" errors.

mode (IN)

The modes are:

The modes are not mutually exclusive and can be used together.

Comments

This function is used to execute a prepared SQL statement. Using an execute call, the application associates a request with a server.

If a SELECT statement is executed, the description of the select-list is available implicitly as a response. This description is buffered on the client side for describes, fetches and define type conversions. Hence it is optimal to describe a select list only after an execute. See "Describing Select-List Items" for more information.

Also for SELECT statements, some results are available implicitly. Rows will be received and buffered at the end of the execute. For queries with small row count, a prefetch causes memory to be released in the server if the end of fetch is reached, an optimization that may result in memory usage reduction. Set attribute call has been defined to set the number of rows to be prefetched per result set.

For SELECT statements, at the end of the execute, the statement handle implicitly maintains a reference to the service context on which it is executed. It is the user's responsibility to maintain the integrity of the service context. The implicit reference is maintained until the statement handle is freed or the fetch is cancelled or an end of fetch condition is reached.

Note: If output variables are defined for a SELECT statement before a call to OCIStmtExecute(), the number of rows specified by iters will be fetched directly into the defined output buffers and additional rows equivalent to the prefetch count will be prefetched. If there are no additional rows, then the fetch is complete without calling OCIStmtFetch().

Related Functions

OCIStmtPrepare()


OCIStmtFetch()

Purpose

Fetches rows from a query.

Syntax

sword OCIStmtFetch ( OCIStmt     *stmtp,
                     OCIError    *errhp, 
                     ub4         nrows,
                     ub2         orientation,
                     ub4         mode );

Parameters

stmtp (IN)

A statement (application request) handle.

errhp (IN)

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

nrows (IN)

Number of rows to be fetched from the current position.

orientation (IN)

For release 8.0, the only acceptable value is OCI_FETCH_NEXT, which is also the default value.

mode (IN)

Pass as OCI_DEFAULT.

Comments

The fetch call is a local call, if prefetched rows suffice. However, this is transparent to the application.

If LOB columns are being read, LOB locators are fetched for subsequent LOB operations to be performed on these locators. Prefetching is turned off if LONG columns are involved.

This function can return OCI_SUCCESS_WITH_INFO if the data is truncated or EOF is reached. If you call OCIStmtFetch() with the nrows parameter set to zero, this cancels the cursor.

Related Functions

OCIStmtExecute()


OCIStmtGetPieceInfo()

Purpose

Returns piece information for a piecewise operation.

Syntax

sword OCIStmtGetPieceInfo( CONST OCIStmt  *stmtp,
                           OCIError       *errhp,
                           dvoid          **hndlpp,
                           ub4            *typep,
                           ub1            *in_outp,
                           ub4            *iterp, 
                           ub4            *idxp,
                           ub1            *piecep );

Parameters

stmtp (IN)

The statement when executed returned OCI_NEED_DATA.

errhp (OUT)

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

hndlpp (OUT)

Returns a pointer to the bind or define handle of the bind or define whose runtime data is required or is being provided.

typep (OUT)

The type of the handle pointed to by hndlpp: OCI_HTYPE_BIND (for a bind handle) or OCI_HTYPE_DEFINE (for a define handle).

in_outp (OUT)

Returns OCI_PARAM_IN if the data is required for an IN bind value. Returns OCI_PARAM_OUT if the data is available as an OUT bind variable or a define position value.

iterp (OUT)

Returns the row number of a multiple row operation.

idxp (OUT)

The index of an array element of a PL/SQL array bind operation.

piecep (OUT)

Returns one of the following defined values OCI_ONE_PIECE, OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.

Comments

When an execute/fetch call returns OCI_NEED_DATA to get/return a dynamic bind/define value or piece, OCIStmtGetPieceInfo() returns the relevant information: bind/define handle, iteration, index number and which piece.

See the section "Run Time Data Allocation and Piecewise Operations" for more information about using OCIStmtGetPieceInfo().

Related Functions

OCIAttrGet(), OCIAttrSet(), OCIStmtExecute(), OCIStmtFetch(), OCIStmtSetPieceInfo()


OCIStmtPrepare()

Purpose

This call prepares a SQL or PL/SQL statement for execution.

Syntax

sword OCIStmtPrepare ( OCIStmt       *stmtp,
                       OCIError      *errhp,
                       CONST text    *stmt, 
                       ub4           stmt_len,
                       ub4           language,
                       ub4           mode );

Parameters

stmtp (IN)

A statement handle.

errhp (IN)

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

stmt (IN)

SQL or PL/SQL statement to be executed. Must be a null-terminated string. The pointer to the text of the statement must be available as long as the statement is executed, or data is fetched from it.

stmt_len (IN)

Length of the statement. Must not be zero.

language (IN)

Specifies V7, or native syntax. Possible values are:

mode (IN)

The possible values are:

Comments

An OCI application uses this call to prepare a SQL or PL/SQL statement for execution. The OCIStmtPrepare() call defines an application request.

This is a purely local call. Data values for this statement initialized in subsequent bind calls will be stored in a bind handle which will hang off this statement handle.

This call does not create an association between this statement handle and any particular server.

See the section "Preparing Statements" for more information about using this call.

Related Functions

OCIAttrGet(), OCIStmtExecute()


OCIStmtSetPieceInfo()

Purpose

Sets piece information for a piecewise operation.

Syntax

sword OCIStmtSetPieceInfo ( dvoid             *hndlp,
                            ub4               type,
                            OCIError          *errhp,
                            CONST dvoid       *bufp,
                            ub4               *alenp, 
                            ub1               piece,
                            CONST dvoid       *indp, 
                            ub2               *rcodep ); 

Parameters

hndlp (IN/OUT)

The bind/define handle.

type (IN)

Type of the handle.

errhp (OUT)

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

bufp (IN/OUT)

A pointer to a storage containing the data value or the piece when it is an IN bind variable, otherwise bufp is a pointer to storage for getting a piece or a value for OUT binds and define variables. For named data types or REFs, a pointer to the object or REF is returned.

alenp (IN/OUT)

The length of the piece or the value.

piece (IN)

The piece parameter. Valid values:

This parameter is used for IN bind variables only.

indp (IN/OUT)

Indicator. A pointer to a sb2 value or pointer to an indicator structure for named data types (SQLT_NTY) and REFs (SQLT_REF), i.e., *indp is either an sb2 or a
dvoid * depending upon the data type.

rcodep (IN/OUT)

Return code.

Comments

When an execute call returns OCI_NEED_DATA to get a dynamic IN/OUT bind value or piece, OCIStmtSetPieceInfo() sets the piece information: the buffer, the length, which piece is currently being processed, the indicator, and the return code for this column.

For more information about using OCIStmtSetPieceInfo() see the section "Run Time Data Allocation and Piecewise Operations".

Related Functions

OCIAttrGet(), OCIAttrSet(), OCIStmtExecute(), OCIStmtFetch(), OCIStmtGetPieceInfo()

Thread Management Functions

This section describes the thread management functions.

Table 15-8 OCI Quick Reference
Function  Purpose 

OCIThreadClose()  

Closes a thread handle  

OCIThreadCreate()  

Creates a new thread  

OCIThreadHandleGet()  

Retrieves the OCIThreadHandle of the thread in which it is called  

OCIThreadHndDestroy()  

Destroys and deallocates the thread handle  

OCIThreadHndInit()  

Allocates and initializes the thread handle  

OCIThreadIdDestroy()  

Destroys and deallocates a thread id  

OCIThreadIdGet()  

Retrieves the OCIThreadId of the thread in which it is called  

OCIThreadIdInit()  

Allocate and initialize the thread id  

OCIThreadIdNull()  

Determines whether or not a given OCIThreadId is the NULL thread ID  

OCIThreadIdSame()  

Determines whether or not two OCIThreadIds represent the same thread  

OCIThreadIdSet()  

Sets one OCIThreadId to another  

OCIThreadIdSetNull()  

Sets the NULL thread ID to a given OCIThreadId  

OCIThreadInit()  

Initializes OCIThread context  

OCIThreadIsMulti()  

Tells the caller whether the application is running in a multi-threaded environment or a single-threaded environment  

OCIThreadJoin()  

Allows the calling thread to join with another thread  

OCIThreadKeyDestroy()  

Destroy and deallocate the key pointed to by key  

OCIThreadKeyGet()  

Gets the calling threads current value for a key  

OCIThreadKeyInit()  

Creates a key  

OCIThreadKeySet()  

Sets the calling threads value for a key  

OCIThreadMutexAcquire()  

Acquires a mutex for the thread in which it is called  

OCIThreadMutexDestroy()  

Destroys and deallocate a mutex  

OCIThreadMutexInit()  

Allocates and initializes a mutex  

OCIThreadMutexRelease()  

Releases a mutex  

OCIThreadProcessInit()  

Performs OCIThread process initialization  

OCIThreadTerm()  

Releases the OCIThread context  


OCIThreadClose()

Purpose

Closes a thread handle.

Syntax

sword OCIThreadClose ( dvoid            *hndl, 
                       OCIError         *err, 
                       OCIThreadHandle  *tHnd );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

tHnd (IN/OUT)

The OCIThread thread handle to close.

Comments

tHnd should be initialized by OCIThreadHndInit(). Both thread handle and the thread ID that was returned by the same call to OCIThreadCreate() are invalid after the call to OCIThreadClose().

Related Functions

OCIThreadCreate()


OCIThreadCreate()

Purpose

Creates a new thread.

Syntax

sword OCIThreadCreate ( dvoid            *hndl, 
                        OCIError         *err, 
                        void (*start)    (dvoid
                        dvoid            *arg, 
                        OCIThreadId      *tid, 
                        OCIThreadHandle  *tHnd );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

start (IN)

The function in which the new thread should begin execution.

arg (IN)

The argument to give the function pointed to by start.

tid (IN/OUT)

If not NULL, gets the ID for the new thread.

tHnd (IN/OUT)

If not NULL, gets the handle for the new thread.

Comments

The new thread starts by executing a call to the function pointed to by start with the argument given by arg. When that function returns, the new thread will terminate. The function should not return a value and should accept one parameter, a dvoid. The call to OCIThreadCreate() must be matched by a call to OCIThreadClose() if and only if tHnd is non-NULL.

If tHnd is NULL, a thread ID placed in *tid will not be valid in the calling thread because the timing of the spawned threads termination is unknown.

tid should be initialized by OCIThreadIdInit() and tHnd should be initialized by OCIThreadHndInit().

Related Functions

OCIThreadClose(), OCIThreadIdInit(), OCIThreadHndInit()


OCIThreadHandleGet()

Purpose

Retrieves the OCIThreadHandle of the thread in which it is called.

Syntax

sword OCIThreadHandleGet ( dvoid            *hndl,
                           OCIError         *err,
                           OCIThreadHandle  *tHnd );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

tHnd (IN/OUT)

If not NULL, the location to place the thread handle for the thread.

Comments

tHnd should be initialized by OCIThreadHndInit().

The thread handle tHnd retrieved by this function must be closed with OCIThreadClose() and destroyed by OCIThreadHndDestroy() after it is used.

Related Functions

OCIThreadHndDestroy(), OCIThreadHndInit()


OCIThreadHndDestroy()

Purpose

Destroys and deallocates the thread handle.

Syntax

sword OCIThreadHndDestroy ( dvoid            *hndl, 
                            OCIError         *err, 
                            OCIThreadHandle  **thnd );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

thnd (IN/OUT)

The address of pointer to the thread handle to destroy.

Comments

thnd should be initialized by OCIThreadHndInit().

Related Functions

OCIThreadHandleGet(), OCIThreadHndInit()


OCIThreadHndInit()

Purpose

Allocates and initializes the thread handle.

Syntax

sword OCIThreadHndInit ( dvoid           *hndl, 
                         OCIError        *err,
                         OCIThreadHandle **thnd );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

thnd (OUT)

The address of pointer to the thread handle to initialize.

Related Functions

OCIThreadHandleGet(), OCIThreadHndDestroy()


OCIThreadIdDestroy()

Purpose

Destroys and deallocates a thread Id.

Syntax

sword OCIThreadIdDestroy (dvoid        *hndl,
                          OCIError     *err,
                          OCIThreadId  **tid );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

tid (IN/OUT)

Pointer to the thread ID to destroy.

Comments

tid should be initialized by OCIThreadIdInit().

Related Functions

OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()


OCIThreadIdGet()

Purpose

Retrieves the OCIThreadId of the thread in which it is called.

Syntax

sword OCIThreadIdGet ( dvoid        *hndl,
                       OCIError     *err, 
                       OCIThreadId  *tid );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

tid (OUT)

This should point to the location in which to place the ID of the calling thread.

Comments

tid should be initialized by OCIThreadIdInit(). When OCIThread is used in a single-threaded environment, OCIThreadIdGet() will always place the same value in the location pointed to by tid. The exact value itself is not important. The important thing is that it is not the same as the NULL thread ID and that it is always the same value.

Related Functions

OCIThreadIdDestroy(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()


OCIThreadIdInit()

Purpose

Allocate and initialize the thread Id tid.

Syntax

sword OCIThreadIdInit ( dvoid        *hndl,
                        OCIError     *err, 
                        OCIThreadId  **tid );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR

is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

tid (OUT)

Pointer to the thread ID to initialize.

Related Functions

OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()


OCIThreadIdNull()

Purpose

Determines whether or not a given OCIThreadId is the NULL thread Id.

Syntax

sword OCIThreadIdNull ( dvoid        *hndl, 
                        OCIError     *err, 
                        OCIThreadId  *tid, 
                        boolean      *result );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

tid (IN)

Pointer to the OCIThreadId to check.

result (IN/OUT)

Pointer to the result.

Comments

If tid is the NULL thread ID, result is set to TRUE. Otherwise, result is set to FALSE. tid should be initialized by OCIThreadIdInit().

Related Functions

OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()


OCIThreadIdSame()

Purpose

Determines whether or not two OCIThreadIds represent the same thread.

Syntax

sword OCIThreadIdSame ( dvoid         *hndl, 
                        OCIError      *err,
                        OCIThreadId   *tid1, 
                        OCIThreadId   *tid2, 
                        boolean       *result );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

tid1 (IN)

Pointer to the first OCIThreadId.

tid2 (IN)

Pointer to the second OCIThreadId.

result (IN/OUT)

Pointer to the result.

Comments

If tid1 and tid2 represent the same thread, result is set to TRUE. Otherwise, result is set to FALSE. result is set to TRUE if both tid1 and tid2 are the NULL thread ID. ti1d and tid2 should be initialized by OCIThreadIdInit().

Related Functions

OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSet(), OCIThreadIdSetNull()


OCIThreadIdSet()

Purpose

Sets one OCIThreadId to another.

Syntax

sword OCIThreadIdSet ( dvoid        *hndl,
                       OCIError     *err,
                       OCIThreadId  *tidDest, 
                       OCIThreadId  *tidSrc );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

tidDest (OUT)

This should point to the location of the OCIThreadId to be set to.

tidSrc (IN)

This should point to the OCIThreadId to set from.

Comments

tid should be initialized by OCIThreadIdInit().

Related Functions

OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSetNull()


OCIThreadIdSetNull()

Purpose

Sets the NULL thread ID to a given OCIThreadId.

Syntax

sword OCIThreadIdSetNull ( dvoid        *hndl,
                           OCIError     *err, 
                           OCIThreadId  *tid );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

tid (OUT)

This should point to the OCIThreadId in which to put the NULL thread Id.

Comments

tid should be initialized by OCIThreadIdInit().

Related Functions

OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()


OCIThreadInit()

Purpose

Initializes the OCIThread context.

Syntax

sword OCIThreadInit ( dvoid     *hndl,
                      OCIError  *err );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

Comments

It is illegal for OCIThread clients to try an examine the memory pointed to by the returned pointer. It is safe to make concurrent calls to OCIThreadInit(). Unlike OCIThreadProcessInit(), there is no need to have a first call that occurs before all the others.

The first time OCIThreadInit() is called, it initializes the OCI Thread context. It also saves a pointer to the context in some system dependent manner. Subsequent calls to OCIThreadInit() will return the same context.

Each call to OCIThreadInit() must eventually be matched by a call to OCIThreadTerm().

Related Functions

OCIThreadTerm()


OCIThreadIsMulti()

Purpose

Tells the caller whether the application is running in a multi-threaded environment or a single-threaded environment.

Syntax

boolean OCIThreadIsMulti ( );

Returns

TRUE if the environment is multi-threaded;

FALSE if the environment is single-threaded.

Related Functions

OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()


OCIThreadJoin()

Purpose

Allows the calling thread to join with another thread.

Syntax

sword OCIThreadJoin ( dvoid            *hndl,
                      OCIError         *err, 
                      OCIThreadHandle  *tHnd );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

tHnd (IN)

The OCIThreadHandle of the thread to join with.

Comments

This function blocks the caller until the specified thread terminates.

tHnd should be initialized by OCIThreadHndInit(). The result of multiple threads all trying to join with the same thread is undefined.

Related Functions

OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()


OCIThreadKeyDestroy()

Purpose

Destroy and deallocate the key pointed to by key.

Syntax

sword OCIThreadKeyDestroy ( dvoid         *hndl,
                            OCIError      *err, 
                            OCIThreadKey  **key );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

key (IN/OUT)

The OCIThreadKey in which to destroy the key.

Comments

This is different from the destructor function callback passed to the key create routine. This new destroy function OCIThreadKeyDestroy() is used to terminate any resources OCI THREAD acquired when it created key. The OCIThreadKeyDestFunc callback of OCIThreadKeyInit() is a key VALUE destructor; it does in no way operate on the key itself.

This must be called once the user has finished using the key. Not calling the key destroy function may result in memory leaks.

Related Functions

OCIThreadKeyGet(), OCIThreadKeyInit(), OCIThreadKeySet()


OCIThreadKeyGet()

Purpose

Gets the calling threads current value for a key.

Syntax

sword OCIThreadKeyGet ( dvoid         *hndl, 
                        OCIError      *err, 
                        OCIThreadKey  *key, 
                        dvoid         **pValue );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

key (IN)

The key.

pValue (IN/OUT)

The location in which to place the thread-specific key value.

Comments

It is illegal to use this function on a key that has not been created using OCIThreadKeyInit().

If the calling thread has not yet assigned a value to the key, NULL is placed in the location pointed to by pValue.

Related Functions

OCIThreadKeyDestroy(), OCIThreadKeyInit(), OCIThreadKeySet()


OCIThreadKeyInit()

Purpose

Creates a key.

Syntax

sword OCIThreadKeyInit (dvoid                 *hndl, 
                        OCIError              *err,
                        OCIThreadKey          **key,
                        OCIThreadKeyDestFunc  destFn );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

key (OUT)

The OCIThreadKey in which to create the new key.

destFn (IN)

The destructor for the key. NULL is permitted.

Comments

Each call to this routine allocate and generates a new key that is distinct from all other keys. After this function executes successfully, a pointer to an allocated and initialized key is return. That key can be used with OCIThreadKeyGet() and OCIThreadKeySet(). The initial value of the key will be NULL for all threads.

It is illegal for this function to be called more than once with the same value for the key parameter.

If the destFn parameter is not NULL, the routine pointed to by destFn will be called whenever a thread that has a non-NULL value for the key terminates. The routine will be called with one parameter. The parameter will be the keys value for the thread at the time at which the thread terminated. If the key does not need a destructor function, pass NULL for destFn.

Related Functions

OCIThreadKeyDestroy(), OCIThreadKeyGet(), OCIThreadKeySet()


OCIThreadKeySet()

Purpose

Sets the calling threads value for a key.

Syntax

sword OCIThreadKeySet ( dvoid          *hndl,
                        OCIError       *err, 
                        OCIThreadKey   *key,
                        dvoid          *value );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

key (IN/OUT)

The key.

value (IN)

The thread-specific value to set in the key.

Comments

It is illegal to use this function on a key that has not been created using OCIThreadKeyInit().

Related Functions

OCIThreadKeyDestroy(), OCIThreadKeyGet(), OCIThreadKeyInit()


OCIThreadMutexAcquire()

Purpose

Acquires a mutex for the thread in which it is called.

Syntax

sword OCIThreadMutexAcquire ( dvoid           *hndl,
                              OCIError        *err, 
                              OCIThreadMutex  *mutex );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

mutex (IN/OUT)

The mutex to acquire.

Comments

If the mutex is held by another thread, the calling thread is blocked until it can acquire the mutex.

It is illegal to attempt to acquire an uninitialized mutex.

This functions behavior is undefined if it is used by a thread to acquire a mutex that is already held by that thread.

Related Functions

OCIThreadMutexDestroy(), OCIThreadMutexInit(), OCIThreadMutexRelease()


OCIThreadMutexDestroy()

Purpose

Destroys and deallocate a mutex.

Syntax

sword OCIThreadMutexDestroy ( dvoid          *hndl, 
                              OCIError       *err, 
                              OCIThreadMutex **mutex );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

mutex (IN/OUT)

The mutex to destroy.

Comments

Each mutex must be destroyed once it is no longer needed.

It is not legal to destroy a mutex that is uninitialized or is currently held by a thread. The destruction of a mutex must not occur concurrently with any other operations on the mutex. A mutex must not be used after it has been destroyed.

Related Functions

OCIThreadMutexAcquire(), OCIThreadMutexInit(), OCIThreadMutexRelease()


OCIThreadMutexInit()

Purpose

Allocates and initializes a mutex.

Syntax

sword OCIThreadMutexInit ( dvoid           *hndl,
                           OCIError        *err, 
                           OCIThreadMutex  **mutex );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

mutex (OUT)

The mutex to initialize.

Comments

All mutexes must be initialized prior to use.

Multiple threads must not initialize the same mutex simultaneously. Also, a mutex must not be reinitialized until it has been destroyed (see OCIThreadMutexDestroy()).

Related Functions

OCIThreadMutexDestroy(), OCIThreadMutexAcquire(), OCIThreadMutexRelease()


OCIThreadMutexRelease()

Purpose

Releases a mutex.

Syntax

sword OCIThreadMutexRelease ( dvoid           *hndl,
                              OCIError        *err, 
                              OCIThreadMutex  *mutex );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

mutex (IN/OUT)

The mutex to release.

Comments

If there are any threads blocked on the mutex, one of them will acquire it and become unblocked.

It is illegal to attempt to release an uninitialized mutex. It is also illegal for a thread to release a mutex that it does not hold.

Related Functions

OCIThreadMutexDestroy(), OCIThreadMutexInit(), OCIThreadMutexAcquire()


OCIThreadProcessInit()

Purpose

Performs OCIThread process initialization.

Syntax

void OCIThreadProcessInit ( );

Comments

Whether or not this function needs to be called depends on how OCI Thread is going to be used.

In a single-threaded application, calling this function is optional. If it is called at all, the first call to it must occur before calls to any other OCIThread functions. Subsequent calls can be made without restriction; they will not have any effect.

In a multi-threaded application, this function MUST be called. The first call to it MUST occur strictly before any other OCIThread calls; i.e., no other calls to OCIThread functions (including other calls to this one) can be concurrent with the first call.

Subsequent calls to this function can be made without restriction; they will not have any effect.

Related Functions

OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()


OCIThreadTerm()

Purpose

Releases the OCIThread context.

Syntax

sword OCIThreadTerm ( dvoid     *hndl, 
                      OCIError  *err );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet().

Comments

This function should be called exactly once for each call made to OCIThreadInit().

It is safe to make concurrent calls to OCIThreadTerm(). OCIThreadTerm() will not do anything until it has been called as many times as OCIThreadInit() has been called. When that happens, it terminates the OCIThread layer and frees the memory allocated for the context. Once this happens, the context should not be re-used. It will be necessary to obtain a new one by calling OCIThreadInit().

Related Functions

OCIThreadInit()

Transaction Functions

This section describes the transaction functions.

Table 15-9 OCI Quick Reference
Function  Purpose 

OCITransCommit()  

Commit a transaction on a service context  

OCITransDetach()  

Detach a transaction from a service context  

OCITransForget()  

Forget a prepared global transaction  

OCITransPrepare()  

Prepare a global transaction for commit  

OCITransRollback()  

Roll back a transaction  

OCITransStart()  

Start a transaction on a service context  


OCITransCommit()

Purpose

Commits the transaction associated with a specified service context.

Syntax

sword OCITransCommit ( OCISvcCtx    *svchp,
                       OCIError     *errhp,
                       ub4          flags );

Parameters

svchp (IN)

The service context handle.

errhp (IN)

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

flags (IN)

A flag used for one-phase commit optimization in global transactions.

If the transaction is non-distributed, the flags parameter is ignored, and OCI_DEFAULT can be passed as its value. OCI applications managing global transactions should pass a value of OCI_TRANS_TWOPHASE to the flags parameter for a two-phase commit. The default is one-phase commit.

Comments

The transaction currently associated with the service context is committed. If it is a global transaction that the server cannot commit, this call additionally retrieves the state of the transaction from the database to be returned to the user in the error handle.

If the application has defined multiple transactions, this function operates on the transaction currently associated with the service context. If the application is working with only the implicit local transaction created when database changes are made, that implicit transaction is committed.

If the application is running in the object mode, then the modified or updated objects in the object cache for this transaction are also flushed and committed.

Under normal circumstances, OCITransCommit() returns with a status indicating that the transaction has either been committed or rolled back. With global transactions, it is possible that the transaction is now in-doubt, meaning that it is neither committed nor aborted. In this case, OCITransCommit() attempts to retrieve the status of the transaction from the server. The status is returned.

Example

The following example demonstrates the use of a simple local transaction, as described in the section "Simple Local Transactions".

int main()
{
  OCIEnv *envhp;
  OCIServer *srvhp;
  OCIError *errhp;
  OCISvcCtx *svchp;
  OCIStmt *stmthp;
  dvoid     *tmp;
  text sqlstmt[128];

  OCIInitialize((ub4) OCI_OBJECT, (dvoid *)0,  (dvoid * (*)()) 0,
             (dvoid * (*)()) 0,  (void (*)()) 0 );
  
  OCIHandleAlloc( (dvoid *) NULL, (dvoid **) &envhp, (ub4) OCI_HTYPE_ENV,
             0, (dvoid **) &tmp);
  
  OCIEnvInit( &envhp, (ub4) OCI_DEFAULT, 21, (dvoid **) &tmp  );
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, (ub4) OCI_HTYPE_ERROR,
                52, (dvoid **) &tmp);
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4) OCI_HTYPE_SERVER,
                52, (dvoid **) &tmp);
  
  OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4) OCI_HTYPE_SVCCTX,
                52, (dvoid **) &tmp);

  OCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp, OCI_HTYPE_STMT, 0, 0);

  OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)srvhp, 0,
                  OCI_ATTR_SERVER, errhp);

  OCILogon(envhp, errhp, &svchp, "SCOTT", strlen("SCOTT"), 
                 "TIGER", strlen("TIGER"), 0, 0);

  /* update scott.emp empno=7902, increment salary */
  sprintf((char *)sqlstmt, "UPDATE EMP SET SAL = SAL + 1 WHERE EMPNO = 7902");
  OCIStmtPrepare(stmthp, errhp, sqlstmt, strlen(sqlstmt), OCI_NTV_SYNTAX, 0);
  OCIStmtExecute(svchp, stmthp, errhp, 1, 0, 0, 0, 0);
  OCITransCommit(svchp, errhp, (ub4) 0);

  /* update scott.emp empno=7902, increment salary again, but rollback */
  OCIStmtExecute(svchp, stmthp, errhp, 1, 0, 0, 0, 0);
  OCITransRollback(svchp, errhp, (ub4) 0);
}

Related Functions

OCITransRollback()


OCITransDetach()

Purpose

Detaches a transaction.

Syntax

sword OCITransDetach ( OCISvcCtx    *svchp,
                       OCIError     *errhp,
                       ub4          flags );

Parameters

svchp (IN)

The service context handle.

errhp (IN)

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

flags (IN)

You must pass a value of OCI_DEFAULT for this parameter.

Comments

Detaches a global transaction from the service context handle. The transaction currently attached to the service context handle becomes inactive at the end of this call. The transaction may be resumed later by calling OCITransStart(), specifying a flags value of OCI_TRANS_RESUME.

When a transaction is detached, the value which was specified in the timeout parameter of OCITransStart() when the transaction was started is used to determine the amount of time the branch can remain inactive before being deleted by the server's PMON process.

Note: The transaction can be resumed by a different process than the one that detached it, provided that the transaction has the same authorization. If this function is called before a transaction is actually started, this function is a no-op.

For example code demonstrating the use of OCITransDetach() see the description of OCITransStart().

Related Functions

OCITransStart()


OCITransForget()

Purpose

Causes the server to forget a heuristically completed global transaction.

Syntax

sword OCITransForget ( OCISvcCtx     *svchp, 
                       OCIError      *errhp,
                       ub4           flags );

Parameters

svchp (IN)

The service context handle in which the transaction resides.

errhp (IN)

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

flags (IN)

You must pass OCI_DEFAULT for this parameter.

Comments

Forgets a heuristically completed global transaction. The server deletes the status of the transaction from the system's pending transaction table.

You set the XID of the transaction to be forgotten as an attribute of the transaction handle (OCI_ATTR_XID).

Related Functions

OCITransCommit(), OCITransRollback()


OCITransPrepare()

Purpose

Prepares a transaction for commit.

Syntax

sword OCITransPrepare ( OCISvcCtx    *svchp, 
                        OCIError     *errhp,
                        ub4          flags );

Parameters

svchp (IN)

The service context handle.

errhp (IN)

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

flags (IN)

You must pass OCI_DEFAULT for this parameter.

Comments

Prepares the specified global transaction for commit.

This call is valid only for global transactions.

The call returns OCI_SUCCESS_WITH_INFO if the transaction has not made any changes. The error handle will indicate that the transaction is read-only. The flag parameter is not currently used.

Related Functions

OCITransCommit(), OCITransForget()


OCITransRollback()

Purpose

Rolls back the current transaction.

Syntax

sword OCITransRollback ( dvoid        *svchp, 
                         OCIError     *errhp,
                         ub4          flags );

Parameters

svchp (IN)

A service context handle. The transaction currently set in the service context handle is rolled back.

errhp (IN)

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

flags (IN)

You must pass a value of OCI_DEFAULT for this parameter.

Comments

The current transaction-- defined as the set of statements executed since the last OCITransCommit() or since OCISessionBegin()--is rolled back.

If the application is running under object mode then the modified or updated objects in the object cache for this transaction are also rolled back.

Attempting to roll back a global transaction that is not currently active causes an error.

Examples

For example code demonstrating the use of OCITransRollback() see the description of OCITransCommit().

Related Functions

OCITransCommit()


OCITransStart()

Purpose

Sets the beginning of a transaction.

Syntax

sword OCITransStart ( OCISvcCtx    *svchp, 
                      OCIError     *errhp, 
                      uword        timeout,
                      ub4          flags );

Parameters

svchp (IN/OUT)

The service context handle. The transaction context in the service context handle is initialized at the end of the call if the flag specified a new transaction to be started.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

timeout (IN)

The time, in seconds, to wait for a transaction to become available for resumption when OCI_TRANS_RESUME is specified. When OCI_TRANS_NEW is specified, the timeout parameter indicates the number of seconds the transaction can be inactive before it is automatically aborted by the system. A transaction is inactive between the time it is detached (with OCITransDetach()) and the time it is resumed with OCITransStart().

flags (IN)

Specifies whether a new transaction is being started or an existing transaction is being resumed. Also specifies serializiability or read-only status. More than a single value can be specified. By default, a read/write transaction is started. The flag values are:

Comments

This function sets the beginning of a global or serializable transaction. The transaction context currently associated with the service context handle is initialized at the end of the call if the flags parameter specifies that a new transaction should be started.

The XID of the transaction is set as an attribute of the transaction handle (OCI_ATTR_XID)

Examples

The following examples demonstrate the use of OCI transactional calls for manipulating global transactions.

Example 1

This example shows a single session operating on different branches. This concept is illustrated by Figure 8-2, "Session Operating on Multiple Branches".

int main()
{
  OCIEnv *envhp;
  OCIServer *srvhp;
  OCIError *errhp;
  OCISvcCtx *svchp;
  OCISession *usrhp;
  OCIStmt *stmthp1, *stmthp2;
  OCITrans *txnhp1, *txnhp2;
  dvoid     *tmp;
  XID gxid;
  text sqlstmt[128];

  OCIInitialize((ub4) OCI_OBJECT, (dvoid *)0,  (dvoid * (*)()) 0,
             (dvoid * (*)()) 0,  (void (*)()) 0 );
  
  OCIHandleAlloc( (dvoid *) NULL, (dvoid **) &envhp, (ub4) OCI_HTYPE_ENV,
             0, (dvoid **) &tmp);
  
  OCIEnvInit( &envhp, (ub4) OCI_DEFAULT, 21, (dvoid **) &tmp  );
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, (ub4) OCI_HTYPE_ERROR,
                52, (dvoid **) &tmp);
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4) OCI_HTYPE_SERVER,
                52, (dvoid **) &tmp);
  
  OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4) OCI_HTYPE_SVCCTX,
                52, (dvoid **) &tmp);

  OCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp1, OCI_HTYPE_STMT, 0, 0);
  OCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp2, OCI_HTYPE_STMT, 0, 0);

  OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)srvhp, 0,
                  OCI_ATTR_SERVER, errhp);

  /* set the external name and internal name in server handle */
  OCIAttrSet((dvoid *)srvhp, OCI_HTYPE_SERVER, (dvoid *) "demo", 0,
                  OCI_ATTR_EXTERNAL_NAME, errhp);
  OCIAttrSet((dvoid *)srvhp, OCI_HTYPE_SERVER, (dvoid *) "txn demo", 0,
                          OCI_ATTR_INTERNAL_NAME, errhp);

  /* allocate a user context handle */
  OCIHandleAlloc((dvoid *)envhp, (dvoid **)&usrhp, (ub4) OCI_HTYPE_SESSION,
                (size_t) 0, (dvoid **) 0);
  
  OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"scott", 
             (ub4)strlen("scott"), OCI_ATTR_USERNAME, errhp);
  OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"tiger", 
             (ub4)strlen("tiger"),OCI_ATTR_PASSWORD, errhp);
  
  OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS, 0);
  
  OCIAttrSet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX,
                (dvoid *)usrhp, (ub4)0, OCI_ATTR_SESSION, errhp);

  /* allocate transaction handle 1 and set it in the service handle */
  OCIHandleAlloc((dvoid *)envhp, (dvoid **)&txnhp1,  OCI_HTYPE_TRANS, 0, 0);
  OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)txnhp1, 0,
                          OCI_ATTR_TRANS, errhp);

  /* start a transaction with global transaction id = [1000, 123, 1] */
  gxid.formatID = 1000; /* format id = 1000 */
  gxid.gtrid_length = 3; /* gtrid = 123 */
  gxid.data[0] = 1; gxid.data[1] = 2; gxid.data[2] = 3;
  gxid.bqual_length = 1; /* bqual = 1 */
  gxid.data[3] = 1;

  OCIAttrSet((dvoid *)txnhp1, OCI_HTYPE_TRANS, (dvoid *)&gxid, sizeof(XID),
                          OCI_ATTR_XID, errhp);

  /* start global transaction 1 with 60 second time to live when detached */
  OCITransStart(svchp, errhp, 60, OCI_TRANS_NEW);

  /* update scott.emp empno=7902, increment salary */
  sprintf((char *)sqlstmt, "UPDATE EMP SET SAL = SAL + 1 WHERE EMPNO = 7902");
  OCIStmtPrepare(stmthp1, errhp, sqlstmt, strlen(sqlstmt), OCI_NTV_SYNTAX, 0);
  OCIStmtExecute(svchp, stmthp1, errhp, 1, 0, 0, 0, 0);

  /* detach the transaction */
  OCITransDetach(svchp, errhp, 0);

  /* allocate transaction handle 2 and set it in the service handle */
  OCIHandleAlloc((dvoid *)envhp, (dvoid **)&txnhp2,  OCI_HTYPE_TRANS, 0, 0);
  OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)txnhp2, 0,
                          OCI_ATTR_TRANS, errhp);

  /* start a transaction with global transaction id = [1000, 124, 1] */
  gxid.formatID = 1000; /* format id = 1000 */
  gxid.gtrid_length = 3; /* gtrid = 124 */
  gxid.data[0] = 1; gxid.data[1] = 2; gxid.data[2] = 4;
  gxid.bqual_length = 1; /* bqual = 1 */
  gxid.data[3] = 1; 

  OCIAttrSet((dvoid *)txnhp2, OCI_HTYPE_TRANS, (dvoid *)&gxid, sizeof(XID),
                          OCI_ATTR_XID, errhp);

  /* start global transaction 2 with 90 second time to live when detached */
  OCITransStart(svchp, errhp, 90, OCI_TRANS_NEW);

  /* update scott.emp empno=7934, increment salary */
  sprintf((char *)sqlstmt, "UPDATE EMP SET SAL = SAL + 1 WHERE EMPNO = 7934");
  OCIStmtPrepare(stmthp2, errhp, sqlstmt, strlen(sqlstmt), OCI_NTV_SYNTAX, 0);
  OCIStmtExecute(svchp, stmthp2, errhp, 1, 0, 0, 0, 0);

  /* detach the transaction */
  OCITransDetach(svchp, errhp, 0);

  /* Resume transaction 1, increment salary and commit it */
  /* Set transaction handle 1 into the service handle */
  OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)txnhp1, 0,
                          OCI_ATTR_TRANS, errhp);

  /* attach to transaction 1, wait for 10 seconds if the transaction is busy */
  /* The wait is clearly not required in this example because no other      */
  /* process/thread is using the transaction. It is only for illustration    */
  OCITransStart(svchp, errhp, 10, OCI_TRANS_RESUME);
  OCIStmtExecute(svchp, stmthp1, errhp, 1, 0, 0, 0, 0);
  OCITransCommit(svchp, errhp, (ub4) 0);

  /* attach to transaction 2 and commit it */
  /* set transaction handle2 into the service handle */
  OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)txnhp2, 0,
                          OCI_ATTR_TRANS, errhp);
  OCITransCommit(svchp, errhp, (ub4) 0);
}
Example 2

This example demonstrates a single session operating on multiple branches that share the same transaction.

int main()
{
  OCIEnv *envhp;
  OCIServer *srvhp;
  OCIError *errhp;
  OCISvcCtx *svchp;
  OCISession *usrhp;
  OCIStmt *stmthp;
  OCITrans *txnhp1, *txnhp2;
  dvoid     *tmp;
  XID gxid;
  text sqlstmt[128];

  OCIInitialize((ub4) OCI_OBJECT, (dvoid *)0,  (dvoid * (*)()) 0,
             (dvoid * (*)()) 0,  (void (*)()) 0 );
  
  OCIHandleAlloc( (dvoid *) NULL, (dvoid **) &envhp, (ub4) OCI_HTYPE_ENV,
             0, (dvoid **) &tmp);
  
  OCIEnvInit( &envhp, (ub4) OCI_DEFAULT, 21, (dvoid **) &tmp  );
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, (ub4) OCI_HTYPE_ERROR,
                52, (dvoid **) &tmp);
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4) OCI_HTYPE_SERVER,
                52, (dvoid **) &tmp);
  
  OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
  
  OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4) OCI_HTYPE_SVCCTX,
                52, (dvoid **) &tmp);

  OCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp, OCI_HTYPE_STMT, 0, 0);

  OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)srvhp, 0,
                  OCI_ATTR_SERVER, errhp);

  /* set the external name and internal name in server handle */
  OCIAttrSet((dvoid *)srvhp, OCI_HTYPE_SERVER, (dvoid *) "demo", 0,
                  OCI_ATTR_EXTERNAL_NAME, errhp);
  OCIAttrSet((dvoid *)srvhp, OCI_HTYPE_SERVER, (dvoid *) "txn demo2", 0,
                          OCI_ATTR_INTERNAL_NAME, errhp);

  /* allocate a user context handle */
  OCIHandleAlloc((dvoid *)envhp, (dvoid **)&usrhp, (ub4) OCI_HTYPE_SESSION,
                (size_t) 0, (dvoid **) 0);
  
  OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"scott", 
             (ub4)strlen("scott"), OCI_ATTR_USERNAME, errhp);
  OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"tiger", 
             (ub4)strlen("tiger"),OCI_ATTR_PASSWORD, errhp);
  
  OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS, 0);
  
  OCIAttrSet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX,
                (dvoid *)usrhp, (ub4)0, OCI_ATTR_SESSION, errhp);

  /* allocate transaction handle 1 and set it in the service handle */
  OCIHandleAlloc((dvoid *)envhp, (dvoid **)&txnhp1,  OCI_HTYPE_TRANS, 0, 0);
  OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)txnhp1, 0,
                          OCI_ATTR_TRANS, errhp);

  /* start a transaction with global transaction id = [1000, 123, 1] */
  gxid.formatID = 1000; /* format id = 1000 */
  gxid.gtrid_length = 3; /* gtrid = 123 */
  gxid.data[0] = 1; gxid.data[1] = 2; gxid.data[2] = 3;
  gxid.bqual_length = 1; /* bqual = 1 */
  gxid.data[3] = 1;

  OCIAttrSet((dvoid *)txnhp1, OCI_HTYPE_TRANS, (dvoid *)&gxid, sizeof(XID),
                          OCI_ATTR_XID, errhp);

  /* start global transaction 1 with 60 second time to live when detached */
  OCITransStart(svchp, errhp, 60, OCI_TRANS_NEW);

  /* update scott.emp empno=7902, increment salary */
  sprintf((char *)sqlstmt, "UPDATE EMP SET SAL = SAL + 1 WHERE EMPNO = 7902");
  OCIStmtPrepare(stmthp, errhp, sqlstmt, strlen(sqlstmt), OCI_NTV_SYNTAX, 0);
  OCIStmtExecute(svchp, stmthp, errhp, 1, 0, 0, 0, 0);

  /* detach the transaction */
  OCITransDetach(svchp, errhp, 0);

  /* allocate transaction handle 2 and set it in the service handle */
  OCIHandleAlloc((dvoid *)envhp, (dvoid **)&txnhp2,  OCI_HTYPE_TRANS, 0, 0);
  OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)txnhp2, 0,
                          OCI_ATTR_TRANS, errhp);
            
  /* start a transaction with global transaction id = [1000, 123, 2] */
  /* The global transaction will be tightly coupled with earlier transaction */
  /* There is not much practical value in doing this but the example */
  /* illustrates the use of tightly-coupled transaction branches */
  /* In a practical case the second transaction that tightly couples with */
  /* the first can be executed from a different process/thread */

  gxid.formatID = 1000; /* format id = 1000 */
  gxid.gtrid_length = 3; /* gtrid = 123 */
  gxid.data[0] = 1; gxid.data[1] = 2; gxid.data[2] = 3;
  gxid.bqual_length = 1; /* bqual = 2 */
  gxid.data[3] = 2; 

  OCIAttrSet((dvoid *)txnhp2, OCI_HTYPE_TRANS, (dvoid *)&gxid, sizeof(XID),
                          OCI_ATTR_XID, errhp);

  /* start global transaction 2 with 90 second time to live when detached */
  OCITransStart(svchp, errhp, 90, OCI_TRANS_NEW);

  /* update scott.emp empno=7902, increment salary */
  /* This is possible even if the earlier transaction has locked this row */
  /* because the two global transactions are tightly coupled */
  OCIStmtExecute(svchp, stmthp, errhp, 1, 0, 0, 0, 0);

  /* detach the transaction */
  OCITransDetach(svchp, errhp, 0);

  /* Resume transaction 1 and prepare it. This will return */
  /* OCI_SUCCESS_WITH_INFO because all branches except the last branch */
  /* are treated as read-only transactions for tightly-coupled transactions */ 

  OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)txnhp1, 0,
                          OCI_ATTR_TRANS, errhp);
  if (OCITransPrepare(svchp, errhp, (ub4) 0) == OCI_SUCCESS_WITH_INFO)
  {
    text errbuf[512];
    ub4 buflen;
    sb4 errcode;

    OCIErrorGet ((dvoid *) errhp, (ub4) 1, (text *) NULL, &errcode,
    errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
    printf("OCITransPrepare - %s\n", errbuf);
  }

  /* attach to transaction 2 and commit it */
  /* set transaction handle2 into the service handle */
  OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)txnhp2, 0,
                          OCI_ATTR_TRANS, errhp);
  OCITransCommit(svchp, errhp, (ub4) 0);
}

Related Functions

OCITransDetach()

Miscellaneous Functions

This section describes the miscellaneous OCI functions.

Table 15-10 OCI Quick Reference
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  

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) abort 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) abort 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.

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

Related Functions

OCIReset()


OCIErrorGet()

Purpose

Returns an error message in the buffer provided and an ORACLE error.

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 OCIEnvInit(), OCIHandleAlloc()).

recordno (IN)

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

sqlstate (OUT)

Not supported in release 8.0.

errcodep (OUT)

An ORACLE Error is returned.

bufp (OUT)

The error message text is returned.

bufsiz (IN)

The size of the buffer provide to get the error message.

type (IN)

The type of the handle (OCI_HTYPE_ERR or OCI_HTYPE_ENV).

Comments

Returns an error message in the buffer provided and an ORACLE error code. This function does not support SQL state. This function can be called multiple times if there are more than one diagnostic record for an error.

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

Example

The following sample code demonstrates how you can use OCIErrorGet() in an error-handling routine. This routine prints out the type of status code returned by an OCI function, and if an error occurred, OCIErrorGet() retrieves the text of the message, which is printed.

static void checkerr(errhp, status)
OCIError *errhp;
sword status;
{ text errbuf[512];
  ub4 buflen;
  ub4 errcode;
switch (status)
{ case OCI_SUCCESS:
    break;
  case OCI_SUCCESS_WITH_INFO:
    printf("ErrorOCI_SUCCESS_WITH_INFO\n");
    break;
  case OCI_NEED_DATA:
    printf("ErrorOCI_NEED_DATA\n");
    break;
  case OCI_NO_DATA:
    printf("ErrorOCI_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("ErrorOCI_INVALID_HANDLE\n");
    break;
  case OCI_STILL_EXECUTING:
    printf("ErrorOCI_STILL_EXECUTE\n");
    break;
  case OCI_CONTINUE:
    printf("ErrorOCI_CONTINUE\n");
    break;
  default:
    break;
  }
}

Related Functions

OCIHandleAlloc()


OCILdaToSvcCtx()

Purpose

Converts a V7 Lda_Def to a V8 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 an Oracle release 8 service context handle. The action of this call can be reversed by passing the resulting service context handle to the OCISvcCtxToLda() function.

If the Service context has been converted to an Lda_Def, only Oracle7 calls may be used. It is illegal to make Oracle OCI release 8 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 mode. See Appendix A, "Handle and Descriptor Attributes", for more information.

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. It points to a character string, whose length is specified in usernm_len. This parameter must be NULL if the service context has been initialized with an user session handle.

usernm_len (IN)

The length of the user name string specified in user_name. For a valid user name string, usernm_len must be non-zero.

opasswd (IN)

Specifies the user's old password. It points to a character string, whose length is specified in opasswd_len.

opasswd_len (IN)

The length of the old password string specified in opasswd. For a valid password string, opasswd_len must be non-zero.

npasswd (IN)

Specifies the user's new password. It points to a character string, whose length is specified in npasswd_len which must be non-zero for a valid password string. 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)

Then length of the new password string specified in npasswd. For a valid password string, npasswd_len must be non-zero.

mode (IN)

Can be OCI_DEFAULT and/or OCI_AUTH. If set to OCI_AUTH, the following happens:

If the user session context is already created, this call just changes the password and the flag has no effect on the session. Hence the user still remains logged 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.

Related Functions

OCISessionBegin()


OCIReset()

Purpose

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

Syntax

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

Comments

This call is called in non-blocking mode ONLY. Resets the interrupted asynchronous operation and protocol. Must be called if a OCIBreak call had been issued while a non-blocking operation was in progress.

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.

Related Functions

OCIBreak()


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.

hndltype (IN)

The type of handle passed to the function.

Comments

This call returns the version string of the Oracle server. For example, the following might be returned as the version string if an application is running on a 7.3.2 server:

Oracle7 Server Release 7.3.2.0.0 Production Release
PL/SQL Release 2.3.2.0.0 Production
CORE Version 3.5.2.0.0 Production
TNS for SEQUENT DYNIX/ptx: Version 2.3.2.0.0 Production
NLSRTL Version 3.2.2.0.0 Production

Related Functions

OCIErrorGet()


OCISvcCtxToLda()

Purpose

Toggles between a V8 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 Oracle OCI release 8 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 (e.g., obindps(), ofen()).

Note: 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 mode. See Appendix A, "Handle and Descriptor Attributes", for more information.

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

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 15-11, "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. For information about the parameters of callbackp see the description of OCIUserCallbackRegister().

ctxpp (OUT)

A pointer to return context for the currently registered callback.

Comments

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

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,
                               ub1   when );

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 the entry callback returns anything other than OCI_CONTINUE, then the OCI code is skipped and control is transferred to the exit callback if one exists.

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 entry callback (if the entry 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.

ctxp (IN)

A context pointer for the callback.

fcode (IN)

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

when (IN)

Defines when the callback is invoked. Valid modes are:

Comments

This function is used to register a user-created callback function. The OCI provides the ability to register user-created callback functions with the OCI environment. 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 two kinds of callbacks: entry callbacks and exit callbacks.

Entry callbacks are executed when a program enters an OCI function. If the entry callback returns a value of OCI_CONTINUE, then the normal OCI-specific code is executed. If the callback returns anything other than OCI_CONTINUE, the OCI code does not execute.

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

Note: If no exit callback is registered and the entry callback returns something other than OCI_CONTINUE, then the return code from the entry callback is returned from the associated OCI call. Similarly, if the exit callback returns anything other than OCI_CONTINUE, then that return code is returned by the OCI call.

To find out the callback that is registered for handle, you can use OCIUserCallbackGet(). The prototype of this call is:.

The prototype of the OCIUserCallback typedef is:

typedef sword (*OCIUserCallback) 
           (dvoid   *ctxp,
            dvoid  *hndlp,
            ub4  type,
            ub4  fcode,
            ub1  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. Essentially, 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 15-11, "OCI Function Codes". Please note that callbacks can be registered for only the OCI calls listed in Table 15-11, "OCI Function Codes".

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 entry callback, OCI_SUCCESS will always be passed in. For the exit callback, the return code from the OCI code or the entry callback (if entry callback did not return OCI_CONTINUE) is passed in.

errnop (IN/OUT)

When the entry callback is called, the input value of *errnop is 0. If the entry 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 the exit callback, the input value of *errnop is the value of error number in the error handle. Therefore, if the entry callback did not return OCI_CONTINUE, then the out value of *errnop from the entry callback would be the one in the error handle, and that value would be passed in here to the exit callback. If, on the other hand, the entry callback returned OCI_CONTINUE, and the normal OCI code got executed, then whatever value that is in the error handle due to the OCI call would be passed in here.

Like the entry callback, if the exit callback returns anything other than an OCI_CONTINUE, then it must also set the value of *errnop. If OCI_CONTINUE is not returned by the exit callback, then the value of *errnop is set in the error handle.

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 Appendix B, "OCI Demonstration Programs" for a list of the available demonstration programs.

Table 15-11 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  

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




Prev

Next
Oracle
Copyright © 1999 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index