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.

.

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:

OCI_DEFAULT - executes the default call which discards all notifications on this subscription until the subscription is enabled

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:

OCI_DEFAULT - executes the default call which buffers all notifications on this subscription until a subsequent enable is performed

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:

OCI_DEFAULT - executes the default call

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:

OCI_DEFAULT - executes the default call which specifies that the registration is treated as disconnected
OCI_NOTIFY_CONNECTED - notifications are received only if the client is connected (not supported in this release)

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:

OCI_DEFAULT - executes the default call

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

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:

OCI_DTYPE_SNAP - specifies generation of snapshot descriptor of C type OCISnapshot
OCI_DTYPE_LOB - specifies generation of a LOB value type locator (for a BLOB or CLOB) of C type OCILobLocator
OCI_DTYPE_FILE - specifies generation of a FILE value type locator of C type OCILobLocator.
OCI_DTYPE_ROWID - specifies generation of a ROWID descriptor of C type OCIRowid.
OCI_DTYPE_DATETIME - specifies generation of a DATETIME descriptor of C type OCIDateTime
OCI_DTYPE_INTERVAL - specifies generation of an INTERVAL descriptor of C type OCIInterval
OCI_DTYPE_COMPLEXOBJECTCOMP - specifies generation of a complex object retrieval descriptor of C type OCIComplexObjectComp.
OCI_DTYPE_AQENQ_OPTIONS - specifies generation of an advanced queueing enqueue options descriptor of C type OCIAQEnqOptions.
OCI_DTYPE_AQDEQ_OPTIONS - specifies generation of an advanced queueing dequeue options descriptor of C type OCIAQDeqOptions.
OCI_DTYPE_AQMSG_PROPERTIES - specifies generation of an advanced queueing message properties descriptor of C type OCIAQMsgProperties.
OCI_DTYPE_AQAGENT - specifies generation of an advanced queueing agent descriptor of C type OCIAQAgent.

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

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:

OCI_DTYPE_SNAP - snapshot descriptor
OCI_DTYPE_LOB - a LOB value type descriptor
OCI_DTYPE_FILE - a FILE value type descriptor
OCI_DTYPE_ROWID - a ROWID descriptor
OCI_DTYPE_DATETIME - a DATETIME descriptor
OCI_DTYPE_INTERVAL - an INTERVAL descriptor
OCI_DTYPE_COMPLEXOBJECTCOMP - a complex object retrieval descriptor
OCI_DTYPE_AQENQ_OPTIONS - an AQ enqueue options descriptor
OCI_DTYPE_AQDEQ_OPTIONS - an AQ dequeue options descriptor
OCI_DTYPE_AQMSG_PROPERTIES - an AQ message properties descriptor
OCI_DTYPE_AQAGENT - an AQ agent descriptor

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:

OCI_HTYPE_ERROR - specifies generation of an error report handle of C type OCIError
OCI_HTYPE_SVCCTX - specifies generation of a service context handle of C type OCISvcCtx
OCI_HTYPE_STMT - specifies generation of a statement (application request) handle of C type OCIStmt
OCI_HTYPE_DESCRIBE - specifies generation of a select list description handle of C type OCIDescribe
OCI_HTYPE_SERVER - specifies generation of a server context handle of C type OCIServer
OCI_HTYPE_SESSION - specifies generation of a user session handle of C type OCISession
OCI_HTYPE_TRANS - specifies generation of a transaction context handle of C type OCITrans
OCI_HTYPE_COMPLEXOBJECT - specifies generation of a complex object retrieval handle of C type OCIComplexObject
OCI_HTYPE_SECURITY - specifies generation of a security handle of C type OCISecurity
OCI_HTYPE_SUBSCR - specifies a generation of a subscription handle of C type OCISubscription
OCI_HTYPE_DIRPATH_CTX - specifies a generation of a direct path context handle of C type OCIDirPathCtx
OCI_HTYPE_DIRPATH_COLUMN_ARRAY - specifies a generation of a direct path column array handle of C type OCIDirPathColArray
OCI_HTYPE_DIRPATH_STREAM - specifies a generation of a direct path stream handle of C type OCIDirPathStream
OCI_HTYPE_PROCESS - specifies a generation of a process handle of C type OCIProcess

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:

OCI_HTYPE_ENV - an environment handle
OCI_HTYPE_ERROR - an error report handle
OCI_HTYPE_SVCCTX - a service context handle
OCI_HTYPE_STMT - a statement (application request) handle
OCI_HTYPE_DESCRIBE - a select list description handle
OCI_HTYPE_SERVER - a server handle
OCI_HTYPE_SESSION - a user session handle
OCI_HTYPE_TRANS - a transaction handle
OCI_HTYPE_COMPLEXOBJECT - a complex object retrieval handle
OCI_HTYPE_SECURITY - a security handle
OCI_HTYPE_SUBSCR - a subscription handle
OCI_HTYPE_DIRPATH_CTX - direct path context handle
OCI_HTYPE_DIRPATH_COLUMN_ARRAY - direct path column array handle
OCI_HTYPE_DIRPATH_STREAM - direct path stream handle
OCI_HTYPE_PROCESS - process handle

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

OCI_DTYPE_PARM, for a parameter descriptor
OCI_HTYPE_COR, for a complex object retrieval handle
OCI_HTYPE_STMT, for a statement handle

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,

15 OCI Relational Functions

Introduction

Function Syntax

Purpose

Syntax

Parameters

Comments

Example

Related Functions

Calling OCI Functions

Server Roundtrips for LOB Functions

Advanced Queuing and Publish-Subscribe Functions

Table 15-1 OCI Quick Reference

OCIAQDeq()

Purpose

Syntax

Parameters

Comments

Examples

Related Functions

OCIAQEnq()

Purpose

Syntax

Parameters

Comments

Examples

Example 1

Example 2

Example 3

Example 4

Related Functions

OCIAQListen()

Purpose

Syntax

Parameters

Comments

Related Functions

OCISubscriptionDisable()

Purpose

Syntax

Parameters

Comments

Related Functions

OCISubscriptionEnable()

Purpose

Syntax

Parameters

Comments

Related Functions

OCISubscriptionPost()

Purpose

Syntax

Parameters

Comments

Related Functions

OCISubscriptionRegister()

Purpose

Syntax

Parameters

Comments

Related Functions

OCISubscriptionUnRegister()

Purpose

Syntax

Parameters

Comments

Related Functions

Handle and Descriptor Functions

Table 15-2 OCI Quick Reference

OCIAttrGet()

Purpose

Syntax

Parameters

Comments

Related Functions

OCIAttrSet()

Purpose

Syntax

Parameters

Comments

15
OCI Relational Functions