sdk/include/orid.h

/* Copyright (c) 1994, 2006, Oracle. All rights reserved.  */

/*
  Author:             Tin Nguyen
  Date:               02/07/94
  Source documents:   "Functional Specification for C Object Interface, Object
                       Management Subsystem", "Oracle C Coding Standards
                       version 2.2", and the header file template
  Rule sets:          the generic and .h file rule sets
  Quality status:     not exited
  Identification tag: [ one or more letters to identify the .h file ] 
  Revision code:      [ date of the last revision of the .h file ]

  Note to the user of this header file:

    Anything in this header file that is marked private is not supported and
    must not be used.  Private sections are included in the header file to 
    improve internal maintenance.

  NAME

    ORID - Oracle Object Interface for Dynamic Data Access

  DESCRIPTION

    This file contains declarations for C object interface functions including
    the dynamic object data access operations that allow callers to dynamically
    access and manipulate objects; these operations include getting and setting
    attributes of an object.  These dynamic object operations are for accessing
    and manipulation objects whose types are not known at compile-time.

  RELATED DOCUMENTS
  
     Functional Specification for C Object Interface / Object Management System

  PUBLIC FUNCTIONS

    OCIObjectSetAttr - ORID SET attribute value
    OCIObjectGetAttr - ORID GET attribute value

  PRIVATE FUNCTIONS

    None

  EXAMPLES 

    EXAMPLE 1

    /o
     o This example illustrates how an interative program can use the dynamic
     o attribute access to display and modify attributes of an ADT instance.
     o The interactive program does not know the type of the object at 
     o compile time.
     o/

    void display(adt_ref, object, null_struct, names, names_count, 
                          names_length, indexes, indexes_count)
    {
      /o Pin the ADT o/
      if (OCIObjectPin(env, &adt_ref, OROOPOCUR, OROOPDTRA, OROOLMNON, &adt) 
            != OROSTASUC)
         /o error handling code o/ 

      /o 
       o Call the type manager to obtain all the attributes in the object.
       o Display the content of each attribute in the ADT instance. If the 
       o attribute is an array, display each element of the array. If the
       o attribute is an ADT instance, recursively call this routine to
       o display the embedded ADT instance.
       o/ 
      numAttrs = OCITypeAttrs(env, adt);
      for (i= 1; i <= numAttrs; i++)
      {
         /o get attribute descriptor o/
         if (ortgabp(env, adt, i, &ado_ref, &ado) != OROSTASUC)
           /o error handling code o/ 

         /o get attribute name o/
         names[names_count] = OCITypeElemName(env, ado, 
                   &names_length[names_count]);
      
         /o dynamically get the attr o/
         if (OCIObjectGetAttr(env, object, null_struct, 0, adt_ref, names, 
                     names_length, names_count+1, indexes, indexes_count, 0, 
                     &null, &null_info, &attr) != OROSTASUC)
            /o error handling code o/  

         /o check if attribute is null o/
         if (null) continue;

         /o get typecode of attribute o/
         typecode = OCITypeElemTypeCode(env, ado);

         /o if attribute is a varray, display each element in varray o/
         if (typecode == OCI_TYPECODE_VARRAY)
         {
            /o get the reference to the type of the element of the array o/ 
            if (OCITypeElemParameterizedTyper(env, ado, &attr_type_ref) 
               != OROSTASUC)
               /o error handling code o/ 

            /o get the size of array o/
            if (orlasiz(env, &attr_type_ref, (orlva *)attr,  
                         &numElm) != OROSTASUC)
               /o error handling code o/  

            /o get the typecode of the element of the array o/
            if (ortty2r(env, attr_type_ref, &typecode) != OROSTASUC)
               /o error handling code o/  

            /o iterate the array o/
            for (j=0; j < numElm; j++)
            {
              /o get an element in the array o/
              if (OCIObjectGetAttr(env, attr, null_info, j+1, attr_type_ref,
                  names, names_length, 0, indexes, 0, 0, &null, &null_info, 
                  &element) != OROSTASUC)
                  /o error handling code o/  

              /o check if element is null o/
              if (null) continue;

              /o if attr is an ADT instance, recursively call this routine o/
              if (typecode == OCI_TYPECODE_ADT || typecode == 
                  OCI_TYPECODE_UNNAMEDADT) 
              {
                /o display the element as an adt o/
                display(attr_type_ref, element, null_info, names, lengths, 
                   0, indexes, 0);
              }
      
              /o if attribute is scalar, print the value to the screen o/
              else output_to_screen(element, typecode);
            }
         }

         /o if attribute is an ADT instance, recursively call this routine o/
         else if (typecode == OCI_TYPECODE_ADT || typecode == 
              OCI_TYPECODE_UNNAMEDADT)
         {
            /o get the type ref of the attribute o/
            if (ortgarf(env, ado, &attr_type_ref) != OROSTASUC)
               /o error handling code o/ 

             display(attr_type_ref, attr, null_info, 0, names, 0, names_length,
                      indexes, 0);
         }

         /o if attribute is scalar, print the value to the screen o/
         else output_to_screen(attr, typecode);
      }
    }

    /o ******** main routine *********** o/
    .... 

    /o 
     o Allocate the arrays for storing the path expression 
     o/

    /o get the tdo of type 'long' o/
    if (orttypget(&env, con, "SYS", sizeof("SYS"), "SINT32", sizeof("SINT32"), 
          OROOPDSES, &long_ref, &long_tdo) != OROSTASUC)
          /o error handling code o/

    /o get the tdo of type 'varchar' o/
    if (orttypget(&env, con, "SYS", sizeof("SYS"), "SQL_VARCHAR2", 
          sizeof("SQL_VARCHAR2"), OROOPDSES, &vchar_ref, &vchar_tdo) 
          != OROSTASUC)
          /o error handling code o/

    /o allocate the varrays for the path expression o/ 
    if (orlalloc(env, &vchar_ref, MAX_ARR_SIZE, &attr_names) != OROSTASUC)
       /o error handling code o/ 

    if (orlalloc(env, &long_ref, MAX_ARR_SIZE, &attr_name_lengths) 
                != OROSTASUC)
       /o error handling code o/ 

    if (orlalloc(env, &long_ref, MAX_ARR_SIZE, &attr_name_indexes) 
                != OROSTASUC)
       /o error handling code o/ 

    /o 
     o Get an ADT instance. The ref to the ADT instance can be obtained
     o by through ORI or OSCI. 
     o/
    if (OCIObjectPin(env, &obj_ref, OROOPOCUR, OROOPDTRA, OROOLMUPD, &object) 
          != OROSTASUC)
       /o error handling code o/ 

    /o get the null structure of the ADT instance o/
    if (OCIObjectGetInd(gp, object, &null_struct) != OROSTASUC)
       /o error handling code o/ 

    /o 
     o Get the type of the ADT instance
     o/

    /o find out the type of the ADT instance o/
    if (oriogto(env, object, &adt_ref) != OROSTASUC)
       /o error handling code o/ 

    /o display the object o/
    display(adt_ref, object, null_struct, attr_names, 0, attr_names_lengths,
                     attr_names_indexes, 0);

    /o After the object is displayed, the program waits for the user to 
     o respond.  The user modifies the values of an attribute and the
     o program generates a path expression for the attribute and calls 
     o OCIObjectSetAttr() to set the value. 
     o/

    if (OCIObjectSetAttr(env, object, null_struct, adt_ref, 
                (text **)attr_names, (ub4 *)attr_name_lengths, 
                attr_names_count, (ub4 *)attr_array_indexes, 
                attr_array_indexes_count, 
                (void *)0, FALSE, (void *)value) != OROSTASUC)
       /o error handling code o/ 

    END OF EXAMPLE 1

  NOTES

    This file has been subsetted to contain only the routines that will
    be in the first release.

  MODIFIED
    dmukhin    06/29/05  - ANSI prototypes; miscellaneous cleanup 
    srseshad   03/12/03  - convert oci public api to ansi
    aahluwal   06/03/02  - bug 2360115
    bpalaval   02/09/01  - Change text to oratext.
    whe        09/01/99 -  976457:check __cplusplus for C++ code
    sthakur    09/18/97 -  collection indexing not supported
    cxcheng    08/05/97 -  fix compile with short names
    skrishna   03/18/97 -  fix ifdef for supporting ansi and k&r proto-types
    cxcheng    02/06/97 -  take out short name support except with SLSHORTNAME
    cxcheng    10/17/96 -  final renaming of functions
    jboonleu   10/07/96 -  beautify with OCI long names
    cxcheng    10/07/96 -  change short names to long names for readability
    jboonleu   09/27/96 -  fix lint
    jwijaya    07/03/96 -  add ANSI prototypes
    jboonleu   04/13/95 -  new interface
    jwijaya    10/11/94 -  fix the sccs header and add namespace
    tanguyen   08/22/94 -  fix example 
    tanguyen   08/09/94 -  remove Sccsid declaration 
    tanguyen   07/20/94 -  fix OCIObjectSetAttr and OCIObjectGetAttr to 
                           use position descriptor 
    tanguyen   07/18/94 -  change 'object' type to become ptr to object 
    tanguyen   06/30/94 -  Fix the ORID_ORACLE ifdef 
    tanguyen   06/27/94 -  update to template format 
    skotsovo   05/12/94 -  replace ado with attribute position 
    jweisz     05/11/94 -  test new checkin facility 
    jwijaya    05/05/94 - orienv/ref/typ -> oroenv/ref/typ
    jwijaya    02/07/94 - Creation

*/

