/* 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 */
Submit an article or tip