Annotation of win32/sql/oracle/include/oci/orid.h, revision 1.1.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