#ifndef ORATYPES
#include <oratypes.h>
#endif
#ifndef ORO_ORACLE
#include <oro.h>
#endif
#ifndef OCI_ORACLE
#include <oci.h>
#endif

#ifndef ORID_ORACLE
#define ORID_ORACLE

#ifdef SLSHORTNAME

#define OCIObjectSetAttr oridset
#define OCIObjectGetAttr oridget

#endif /* SLSHORTNAME */

/*---------------------------------------------------------------------------*/
/*                           PUBLIC FUNCTIONS                                */
/*---------------------------------------------------------------------------*/

/*-------------------------- OCIObjectSetAttr ----------------------------*/
sword OCIObjectSetAttr(    OCIEnv *env, OCIError *err, void  *instance, 
                  void  *null_struct, struct OCIType *tdo, 
                  const oratext **names, const ub4 *lengths, 
                  const ub4 name_count, const ub4 *indexes, 
                  const ub4 index_count, const OCIInd null_status, 
                  const void  *attr_null_struct, const void  *attr_value    );
/*
   NAME: OCIObjectSetAttr - ORID SET value
   PARAMETERS:
        env  (IN) - OCI environment handle initialized in object mode
        err  (IN) - error handle. If there is an error, it is
                        recorded in 'err' and this function returns OCI_ERROR.
                        The error recorded in 'err' can be retrieved by calling
                        OCIErrorGet().
        instance    (IN) - pointer to an ADT instance
        null_struct (IN) - the null structure of the ADT instance or array
        tdo         (IN) - pointer to the TDO
        names       (IN) - array of attribute names. This is used to specify
                           the names of the attributes in the path expression.
        lengths     (IN) - array of lengths of attribute names.
        name_count  (IN) - number of element in the array 'names'.
        indexes     (IN) [OPTIONAL] - currently NOT SUPPORTED, pass (ub4 *)0.
        index_count (IN) [OPTIONAL] - currently NOT SUPPORTED, pass (ub4)0.
        attr_null_status (IN) - the null status of the attribute if the type of
                                 attribute is primitive.
        attr_null_struct (IN) - the null structure of an ADT or collection
                                 attribute.
        attr_value       (IN) - pointer to the attribute value.
   REQUIRES:
   DESCRIPTION:
        This function set the attribute of the given object with the given 
        value.  The position of the attribute is specified as a path 
        expression which is an array of names and an array of indexes. 
   RETURNS:
        one of OROSTA*
   EXAMPLES:
        For path expression stanford.cs.stu[5].addr, the arrays will look like
          names = {"stanford", "cs", "stu", "addr"} 
          lengths = {8, 2, 3, 4}
          indexes = {5}
        
        Also see the above example.
 */

