Annotation of win32/sql/oracle/include/oci/orid.h, revision 1.1
1.1 ! parser 1: /* Copyright (c) Oracle Corporation 1994, 1996, 1997, 1999. All Rights Reserved. */
! 2:
! 3: /*
! 4: Author: Tin Nguyen
! 5: Date: 02/07/94
! 6: Source documents: "Functional Specification for C Object Interface, Object
! 7: Management Subsystem", "Oracle C Coding Standards
! 8: version 2.2", and the header file template
! 9: Rule sets: the generic and .h file rule sets
! 10: Quality status: not exited
! 11: Identification tag: [ one or more letters to identify the .h file ]
! 12: Revision code: [ date of the last revision of the .h file ]
! 13:
! 14: Note to the user of this header file:
! 15:
! 16: Anything in this header file that is marked private is not supported and
! 17: must not be used. Private sections are included in the header file to
! 18: improve internal maintenance.
! 19:
! 20: NAME
! 21:
! 22: ORID - Oracle Object Interface for Dynamic Data Access
! 23:
! 24: DESCRIPTION
! 25:
! 26: This file contains declarations for C object interface functions including
! 27: the dynamic object data access operations that allow callers to dynamically
! 28: access and manipulate objects; these operations include getting and setting
! 29: attributes of an object. These dynamic object operations are for accessing
! 30: and manipulation objects whose types are not known at compile-time.
! 31:
! 32: RELATED DOCUMENTS
! 33:
! 34: Functional Specification for C Object Interface / Object Management System
! 35:
! 36: PUBLIC FUNCTIONS
! 37:
! 38: OCIObjectSetAttr - ORID SET attribute value
! 39: OCIObjectGetAttr - ORID GET attribute value
! 40:
! 41: PRIVATE FUNCTIONS
! 42:
! 43: None
! 44:
! 45: EXAMPLES
! 46:
! 47: EXAMPLE 1
! 48:
! 49: /o
! 50: o This example illustrates how an interative program can use the dynamic
! 51: o attribute access to display and modify attributes of an ADT instance.
! 52: o The interactive program does not know the type of the object at
! 53: o compile time.
! 54: o/
! 55:
! 56: void display(adt_ref, object, null_struct, names, names_count,
! 57: names_length, indexes, indexes_count)
! 58: {
! 59: /o Pin the ADT o/
! 60: if (OCIObjectPin(env, &adt_ref, OROOPOCUR, OROOPDTRA, OROOLMNON, &adt)
! 61: != OROSTASUC)
! 62: /o error handling code o/
! 63:
! 64: /o
! 65: o Call the type manager to obtain all the attributes in the object.
! 66: o Display the content of each attribute in the ADT instance. If the
! 67: o attribute is an array, display each element of the array. If the
! 68: o attribute is an ADT instance, recursively call this routine to
! 69: o display the embedded ADT instance.
! 70: o/
! 71: numAttrs = OCITypeAttrs(env, adt);
! 72: for (i= 1; i <= numAttrs; i++)
! 73: {
! 74: /o get attribute descriptor o/
! 75: if (ortgabp(env, adt, i, &ado_ref, &ado) != OROSTASUC)
! 76: /o error handling code o/
! 77:
! 78: /o get attribute name o/
! 79: names[names_count] = OCITypeElemName(env, ado,
! 80: &names_length[names_count]);
! 81:
! 82: /o dynamically get the attr o/
! 83: if (OCIObjectGetAttr(env, object, null_struct, 0, adt_ref, names,
! 84: names_length, names_count+1, indexes, indexes_count, 0,
! 85: &null, &null_info, &attr) != OROSTASUC)
! 86: /o error handling code o/
! 87:
! 88: /o check if attribute is null o/
! 89: if (null) continue;
! 90:
! 91: /o get typecode of attribute o/
! 92: typecode = OCITypeElemTypeCode(env, ado);
! 93:
! 94: /o if attribute is a varray, display each element in varray o/
! 95: if (typecode == OCI_TYPECODE_VARRAY)
! 96: {
! 97: /o get the reference to the type of the element of the array o/
! 98: if (OCITypeElemParameterizedTyper(env, ado, &attr_type_ref)
! 99: != OROSTASUC)
! 100: /o error handling code o/
! 101:
! 102: /o get the size of array o/
! 103: if (orlasiz(env, &attr_type_ref, (orlva *)attr,
! 104: &numElm) != OROSTASUC)
! 105: /o error handling code o/
! 106:
! 107: /o get the typecode of the element of the array o/
! 108: if (ortty2r(env, attr_type_ref, &typecode) != OROSTASUC)
! 109: /o error handling code o/
! 110:
! 111: /o iterate the array o/
! 112: for (j=0; j < numElm; j++)
! 113: {
! 114: /o get an element in the array o/
! 115: if (OCIObjectGetAttr(env, attr, null_info, j+1, attr_type_ref,
! 116: names, names_length, 0, indexes, 0, 0, &null, &null_info,
! 117: &element) != OROSTASUC)
! 118: /o error handling code o/
! 119:
! 120: /o check if element is null o/
! 121: if (null) continue;
! 122:
! 123: /o if attr is an ADT instance, recursively call this routine o/
! 124: if (typecode == OCI_TYPECODE_ADT || typecode ==
! 125: OCI_TYPECODE_UNNAMEDADT)
! 126: {
! 127: /o display the element as an adt o/
! 128: display(attr_type_ref, element, null_info, names, lengths,
! 129: 0, indexes, 0);
! 130: }
! 131:
! 132: /o if attribute is scalar, print the value to the screen o/
! 133: else output_to_screen(element, typecode);
! 134: }
! 135: }
! 136:
! 137: /o if attribute is an ADT instance, recursively call this routine o/
! 138: else if (typecode == OCI_TYPECODE_ADT || typecode ==
! 139: OCI_TYPECODE_UNNAMEDADT)
! 140: {
! 141: /o get the type ref of the attribute o/
! 142: if (ortgarf(env, ado, &attr_type_ref) != OROSTASUC)
! 143: /o error handling code o/
! 144:
! 145: display(attr_type_ref, attr, null_info, 0, names, 0, names_length,
! 146: indexes, 0);
! 147: }
! 148:
! 149: /o if attribute is scalar, print the value to the screen o/
! 150: else output_to_screen(attr, typecode);
! 151: }
! 152: }
! 153:
! 154: /o ******** main routine *********** o/
! 155: ....
! 156:
! 157: /o
! 158: o Allocate the arrays for storing the path expression
! 159: o/
! 160:
! 161: /o get the tdo of type 'long' o/
! 162: if (orttypget(&env, con, "SYS", sizeof("SYS"), "SINT32", sizeof("SINT32"),
! 163: OROOPDSES, &long_ref, &long_tdo) != OROSTASUC)
! 164: /o error handling code o/
! 165:
! 166: /o get the tdo of type 'varchar' o/
! 167: if (orttypget(&env, con, "SYS", sizeof("SYS"), "SQL_VARCHAR2",
! 168: sizeof("SQL_VARCHAR2"), OROOPDSES, &vchar_ref, &vchar_tdo)
! 169: != OROSTASUC)
! 170: /o error handling code o/
! 171:
! 172: /o allocate the varrays for the path expression o/
! 173: if (orlalloc(env, &vchar_ref, MAX_ARR_SIZE, &attr_names) != OROSTASUC)
! 174: /o error handling code o/
! 175:
! 176: if (orlalloc(env, &long_ref, MAX_ARR_SIZE, &attr_name_lengths)
! 177: != OROSTASUC)
! 178: /o error handling code o/
! 179:
! 180: if (orlalloc(env, &long_ref, MAX_ARR_SIZE, &attr_name_indexes)
! 181: != OROSTASUC)
! 182: /o error handling code o/
! 183:
! 184: /o
! 185: o Get an ADT instance. The ref to the ADT instance can be obtained
! 186: o by through ORI or OSCI.
! 187: o/
! 188: if (OCIObjectPin(env, &obj_ref, OROOPOCUR, OROOPDTRA, OROOLMUPD, &object)
! 189: != OROSTASUC)
! 190: /o error handling code o/
! 191:
! 192: /o get the null structure of the ADT instance o/
! 193: if (OCIObjectGetInd(gp, object, &null_struct) != OROSTASUC)
! 194: /o error handling code o/
! 195:
! 196: /o
! 197: o Get the type of the ADT instance
! 198: o/
! 199:
! 200: /o find out the type of the ADT instance o/
! 201: if (oriogto(env, object, &adt_ref) != OROSTASUC)
! 202: /o error handling code o/
! 203:
! 204: /o display the object o/
! 205: display(adt_ref, object, null_struct, attr_names, 0, attr_names_lengths,
! 206: attr_names_indexes, 0);
! 207:
! 208: /o After the object is displayed, the program waits for the user to
! 209: o respond. The user modifies the values of an attribute and the
! 210: o program generates a path expression for the attribute and calls
! 211: o OCIObjectSetAttr() to set the value.
! 212: o/
! 213:
! 214: if (OCIObjectSetAttr(env, object, null_struct, adt_ref,
! 215: (text **)attr_names, (ub4 *)attr_name_lengths,
! 216: attr_names_count, (ub4 *)attr_array_indexes,
! 217: attr_array_indexes_count,
! 218: (dvoid *)0, FALSE, (dvoid *)value) != OROSTASUC)
! 219: /o error handling code o/
! 220:
! 221: END OF EXAMPLE 1
! 222:
! 223: NOTES
! 224:
! 225: This file has been subsetted to contain only the routines that will
! 226: be in the first release.
! 227:
! 228: MODIFIED
! 229: whe 09/01/99 - 976457:check __cplusplus for C++ code
! 230: sthakur 09/18/97 - collection indexing not supported
! 231: cxcheng 08/05/97 - fix compile with short names
! 232: skrishna 03/18/97 - fix ifdef for supporting ansi and k&r proto-types
! 233: cxcheng 02/06/97 - take out short name support except with SLSHORTNAME
! 234: cxcheng 10/17/96 - final renaming of functions
! 235: jboonleu 10/07/96 - beautify with OCI long names
! 236: cxcheng 10/07/96 - change short names to long names for readability
! 237: jboonleu 09/27/96 - fix lint
! 238: jwijaya 07/03/96 - add ANSI prototypes
! 239: jboonleu 04/13/95 - new interface
! 240: jwijaya 10/11/94 - fix the sccs header and add namespace
! 241: tanguyen 08/22/94 - fix example
! 242: tanguyen 08/09/94 - remove Sccsid declaration
! 243: tanguyen 07/20/94 - fix OCIObjectSetAttr and OCIObjectGetAttr to
! 244: use position descriptor
! 245: tanguyen 07/18/94 - change 'object' type to become ptr to object
! 246: tanguyen 06/30/94 - Fix the ORID_ORACLE ifdef
! 247: tanguyen 06/27/94 - update to template format
! 248: skotsovo 05/12/94 - replace ado with attribute position
! 249: jweisz 05/11/94 - test new checkin facility
! 250: jwijaya 05/05/94 - orienv/ref/typ -> oroenv/ref/typ
! 251: jwijaya 02/07/94 - Creation
! 252:
! 253: */
! 254:
! 255: #ifndef ORATYPES
! 256: #include <oratypes.h>
! 257: #endif
! 258: #ifndef ORO_ORACLE
! 259: #include <oro.h>
! 260: #endif
! 261: #ifndef OCI_ORACLE
! 262: #include <oci.h>
! 263: #endif
! 264:
! 265: #ifndef ORID_ORACLE
! 266: #define ORID_ORACLE
! 267:
! 268: #ifdef SLSHORTNAME
! 269:
! 270: #define OCIObjectSetAttr oridset
! 271: #define OCIObjectGetAttr oridget
! 272:
! 273: #endif /* SLSHORTNAME */
! 274:
! 275: /*---------------------------------------------------------------------------*/
! 276: /* PUBLIC FUNCTIONS */
! 277: /*---------------------------------------------------------------------------*/
! 278:
! 279: /*-------------------------- OCIObjectSetAttr ----------------------------*/
! 280: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 281: sword OCIObjectSetAttr(/*_ OCIEnv *env, OCIError *err, dvoid *instance,
! 282: dvoid *null_struct, struct OCIType *tdo,
! 283: CONST text **names, CONST ub4 *lengths, CONST ub4 name_count,
! 284: CONST ub4 *indexes, CONST ub4 index_count,
! 285: CONST OCIInd null_status, CONST dvoid *attr_null_struct,
! 286: CONST dvoid *attr_value _*/);
! 287: #else /* ANSI C */
! 288: sword OCIObjectSetAttr( OCIEnv *env, OCIError *err, dvoid *instance,
! 289: dvoid *null_struct, struct OCIType *tdo,
! 290: CONST text **names, CONST ub4 *lengths, CONST ub4 name_count,
! 291: CONST ub4 *indexes, CONST ub4 index_count,
! 292: CONST OCIInd null_status, CONST dvoid *attr_null_struct,
! 293: CONST dvoid *attr_value );
! 294: #endif
! 295: /*
! 296: NAME: OCIObjectSetAttr - ORID SET value
! 297: PARAMETERS:
! 298: env (IN) - OCI environment handle initialized in object mode
! 299: err (IN) - error handle. If there is an error, it is
! 300: recorded in 'err' and this function returns OCI_ERROR.
! 301: The error recorded in 'err' can be retrieved by calling
! 302: OCIErrorGet().
! 303: instance (IN) - pointer to an ADT instance
! 304: null_struct (IN) - the null structure of the ADT instance or array
! 305: tdo (IN) - pointer to the TDO
! 306: names (IN) - array of attribute names. This is used to specify
! 307: the names of the attributes in the path expression.
! 308: lengths (IN) - array of lengths of attribute names.
! 309: name_count (IN) - number of element in the array 'names'.
! 310: indexes (IN) [OPTIONAL] - currently NOT SUPPORTED, pass (ub4 *)0.
! 311: index_count (IN) [OPTIONAL] - currently NOT SUPPORTED, pass (ub4)0.
! 312: attr_null_status (IN) - the null status of the attribute if the type of
! 313: attribute is primitive.
! 314: attr_null_struct (IN) - the null structure of an ADT or collection
! 315: attribute.
! 316: attr_value (IN) - pointer to the attribute value.
! 317: REQUIRES:
! 318: DESCRIPTION:
! 319: This function set the attribute of the given object with the given
! 320: value. The position of the attribute is specified as a path
! 321: expression which is an array of names and an array of indexes.
! 322: RETURNS:
! 323: one of OROSTA*
! 324: EXAMPLES:
! 325: For path expression stanford.cs.stu[5].addr, the arrays will look like
! 326: names = {"stanford", "cs", "stu", "addr"}
! 327: lengths = {8, 2, 3, 4}
! 328: indexes = {5}
! 329:
! 330: Also see the above example.
! 331: */
! 332:
! 333: /*-------------------------- OCIObjectGetAttr ----------------------------*/
! 334: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 335: sword OCIObjectGetAttr(/*_ OCIEnv *env, OCIError *err, dvoid *instance,
! 336: dvoid *null_struct, struct OCIType *tdo, CONST text **names,
! 337: CONST ub4 *lengths, CONST ub4 name_count,
! 338: CONST ub4 *indexes, CONST ub4 index_count,
! 339: OCIInd *attr_null_status, dvoid **attr_null_struct,
! 340: dvoid **attr_value, struct OCIType **attr_tdo _*/);
! 341: #else /* ANSI C */
! 342: sword OCIObjectGetAttr( OCIEnv *env, OCIError *err, dvoid *instance,
! 343: dvoid *null_struct, struct OCIType *tdo, CONST text **names,
! 344: CONST ub4 *lengths, CONST ub4 name_count,
! 345: CONST ub4 *indexes, CONST ub4 index_count,
! 346: OCIInd *attr_null_status, dvoid **attr_null_struct,
! 347: dvoid **attr_value, struct OCIType **attr_tdo );
! 348: #endif
! 349: /*
! 350: NAME: OCIObjectGetAttr - ORID GET value
! 351: PARAMETERS:
! 352: env (IN) - OCI environment handle initialized in object mode
! 353: err (IN) - error handle. If there is an error, it is
! 354: recorded in 'err' and this function returns OCI_ERROR.
! 355: The error recorded in 'err' can be retrieved by calling
! 356: OCIErrorGet().
! 357: instance (IN) - pointer to an ADT instance
! 358: null_struct (IN) - the null structure of the ADT instance or array
! 359: tdo (IN) - pointer to the TDO
! 360: names (IN) - array of attribute names. This is used to specify
! 361: the names of the attributes in the path expression.
! 362: lengths (IN) - array of lengths of attribute names.
! 363: name_count (IN) - number of element in the array 'names'.
! 364: indexes (IN) [OPTIONAL] - currently NOT SUPPORTED, pass (ub4 *)0.
! 365: index_count (IN) [OPTIONAL] - currently NOT SUPPORTED, pass (ub4)0.
! 366: attr_null_status (OUT) - the null status of the attribute if the type
! 367: of attribute is primitive.
! 368: attr_null_struct (OUT) - the null structure of an ADT or collection
! 369: attribute.
! 370: attr_value (OUT) - pointer to the attribute value.
! 371: attr_tdo (OUT) - pointer to the TDO of the attribute.
! 372: REQUIRES:
! 373: - a valid OCI environment handle must be given.
! 374: DESCRIPTION:
! 375: This function gets a value from an ADT instance or from an array.
! 376: If the parameter 'instance' points to an ADT instance, then the path
! 377: expression specifies the location of the attribute in the ADT.
! 378: It is assumed that the object is pinned and that the value returned
! 379: is valid until the object is unpinned.
! 380: RETURNS:
! 381: one of OROSTA*
! 382: EXAMPLES:
! 383: See example in OCIObjectSetAttr(). Also see the above example.
! 384: */
! 385:
! 386: #endif /* ORID_ORACLE */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to orid.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / sql / oracle / include / oci