/* 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 #endif #ifndef ORO_ORACLE #include #endif #ifndef OCI_ORACLE #include #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 */