/*-------------------------- OCIObjectGetAttr ----------------------------*/
sword OCIObjectGetAttr(    OCIEnv *env, OCIError *err, void  *instance, 
                  void  *null_struct, struct OCIType *tdo, 
                  const oratext **names, const ub4 *lengths, 
                  const ub4 name_count, const ub4 *indexes, 
                  const ub4 index_count, OCIInd *attr_null_status, 
                  void  **attr_null_struct, void  **attr_value, 
                  struct OCIType **attr_tdo    );
/*
   NAME: OCIObjectGetAttr - ORID GET value
   PARAMETERS:
        env  (IN) - OCI environment handle initialized in object mode
        err  (IN) - error handle. If there is an error, it is
                        recorded in 'err' and this function returns OCI_ERROR.
                        The error recorded in 'err' can be retrieved by calling
                        OCIErrorGet().
        instance    (IN) - pointer to an ADT instance 
        null_struct (IN) - the null structure of the ADT instance or array
        tdo         (IN) - pointer to the TDO 
        names       (IN) - array of attribute names. This is used to specify
                           the names of the attributes in the path expression.
        lengths     (IN) - array of lengths of attribute names. 
        name_count  (IN) - number of element in the array 'names'.
        indexes     (IN) [OPTIONAL] - currently NOT SUPPORTED, pass (ub4 *)0.
        index_count (IN) [OPTIONAL] - currently NOT SUPPORTED, pass (ub4)0.
        attr_null_status (OUT) - the null status of the attribute if the type 
                                 of attribute is primitive. 
        attr_null_struct (OUT) - the null structure of an ADT or collection
                                 attribute.
        attr_value       (OUT) - pointer to the attribute value.
        attr_tdo         (OUT) - pointer to the TDO of the attribute.
   REQUIRES:
      - a valid OCI environment handle must be given.
   DESCRIPTION:
        This function gets a value from an ADT instance or from an array.
        If the parameter 'instance' points to an ADT instance, then the path
        expression specifies the location of the attribute in the ADT. 
        It is assumed that the object is pinned and that the value returned 
        is valid until the object is unpinned.
   RETURNS:
        one of OROSTA*
   EXAMPLES:
        See example in OCIObjectSetAttr(). Also see the above example.
 */

#endif /* ORID_ORACLE */