Annotation of win32/sql/oracle/include/oci/orl.h, revision 1.1.1.1
1.1 parser 1: /* Copyright (c) 1993, 1995, 1996, 1997, 1998, 1999 by Oracle Corporation */
2:
3: /*
4: Author: Srinath Krishnaswamy
5: Date: 11/24/93
6: Source documents: "Functional Specification for C Language Mapping of
7: OTS Types, Object Management Subsystem", "Oracle C
8: Coding Standards version 2.2", and the header file
9: template
10: Rule sets: the generic and .h file rule sets
11: Quality status: not exited
12: Identification tag: [ one or more letters to identify the .h file ]
13: Revision code: 11/24/93
14:
15: NAME
16:
17: ORL - ORacle's external C Language interface to primitive OTS types
18:
19: DESCRIPTION
20:
21: This header file contains C langauge interface to the OTS primitive
22: types. The interface includes C mapping of OTS primitive types and
23: the prototype of the pre-defined operations on the primitive types.
24:
25: ***********************************************************************
26: *** NOTE: The OCI functions for objects requires the ***
27: *** application to be running in OBJECT mode. That is, during ***
28: *** process initialization OCIInitialize(), the mode ***
29: *** specified should be OBJECT mode. ***
30: ** OCIInitialize(OCI_OBJECT, ..); ***
31: ***********************************************************************
32:
33: RELATED DOCUMENTS
34:
35: [1] Krishnaswamy, Srinath and Nguyen, Tin A., "Functional Specification
36: for C Language Mapping of OTS Types, Object Management Subsystem",
37: March 1994.
38: [2] Nguyen, Tin A., "The Open Type System", Oracle Corporation,
39: February 1994.
40: [3] Klein, Jonathan D., "Large Field Management", Oracle Corporation,
41: October 1993.
42:
43: PUBLIC FUNCTIONS
44:
45: OCI - OCI functions to manipulate Oracle Number, float and decimal
46: ARITHMETIC
47: OCINumberInc - OCINumber INCrement (optimized)
48: OCINumberDec - OCINumber DECrement (optimized)
49: OCINumberAdd - OCINumber ADD numbers
50: OCINumberSub - OCINumber SUBtract numbers
51: OCINumberMul - OCINumber MULtiply numbers
52: OCINumberDiv - OCINumber DIVide numbers
53: OCINumberMod - OCINumber MODulo division
54: OCINumberIntPower - OCINumber integer PoWeR
55: OCINumberShift - OCINumber decimal ShiFT number
56: OCINumberNeg - OCINumber NEGate number
57: OCINumberAbs - OCINumber ABSolute value
58: OCINumberCeil - OCINumber CEiling of number
59: OCINumberFloor - OCINumber FLooR of number
60: OCINumberSqrt - OCINumber SQuare Root of number
61: OCINumberSign - OCINumber get SIGN of number
62: NATIVE TYPE CONVERSION
63: OCINumberToInt - OCINumber convert number TO machine-format Integer
64: OCINumberFromInt - OCINumber convert machine-format Integer TO Number
65: OCINumberToReal - OCINumber convert number TO machine-format Real
66: OCINumberFromReal - OCINumber convert machine-format Real TO Number
67: TEXT STRING CONVERSION
68: OCINumberToText - OCINumber convert number TO String
69: OCINumberFromText - OCINumber convert String TO Number
70: COMPARISON
71: OCINumberCmp - OCINumber CoMPare numbers
72: OCINumberIsZero - OCINumber comparison with ZERo
73: OCINumberIsInt - OCINumber Is an Integer
74: ASSIGNMENT
75: OCINumberAssign - OCINumber ASsiGn number
76: OCINumberSetZero - OCINumber Set number to Zero value
77: OCINumberSetPi - OCINumber Set number to Pi
78: ROUNDING
79: OCINumberTrunc - OCINumber TRUncate an Oracle number
80: OCINumberRound - OCINumber ROUnd number
81: OCINumberPrec - OCINumber round to Precision digits
82: TRANSCENDENTAL
83: OCINumberSin - OCINumber SINe
84: OCINumberArcSin - OCINumber Arc SINe
85: OCINumberHypSin - OCINumber SiNe Hyperbolic
86: OCINumberCos - OCINumber COSine
87: OCINumberArcCos - OCINumber Arc COSine
88: OCINumberHypCos - OCINumber CoSine Hyperbolic
89: OCINumberTan - OCINumber TANgent
90: OCINumberArcTan - OCINumber Arc TANgent
91: OCINumberArcTan2 - OCINumber Arc TaNgent 2
92: OCINumberHypTan - OCINumber TaNgent Hyperbolic
93: OCINumberPower - OCINumber arbitrary Base EXponentiation
94: OCINumberExp - OCINumber EXPonentiation to base e
95: OCINumberLn - OCINumber Logarithm Natural
96: OCINumberLog - OCINumber LOGarithm to arbitrary base
97:
98: OCIDate - OCI functions to manipulate OCI Date
99: OCIDateToExternal - OCIDate convert date to external form
100: OCIDateFromExternal - OCIDate convert external form of date into OCIDate
101: OCIDateAssign - OCIDate Assignment
102: OCIDateToText - OCIDate convert date TO String
103: OCIDateFromText - OCIDate convert String TO Date
104: OCIDateZoneToZone - OCIDate convert date from one time
105: Zone TO another Zone
106: OCIDateCompare - OCIDate CoMPare dates
107: OCIDateAddMonths - OCIDate ADd or subtract Months
108: OCIDateAddDays - OCIDate ADd or subtract Days
109: OCIDateLastDay - OCIDate get date of LaST day of month
110: OCIDateDaysBetween - OCIDate get number of days BeTWeen two dates
111: OCIDateNextDay - OCIDate get date of Next DaY
112: OCIDateCheck - OCIDate CHecK if the given date is valid
113: OCIDateSysDate - OCIDate get current SYStem date and time
114:
115: OCIString - OCI String functions to manipulate Variable-length string
116: OCIStringAssign - OCIString Assign string to string
117: OCIStringAssignText - OCIString Assign Text string to string
118: OCIStringResize - OCIString ReSiZe string
119: OCIStringSize - OCIString get String Size
120: OCIStringPtr - OCIString get String PoinTeR
121: OCIStringAllocSize - OCIString get Allocated SiZe
122:
123: OCIRaw - OCI Raw functions to manipulate variable-length raW
124: OCIRawAssignRaw - OCIRaw Assign Raw (of type OCIRaw*) to raw
125: (of type OCIRaw*)
126: OCIRawResize - OCIRaw Resize raw
127: OCIRawSize - OCIRaw get Raw Size
128: OCIRawPtr - OCIRaw get Raw data Pointer
129: OCIRawAllocSize - OCIRaw get Allocated Size
130:
131: OCIColl - OCI Collection generic functions. These functions can be
132: used to manipulate both variable-length array (varray) and
133: nested table.
134: OCICollSize - OCIColl return current SIZe of the given collection
135: (in number of elements)
136: OCICollMax - OCIColl return the MAXimum number of elements in the
137: collection (i.e. upper-bound)
138: OCICollGetElem - OCIColl GET pointer to the element at the given
139: position
140: OCICollAssignElem - OCIColl assign to element at given index
141: OCICollAssign - OCIColl ASsiGn collection; perform deep-copy of source
142: collection to target collection
143: OCICollAppend - OCIColl aPPend the given element to the end of the
144: collection
145: OCICollTrim - OCIColl trim (delete) the given number of elements
146: from the end of the collection
147: OCICollIsLocator - OCIColl indicates whether a collection is locator
148: based or not.
149: OCIIterCreate - OCIColl Create an ITerator to scan the collection
150: elements
151: OCIIterDelete - OCIColl Delete ITerator
152: OCIIterInit - OCIColl Initialize ITerator to scan the given collection
153: OCIIterGetCurrent - OCIColl Iterator based, get CURrent
154: collection element
155: OCIIterNext - OCIColl Iterator based, get NeXT collection element
156: OCIIterPrev - OCIColl Iterator based, get PReVious collection element
157:
158: OCITable - OCI functions to manipulate nested Table. The OCIColl*() and
159: OCITable*() functions can be used to manipulate nested table
160: OCITableDelete(i) - OCITable if element(i) exists then the element is
161: marked as deleted else the function returns false. So
162: delete's create "holes".
163: OCITableExists(i) - OCITable return true iff an element at
164: position i EXIsts
165: OCITableFirst - OCITable return the smallest value of i for which
166: exists(i) is true.
167: OCITableLast - OCITable return the largest value of i for which
168: exists(i) is true.
169: OCITableNext(i) - OCITable return pointer to the smallest position j,
170: greater than i, such that OCITableExists(j) is true
171: OCITablePrev(i) - OCITable return pointer to the largest position j,
172: less than i, such that OCITableExists(j) is true
173: OCITableSize - OCITable return current SIZe of the given nested table not
174: including deleted elements
175:
176: OCIRef - OCI functions to manipulate object Reference
177: OCIRefClear - OCIRef CLeaR or nullify a ref
178: OCIRefAssign - OCIRef ASsiGn a ref to another
179: OCIRefIsEqual - OCIRef compare two refs for EQUality
180: OCIRefIsNull - OCIRef test if a ref is NULl
181: OCIRefFromHex - OCIRef convert a Hexadecimal string TO a Ref
182: OCIRefToHex - OCIRef convert a ref to a Hexadecimal string
183: OCIRefHexSize - OCIRef get size of buffer in bytes to store hexadecimal
184: string
185:
186: OBSOLETE: to be replaced by functions from oci.h:
187:
188: ORLL - ORL functions to manipulate lob Locators
189: orllasg - ORLL AsiGn one locator to another
190: orllequ - ORLL compare two locators for EQUality
191: orlliini - ORLL Is the locator INItialized?
192: orllgsz - ORLL Get locator SiZe
193: orllgcid - ORLL Get Character set ID
194:
195: NOTE: The following are specific to FILE lobs:
196:
197: orllsnm - ORLL Set directory alias and file NaMe in the locator
198: orllgnm - ORLL Get directory alias and file NaMe from the locator
199:
200: EXAMPLES
201:
202: Examples are given in the description of each function where
203: relevant.
204:
205: NOTES
206:
207: This file has been subsetted to contain ONLY the routines that will
208: be in the first release.
209:
210: QUESTIONS
211:
212: MODIFIED
213: rkasamse 09/20/99 - lint changes
214: whe 09/01/99 - 976457:check __cplusplus for C++ code
215: hsbedi 08/11/99 - Add macro
216: rxgovind 10/14/98 - make non exposed calls (OCIRowType etc) private
217: rxgovind 06/09/98 - update OCIRowTypeCreate
218: nmantrav 05/11/98 - add OCIRowTypeGetCount
219: rxgovind 03/29/98 - add OCIRowType and OCIRowData interfaces
220: jwijaya 05/06/98 - add OCICollIsLocator
221: rxgovind 03/18/98 - opaque types: move to kolo.h
222: etucker 02/02/98 - add comments for Dec and Inc
223: etucker 01/29/98 - Finish core5 integration
224: rxgovind 11/11/97 - opaque types
225: etucker 10/28/97 - add ORLN functions for SDK
226: cxcheng 07/28/97 - remove OCILobLocator #define
227: skmishra 05/13/97 - stdcc compatibility changes
228: skrishna 04/25/97 - rename OCINumber*(): Exp Power TanHyp Zero Init
229: TanToArc Sqr Truncate and Compare
230: skotsovo 03/31/97 - remove OCILobLocatorSize
231: skrishna 03/25/97 - remove orld2i and orldi2d
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: skrishna 01/06/97 - update OCITableSize() comments
235: skrishna 12/27/96 - fix OCIDateGet/OCIDateSet
236: skrishna 12/12/96 - update OCICollGelElem comments
237: skrishna 11/07/96 - OCICollGetElem: interface change
238: skrishna 11/05/96 - add OCIDate Get/Set and OCIDateAssign
239: cxcheng 10/31/96 - change OCINumberTanHyp to OCINumberHypTan
240: cxcheng 10/30/96 - #define orll short names to long names
241: dchatter 10/26/96 - fix some OCI file long names
242: cxcheng 10/24/96 - remove unnecessary comment in front
243: cxcheng 10/14/96 - disable long name mapping for LOB functions
244: skrishna 10/13/96 - continue beautification
245: skotsovo 10/16/96 - update ocilob names
246: cxcheng 10/09/96 - add structure members in #define for date/time
247: cxcheng 10/09/96 - more lint fixes
248: skrishna 10/09/96 - continue beautification
249: cxcheng 10/09/96 - more fixes
250: skrishna 10/09/96 - change fixed-char rep. to orlvstr*
251: jwijaya 10/08/96 - continue beautification
252: jwijaya 10/07/96 - beautify
253: cxcheng 10/07/96 - more changes
254: cxcheng 10/04/96 - replace short names with long names
255: skrishna 10/01/96 - orlcsiz, orltsiz: change prototype to take errhdl
256: skrishna 09/23/96 - fix lint errors
257: skotsovo 09/23/96 - remove orllmkcur().
258: jwijaya 09/17/96 - comments on null ref
259: skrishna 09/19/96 - change orlraw format
260: skotsovo 09/19/96 - add orlliini and remove orllnul
261: skrishna 08/14/96 - orlvstr: change format to ub4 followed by text
262: jboonleu 08/06/96 - update comment
263: skotsovo 08/08/96 - revert to locators instead of descriptors as input t
264: jboonleu 07/23/96 - remove orlrcur
265: skrishna 07/06/96 - add orltsiz
266: skrishna 07/05/96 - add orld2i and orldi2d
267: jwijaya 07/03/96 - add ANSI prototypes
268: skrishna 06/27/96 - document default string format in orlds2d & orld2s
269: skrishna 06/25/96 - change max date value
270: skrishna 06/18/96 - modify orld2s() comments
271: skotsovo 06/13/96 - orll functions take lob descriptors instead of locat
272: rxgovind 06/05/96 - change prototype of orlrcur to take ocienvh
273: skrishna 05/30/96 - support collection trimming
274: skrishna 05/30/96 - remove orlralo/fre and orllalo/fre instead use
275: orionew/fre
276: skrishna 05/28/96 - add orlt*() and modify orla*()
277: skotsovo 05/23/96 - add orlbl typedefs for pro*c
278: jboonleu 05/14/96 - add orlrcur
279: rxgovind 05/08/96 - changes for 3gl callbacks
280: skotsovo 05/01/96 - in orllasg, no need to alloc orlbl*
281: skrishna 04/21/96 - merge changes from 960418 object branch into big
282: skrishna 04/17/96 - rename orlrcpy to orlrasg
283: skrishna 04/12/96 - add orlr2h and orlrh2r functions
284: skotsovo 04/15/96 - add fnt to make the lob locator current
285: skrishna 04/08/96 - change orl*() to take ocienvh* and ocierrh* instead
286: of oroenv*
287: skotsovo 03/22/96 - add locator functions
288: skotsovo 03/22/96 - add locator functions
289: skrishna 02/27/96 - remove mlslabel interface
290: skotsovo 02/20/96 - remove orlbty and use dty type instead.
291: skotsovo 02/14/96 - add text file lobs.
292: skrishna 01/31/96 - update comments of orln2r, orldchk, orlds2d & orld2s
293: skrishna 01/31/96 - change orld2s() and orln2s() to return string length
294: skrishna 01/21/96 - remove old raw interface
295: skrishna 12/14/95 - add raw interface
296: skotsovo 01/03/96 - change LOB offsets and lengths from ub4 to ubig_ora
297: to support 64 bit machines.
298: skotsovo 10/30/95 - add orlblsiz() to get lob locator size
299: skrishna 10/24/95 - move ref functions from ori and update the ref
300: functions to support variable-length ref
301: cxcheng 10/20/95 - add more comments on number versions
302: cxcheng 10/13/95 - add more number functions
303: cxcheng 08/29/95 - Support for segmented varrays
304: cxcheng 08/18/95 - modifiy orlmls structure
305: skrishna 06/06/95 - rename orln, orld, orlvs and orlva to orlnum,
306: orldat, orlvstr and orlvary respectively
307: skrishna 11/15/94 - remove orlnget() function
308: skrishna 09/20/94 - modify orldbtw() to return number of days only
309: skrishna 08/24/94 - change format string length type from ub4 to ub1
310: skrishna 07/19/94 - Rename orln2c & orlnc2n to orln2s & orlns2n
311: skrishna 06/29/94 - Add blob interface; add examples
312: skrishna 06/23/94 - Update comments and format
313: skrishna 05/19/94 - update varray append comments
314: skrishna 05/05/94 - Subsetting
315: skrishna 11/24/93 - Creation
316: */
317:
318: #ifndef ORATYPES
319: #include <oratypes.h>
320: #endif
321:
322: #ifndef ORO_ORACLE
323: #include <oro.h>
324: #endif
325:
326: #ifndef ORT_ORACLE
327: #include <ort.h>
328: #endif
329:
330: #ifndef OCI_ORACLE
331: #include <oci.h>
332: #endif
333:
334: #ifndef ORL_ORACLE
335: #define ORL_ORACLE
336:
337: /*---------------------------------------------------------------------------*/
338: /* SHORT NAMES SUPPORT SECTION */
339: /*---------------------------------------------------------------------------*/
340:
341: #ifdef SLSHORTNAME
342:
343: /* the following are short names that are only supported on IBM mainframes
344: with the SLSHORTNAME defined.
345: With this all subsequent long names will actually be substituted with
346: the short names here */
347:
348: #define OCIArray orlvary
349: #define OCIColl orlcol
350: #define OCICollAppend orlcapp
351: #define OCICollAssign orlcasg
352: #define OCICollAssignElem orlcase
353: #define OCICollGetElem orlcget
354: #define OCICollMax orlcmax
355: #define OCICollSize orlcsiz
356: #define OCICollTrim orlctrm
357: #define OCICollIsLocator orlcilc
358: #define OCIDate orldat
359: #define OCIDateAddDays orldadd
360: #define OCIDateAddMonths orldadm
361: #define OCIDateCheck orldchk
362: #define OCIDateCompare orldcmp
363: #define OCIDateDD day_orldat
364: #define OCIDateDaysBetween orldbtw
365: #define OCIDateFromText orlds2d
366: #define OCIDateLastDay orldlst
367: #define OCIDateMM mon_orldat
368: #define OCIDateNextDay orldndy
369: #define OCIDateSysDate orldsys
370: #define OCIDateTime time_orldat
371: #define OCIDateYYYY gye_orldat
372: #define OCIDateZoneToZone orldz2z
373: #define OCIIter orlcitr
374: #define OCIIterCreate orlccit
375: #define OCIIterDelete orlcdit
376: #define OCIIterGetCurrent orlcicur
377: #define OCIIterInit orlciit
378: #define OCIIterNext orlcinxt
379: #define OCIIterPrev orlciprv
380: #define OCINumber orlnum
381: #define OCINumberAbs orlnabs
382: #define OCINumberAdd orlnadd
383: #define OCINumberArcCos orlnacos
384: #define OCINumberArcSin orlnasin
385: #define OCINumberArcTan orlnatan
386: #define OCINumberAssign orlnasg
387: #define OCINumberCeil orlncel
388: #define OCINumberCos orlncos
389: #define OCINumberDiv orlndiv
390: #define OCINumberPower orlnbex
391: #define OCINumberFloor orlnflr
392: #define OCINumberFromInt orlni2n
393: #define OCINumberFromReal orlnr2n
394: #define OCINumberFromText orlns2n
395: #define OCINumberHypCos orlncsh
396: #define OCINumberHypSin orlnsnh
397: #define OCINumberSetZero orlnini
398: #define OCINumberSetPi orlnspi
399: #define OCINumberInc orlninc
400: #define OCINumberDec orlndec
401: #define OCINumberIntPower orlnpwr
402: #define OCINumberLn orlnln
403: #define OCINumberLog orlnlog
404: #define OCINumberMod orlnmod
405: #define OCINumberMul orlnmul
406: #define OCINumberNeg orlnneg
407: #define OCINumberPart orlnpart
408: #define OCINumberExp orlnexp
409: #define OCINumberRound orlnrou
410: #define OCINumberPrec orlnpre
411: #define OCINumberShift orlnsft
412: #define OCINumberSign orlnsgn
413: #define OCINumberSin orlnsin
414: #define OCINumberSqrt orlnsqr
415: #define OCINumberSub orlnsub
416: #define OCINumberTan orlntan
417: #define OCINumberHypTan orlntnh
418: #define OCINumberArcTan2 orlnatn2
419: #define OCINumberToInt orln2i
420: #define OCINumberToReal orln2r
421: #define OCINumberToText orln2s
422: #define OCINumberTrunc orlntru
423: #define OCINumberCmp orlncmp
424: #define OCINumberIsZero orlnzer
425: #define OCINumberIsInt orlnint
426: #define OCIRaw orlraw
427: #define OCIRawAllocSize orlwasz
428: #define OCIRawAssignBytes orlwabr
429: #define OCIRawAssignRaw orlwarr
430: #define OCIRawPtr orlwgrp
431: #define OCIRawResize orlwrsz
432: #define OCIRawSize orlwgsz
433: #define OCIRefAssign orlrasg
434: #define OCIRefClear orlrclr
435: #define OCIRefFromHex orlrh2r
436: #define OCIRefHexSize orlrhsz
437: #define OCIRefIsEqual orlrequ
438: #define OCIRefIsNull orlrnul
439: #define OCIRefToHex orlr2h
440: #define OCIString orlvstr
441: #define OCIStringAllocSize orlvasz
442: #define OCIStringAssign orlvass
443: #define OCIStringAssignText orlvats
444: #define OCIStringPtr orlvgsp
445: #define OCIStringResize orlvrsz
446: #define OCIStringSize orlvgsz
447: #define OCITable orltbl
448: #define OCITableDelete orltdel
449: #define OCITableExists orltexi
450: #define OCITableFirst orltfst
451: #define OCITableLast orltlst
452: #define OCITableNext orltnxt
453: #define OCITablePrev orltprv
454: #define OCITableSize orltsiz
455: #define OCITime orldtm
456: #define OCITimeHH orldtmhh
457: #define OCITimeMI orldtmmm
458: #define OCITimeSS orldtmss
459: #define OCI_LOBMODE_READONLY ORLBMORO
460: #define OCI_LOBMODE_READWRITE ORLBMORW
461:
462: #endif /* SLSHORTNAME */
463:
464: /*****************************************************************************/
465: /* NUMBER/FLOAT/DECIMAL TYPE */
466: /*****************************************************************************/
467:
468: #define OCI_NUMBER_SIZE 22
469: struct OCINumber
470: {
471: ub1 OCINumberPart[OCI_NUMBER_SIZE];
472: };
473: typedef struct OCINumber OCINumber;
474:
475: /*
476: * OCINumber - OCI Number mapping in c
477: *
478: * The OTS types: NUMBER, NUMERIC, INT, SHORTINT, REAL, DOUBLE PRECISION,
479: * FLOAT and DECIMAL are represented by OCINumber.
480: * The contents of OCINumber is opaque to clients.
481: *
482: * For binding variables of type OCINumber in OCI calls (OCIBindByName(),
483: * OCIBindByPos(), and OCIDefineByPos()) use the type code SQLT_VNU.
484: */
485:
486: /*
487: EXAMPLE
488:
489: The following example shows how to manipulate an attribute of type
490: oracle number.
491:
492: struct person
493: {
494: OCINumber sal;
495: };
496: typedef struct person person;
497:
498: OCIError *err;
499: person* joe;
500: person* tom;
501: person* debbie;
502: OCINumber *joesal;
503: OCINumber *tomsal;
504: OCINumber *debsal;
505: sword status;
506: int inum;
507: double dnum;
508: OCINumber ornum;
509: char buffer[21];
510: ub4 buflen;
511: sword result;
512:
513: /o See oci.h for an example of how to initialize OCIError.
514: o For this example, assume the OCIEnv and OCIError has been
515: o initialized.
516: o/
517:
518: /o Pin joe, tom and debbie person objects in the object cache. See ori.h
519: o for an example on pinning objects. For this example, assume that
520: o joe, tom and debbie are pointing to pinned objects.
521: o/
522: joesal = &joe->sal;
523: tomsal = &tom->sal;
524: debsal = &debbie->sal;
525:
526: /o initialize joe's salary to be $12,000 o/
527: inum = 12000;
528: status = OCINumberFromInt(err, &inum, sizeof(inum), OCI_NUMBER_SIGNED,
529: joesal);
530: if (status != OCI_SUCCESS)
531: /o goto to handle error from OCINumberFromInt o/;
532:
533: /o initialize tom's salary to be same as joe o/
534: OCINumberAssign(err, joesal, tomsal);
535:
536: /o initialize debbie's salary to be 20% more than joe's o/
537: dnum = 1.2;
538: status = OCINumberFromReal(err, &dnum, sizeof(double), &ornum);
539: if (status != OCI_SUCCESS)
540: /o goto to handle error from OCINumberFromReal o/;
541: status = OCINumberMul(err, joesal, &ornum, debsal);
542: if (status != OCI_SUCCESS) /o goto to handle error from OCINumberMul o/;
543:
544: /o give tom a 50% raise o/
545: dnum = 1.5;
546: status = OCINumberFromReal(err, &dnum, sizeof(double), &ornum);
547: if (status != OCI_SUCCESS)
548: /o goto to handle error from OCINumberFromReal o/;
549: status = OCINumberMul(err, tomsal, &ornum, tomsal);
550: if (status != OCI_SUCCESS) /o goto to handle error from OCINumberMul o/;
551:
552: /o double joe's salary o/
553: status = OCINumberAdd(err, joesal, joesal, joesal);
554: if (status != OCI_SUCCESS) /o goto to handle error from OCINumberAdd o/;
555:
556: /o get joe's salary in integer o/
557: status = OCINumberToInt(err, joesal, sizeof(inum), OCI_NUMBER_SIGNED,
558: &inum);
559: if (status != OCI_SUCCESS)/o goto to handle error from OCINumberToInt o/;
560: /o inum is set to 24000 o/
561:
562: /o get debbie's salary in double o/
563: status = OCINumberToReal(err, debsal, sizeof(dnum), &dnum);
564: if (status != OCI_SUCCESS)/o goto to handle error from OCINumberToReal o/;
565: /o dnum is set to 14400 o/
566:
567: /o print tom's salary as DEM0001`8000.00 o/
568: buflen = sizeof(buffer);
569: status = OCINumberToText(err, tomsal, "C0999G9999D99", 13,
570: "NLS_NUMERIC_CHARACTERS='.`' NLS_ISO_CURRENCY='Germany'", 54,
571: &buflen, buffer);
572: if (status != OCI_SUCCESS)/o goto to handle error from OCINumberToText o/;
573: printf("tom's salary = %s\n", buffer);
574:
575: /o compare joe and tom's salary o/
576: status = OCINumberCmp(err, joesal, tomsal, &result);
577: if (status != OCI_SUCCESS) /o goto to handle error from OCINumberCmp o/;
578: /o result is positive o/
579:
580: /o read debbie's new salary from string o/
581: status = OCINumberFromText(err, "48`000.00", 9, "99G999D99", 9,
582: "NLS_NUMERIC_CHARACTERS='.`'", 27, debsal);
583: if (status != OCI_SUCCESS)
584: /o goto to handle error from OCINumberFromText o/;
585: /o debbie's salary is now 48000.00 o/
586:
587: */
588:
589: /*----------------------------- OCINumberInc --------------------------------*/
590:
591: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
592: sword OCINumberInc(/*_ OCIError *err, OCINumber *number _*/);
593: #else /* ANSI C */
594: sword OCINumberInc( OCIError *err, OCINumber *number );
595: #endif
596: /*
597: NAME: OCINumberInc - OCINumber INCrement numbers
598: PARAMETERS:
599: err (IN/OUT) - error handle. If there is an error, it is
600: recorded in 'err' and this function returns OCI_ERROR.
601: The error recorded in 'err' can be retrieved by calling
602: OCIErrorGet().
603: number (IN/OUT) a positive Oracle number to be incremented
604: DESCRIPTION:
605: Increment Oracle number in place. It is assumed that the input is
606: an integer between 0 and 100^21-2. If the is input too large, it will
607: be treated as 0 - the result will be an Oracle number 1. If the input
608: is not a positive integer, the result will be unpredictable.
609: RETURNS:
610: OCI_SUCCESS if the function completes successfully.
611: OCI_INVALID_HANDLE if 'err' is NULL.
612: OCI_ERROR if
613: any of the number arguments is null
614: */
615:
616: /*----------------------------- OCINumberDec --------------------------------*/
617:
618: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
619: sword OCINumberDec(/*_ OCIError *err, OCINumber *number _*/);
620: #else /* ANSI C */
621: sword OCINumberDec( OCIError *err, OCINumber *number );
622: #endif
623: /*
624: NAME: OCINumberDec - OCINumber DECrement numbers
625: PARAMETERS:
626: err (IN/OUT) - error handle. If there is an error, it is
627: recorded in 'err' and this function returns OCI_ERROR.
628: The error recorded in 'err' can be retrieved by calling
629: OCIErrorGet().
630: number (IN/OUT) - a positive Oracle number to be decremented
631: DESCRIPTION:
632: Decrement Oracle number in place. It is assumed that the input is an
633: integer between 1 and 100^21-2. If the input is too large, it will be
634: treated as 1 - the result will be an Oracle number 0. If the input is
635: not a positive integer, the result will be unpredictable.
636: RETURNS:
637: OCI_SUCCESS if the function completes successfully.
638: OCI_INVALID_HANDLE if 'err' is NULL.
639: OCI_ERROR if
640: any of the number arguments is null
641: */
642:
643: /*-------------------------- OCINumberSetZero -------------------------------*/
644:
645: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
646: void OCINumberSetZero(/*_ OCIError *err, OCINumber *num _*/);
647: #else /* ANSI C */
648: void OCINumberSetZero( OCIError *err, OCINumber *num );
649: #endif
650: /*
651: NAME: OCINumberSetZero - OCINumber Set number to Zero value
652: PARAMETERS:
653: err (IN/OUT) - pointer to OCI error handle
654: num (OUT) - set to zero value
655: DESCRIPTION:
656: Initialize the given number to value 0.
657: */
658:
659: /*--------------------------- OCINumberSetPi --------------------------------*/
660:
661: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
662: void OCINumberSetPi(/*_ OCIError *err, OCINumber *num _*/);
663: #else /* ANSI C */
664: void OCINumberSetPi( OCIError *err, OCINumber *num );
665: #endif
666: /*
667: NAME: OCINumberSetPi - OCINumber Set number to Pi
668: err (IN/OUT) - pointer to OCI error handle
669: num (OUT) - set to zero value
670: DESCRIPTION:
671: Initialize the given number to value Pi.
672: */
673:
674: /*----------------------------- OCINumberAdd --------------------------------*/
675:
676: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
677: sword OCINumberAdd(/*_ OCIError *err, CONST OCINumber *number1,
678: CONST OCINumber *number2, OCINumber *result _*/);
679: #else /* ANSI C */
680: sword OCINumberAdd( OCIError *err, CONST OCINumber *number1,
681: CONST OCINumber *number2, OCINumber *result );
682: #endif
683: /*
684: NAME: OCINumberAdd - OCINumber ADD numbers
685: PARAMETERS:
686: err (IN/OUT) - error handle. If there is an error, it is
687: recorded in 'err' and this function returns OCI_ERROR.
688: The error recorded in 'err' can be retrieved by calling
689: OCIErrorGet().
690: number1, number2 (IN) - numbers to be added
691: result (OUT) - result of adding 'number1' with 'number2'
692: DESCRIPTION:
693: Add 'number1' with 'number2' and return result in 'result'.
694: RETURNS:
695: OCI_SUCCESS if the function completes successfully.
696: OCI_INVALID_HANDLE if 'err' is NULL.
697: OCI_ERROR if
698: any of the number arguments is null
699: */
700:
701: /*----------------------------- OCINumberSub --------------------------------*/
702:
703: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
704: sword OCINumberSub(/*_ OCIError *err, CONST OCINumber *number1,
705: CONST OCINumber *number2, OCINumber *result _*/);
706: #else /* ANSI C */
707: sword OCINumberSub( OCIError *err, CONST OCINumber *number1,
708: CONST OCINumber *number2, OCINumber *result );
709: #endif
710: /*
711: NAME: OCINumberSub - OCINumber SUBtract numbers
712: PARAMETERS:
713: err (IN/OUT) - error handle. If there is an error, it is
714: recorded in 'err' and this function returns OCI_ERROR.
715: The error recorded in 'err' can be retrieved by calling
716: OCIErrorGet().
717: number1, number2 (IN) - 'number2' subtracted from 'number1'
718: result (OUT) - subtraction result
719: DESCRIPTION:
720: Subtract 'number2' from 'number1' and return result in 'result'.
721: RETURNS:
722: OCI_SUCCESS if the function completes successfully.
723: OCI_INVALID_HANDLE if 'err' is NULL.
724: OCI_ERROR if
725: any of the number arguments is null
726: */
727:
728: /*----------------------------- OCINumberMul --------------------------------*/
729:
730: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
731: sword OCINumberMul(/*_ OCIError *err, CONST OCINumber *number1,
732: CONST OCINumber *number2, OCINumber *result _*/);
733: #else /* ANSI C */
734: sword OCINumberMul( OCIError *err, CONST OCINumber *number1,
735: CONST OCINumber *number2, OCINumber *result );
736: #endif
737: /*
738: NAME: OCINumberMul - OCINumber MULtiply numbers
739: PARAMETERS:
740: err (IN/OUT) - error handle. If there is an error, it is
741: recorded in 'err' and this function returns OCI_ERROR.
742: The error recorded in 'err' can be retrieved by calling
743: OCIErrorGet().
744: number1, number2 (IN) - numbers to be multiplied
745: result (OUT) - multiplication result
746: DESCRIPTION:
747: Multiply 'number1' with 'number2' and return result in 'result'.
748: RETURNS:
749: OCI_SUCCESS if the function completes successfully.
750: OCI_INVALID_HANDLE if 'err' is NULL.
751: OCI_ERROR if
752: any of the number arguments is null
753: */
754:
755: /*----------------------------- OCINumberDiv --------------------------------*/
756:
757: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
758: sword OCINumberDiv(/*_ OCIError *err, CONST OCINumber *number1,
759: CONST OCINumber *number2, OCINumber *result _*/);
760: #else /* ANSI C */
761: sword OCINumberDiv( OCIError *err, CONST OCINumber *number1,
762: CONST OCINumber *number2, OCINumber *result );
763: #endif
764: /*
765: NAME: OCINumberDiv - OCINumber DIVide numbers
766: PARAMETERS:
767: err (IN/OUT) - error handle. If there is an error, it is
768: recorded in 'err' and this function returns OCI_ERROR.
769: The error recorded in 'err' can be retrieved by calling
770: OCIErrorGet().
771: number1 (IN) - pointer to the numerator
772: number2 (IN) - pointer to the denominator
773: result (OUT) - division result
774: DESCRIPTION:
775: Divide 'number1' by 'number2' and return result in 'result'.
776: RETURNS:
777: OCI_SUCCESS if the function completes successfully.
778: OCI_INVALID_HANDLE if 'err' is NULL.
779: OCI_ERROR if
780: any of the number arguments is null
781: underflow errorr
782: overflow errorr
783: divide by zero errorr
784: */
785:
786: /*----------------------------- OCINumberMod --------------------------------*/
787:
788: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
789: sword OCINumberMod(/*_ OCIError *err, CONST OCINumber *number1,
790: CONST OCINumber *number2, OCINumber *result _*/);
791: #else /* ANSI C */
792: sword OCINumberMod( OCIError *err, CONST OCINumber *number1,
793: CONST OCINumber *number2, OCINumber *result );
794: #endif
795: /*
796: NAME: OCINumberMod - OCINumber MODulous
797: PARAMETERS:
798: err (IN/OUT) - error handle. If there is an error, it is
799: recorded in 'err' and this function returns OCI_ERROR.
800: The error recorded in 'err' can be retrieved by calling
801: OCIErrorGet().
802: number1 (IN) - pointer to the numerator
803: number2 (IN) - pointer to the denominator
804: result (OUT) - remainder of the result
805: DESCRIPTION:
806: Finds the remainder of the division of two Oracle numbers.
807: RETURNS:
808: OCI_SUCCESS if the function completes successfully.
809: OCI_INVALID_HANDLE if 'err' is NULL.
810: OCI_ERROR if
811: any of the number arguments is null
812: divide by zero errorr
813: */
814:
815: /*------------------------ OCINumberIntPower --------------------------------*/
816:
817: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
818: sword OCINumberIntPower(/*_ OCIError *err, CONST OCINumber *base,
819: CONST sword exp, OCINumber *result _*/);
820: #else /* ANSI C */
821: sword OCINumberIntPower( OCIError *err, CONST OCINumber *base,
822: CONST sword exp, OCINumber *result );
823: #endif
824: /*
825: NAME: OCINumberIntPower - OCINumber takes an arbitary base to an arbitary
826: integer PoWeR
827: PARAMETERS:
828: err (IN/OUT) - error handle. If there is an error, it is
829: recorded in 'err' and this function returns OCI_ERROR.
830: The error recorded in 'err' can be retrieved by calling
831: OCIErrorGet().
832: base (IN) - base of the exponentiation
833: exp (IN) - exponent to which the base is to be raised
834: result (OUT) - output of exponentiation
835: DESCRIPTION:
836: Takes an arbitary base to an arbitary integer power.
837: RETURNS:
838: OCI_SUCCESS if the function completes successfully.
839: OCI_INVALID_HANDLE if 'err' is NULL.
840: OCI_ERROR if
841: any of the number arguments is null
842: */
843:
844: /*-------------------------- OCINumberShift ---------------------------------*/
845:
846: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
847: sword OCINumberShift(/*_ OCIError *err, CONST OCINumber *number,
848: CONST sword nDig, OCINumber *result _*/);
849: #else /* ANSI C */
850: sword OCINumberShift( OCIError *err, CONST OCINumber *number,
851: CONST sword nDig, OCINumber *result );
852: #endif
853: /*
854: NAME: OCINumberShift - OCINumber multiplies by a power of 10.
855:
856: PARAMETERS:
857: err (IN/OUT) - error handle. If there is an error, it is
858: recorded in 'err' and this function returns OCI_ERROR.
859: The error recorded in 'err' can be retrieved by calling
860: OCIErrorGet().
861: number (IN) - Oracle Number to be shifted.
862: nDig (IN) - number of decimal places to shift.
863: result (OUT) - shift result.
864: DESCRIPTION:
865: Multiplies number by 10^NDig and sets product to the result.
866: RETURNS:
867: OCI_SUCCESS if the function completes successfully.
868: OCI_INVALID_HANDLE if 'err' is NULL.
869: OCI_ERROR if
870: any of the number arguments is null
871: */
872:
873: /*----------------------------- OCINumberNeg --------------------------------*/
874:
875: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
876: sword OCINumberNeg(/*_ OCIError *err, CONST OCINumber *number,
877: OCINumber *result _*/);
878: #else /* ANSI C */
879: sword OCINumberNeg( OCIError *err, CONST OCINumber *number,
880: OCINumber *result );
881: #endif
882: /*
883: NAME: OCINumberNeg - OCINumber NEGate number
884: PARAMETERS:
885: err (IN/OUT) - error handle. If there is an error, it is
886: recorded in 'err' and this function returns OCI_ERROR.
887: The error recorded in 'err' can be retrieved by calling
888: OCIErrorGet().
889: number (IN) - number to be negated
890: result (OUT) - will contain negated value of 'number'
891: DESCRIPTION:
892: Negates an Oracle number.
893: RETURNS:
894: OCI_SUCCESS if the function completes successfully.
895: OCI_INVALID_HANDLE if 'err' is NULL.
896: OCI_ERROR if
897: any of the number arguments is null
898: */
899:
900: /*------------------------- OCINumberToText ---------------------------------*/
901:
902: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
903: sword OCINumberToText(/*_ OCIError *err, CONST OCINumber *number,
904: CONST text *fmt, ub4 fmt_length,
905: CONST text *nls_params, ub4 nls_p_length,
906: ub4 *buf_size, text *buf _*/);
907: #else /* ANSI C */
908: sword OCINumberToText( OCIError *err, CONST OCINumber *number,
909: CONST text *fmt, ub4 fmt_length,
910: CONST text *nls_params, ub4 nls_p_length,
911: ub4 *buf_size, text *buf );
912: #endif
913: /*
914: NAME: OCINumberToText - OCINumber convert number TO String
915: PARAMETERS:
916: err (IN/OUT) - error handle. If there is an error, it is
917: recorded in 'err' and this function returns OCI_ERROR.
918: The error recorded in 'err' can be retrieved by calling
919: OCIErrorGet().
920: number (IN) - Oracle number to be converted
921: fmt (IN) - conversion format
922: fmt_length (IN) - length of the 'fmt' parameter
923: nls_params (IN) - nls format specification, if null string
924: i.e. (text *)0, then the default parameters for the
925: session is used
926: nls_p_length (IN) - length of the 'nls_params' parameter
927: buf_size (IN/OUT) - size of the buffer must be passed as input by
928: the caller, this function will return the length of the
929: resulting string in bytes via this parameter. The length
930: does not include the terminating null ('\0').
931: buf (OUT) - buffer into which the converted string is placed. The
932: resulting string is null terminated.
933: DESCRIPTION:
934: Converts the given number to a character string
935: according to the specified format. Refer to "TO_NUMBER" conversion
936: function described in "Oracle SQL Language Reference Manual" for a
937: description of format and NLS parameters.
938: The converted number string is stored in the buffer 'buf', up to
939: a max of '*buf_size' bytes. Length of the resulting string is
940: returned via 'buf_size'.
941: RETURNS:
942: OCI_SUCCESS if the function completes successfully.
943: OCI_INVALID_HANDLE if 'err' is NULL.
944: OCI_ERROR if
945: 'number' or 'buf' is null
946: buffer too small
947: invalid format
948: invalid nls format
949: number to text translation for the given format causes overflow
950: */
951:
952: /*-------------------------- OCINumberFromText ------------------------------*/
953:
954: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
955: sword OCINumberFromText(/*_ OCIError *err, CONST text *str,
956: ub4 str_length, CONST text *fmt, ub4 fmt_length,
957: CONST text *nls_params, ub4 nls_p_length,
958: OCINumber *number _*/);
959: #else /* ANSI C */
960: sword OCINumberFromText( OCIError *err, CONST text *str,
961: ub4 str_length, CONST text *fmt, ub4 fmt_length,
962: CONST text *nls_params, ub4 nls_p_length,
963: OCINumber *number );
964: #endif
965: /*
966: NAME: OCINumberFromText - OCINumber convert String TO Number
967: PARAMETERS:
968: err (IN/OUT) - error handle. If there is an error, it is
969: recorded in 'err' and this function returns OCI_ERROR.
970: The error recorded in 'err' can be retrieved by calling
971: OCIErrorGet().
972: str (IN) - input string to be converted to Oracle number
973: str_length (IN) - size of the input string
974: fmt (IN) - conversion format
975: fmt_length (IN) - length of the 'fmt' parameter
976: nls_params (IN) - nls format specification, if null string
977: i.e. (text *)0, then the default parameters for the
978: session is used
979: nls_p_length (IN) - length of the 'nls_params' parameter
980: number (OUT) - given string converted to number
981: DESCRIPTION:
982: Converts the given string to a number
983: according to the specified format. Refer to "TO_NUMBER" conversion
984: function described in "Oracle SQL Language Reference Manual" for a
985: description of format and NLS parameters.
986: RETURNS:
987: OCI_SUCCESS if the function completes successfully.
988: OCI_INVALID_HANDLE if 'err' is NULL.
989: OCI_ERROR if
990: 'number' or 'str' is null
991: 'str_length' is 0
992: invalid format
993: invalid nls format
994: invalid input string
995: */
996:
997: /*-------------------------- OCINumberToInt ---------------------------------*/
998:
999: #define OCI_NUMBER_UNSIGNED 0 /* Unsigned type -- ubX */
1000: #define OCI_NUMBER_SIGNED 2 /* Signed type -- sbX */
1001:
1002: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1003: sword OCINumberToInt(/*_ OCIError *err, CONST OCINumber *number,
1004: uword rsl_length, uword rsl_flag, dvoid *rsl _*/);
1005: #else /* ANSI C */
1006: sword OCINumberToInt( OCIError *err, CONST OCINumber *number,
1007: uword rsl_length, uword rsl_flag, dvoid *rsl );
1008: #endif
1009: /*
1010: NAME: OCINumberToInt - OCINumber convert number TO Integer
1011: PARAMETERS:
1012: err (IN/OUT) - error handle. If there is an error, it is
1013: recorded in 'err' and this function returns OCI_ERROR.
1014: The error recorded in 'err' can be retrieved by calling
1015: OCIErrorGet().
1016: number (IN) - number to be converted
1017: rsl_length (IN) - size of the desired result
1018: rsl_s_flag (IN) - flag denoting the desired sign of the output; valid
1019: values are OCI_NUMBER_UNSIGNED, OCI_NUMBER_SIGNED
1020: rsl (OUT) - pointer to space for the result
1021: DESCRIPTION:
1022: Native type conversion function.
1023: Converts the given Oracle number into an xbx (e.g. ub2, ub4, sb2 etc.)
1024: RETURNS:
1025: OCI_SUCCESS if the function completes successfully.
1026: OCI_INVALID_HANDLE if 'err' is NULL.
1027: OCI_ERROR if
1028: 'number' or 'rsl' is null
1029: integer value of 'number' is too big -- overflow
1030: integer value of 'number' is too small -- underflow
1031: invalid sign flag value ('rsl_s_flag')
1032: */
1033:
1034: /*--------------------------- OCINumberFromInt ------------------------------*/
1035:
1036: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1037: sword OCINumberFromInt(/*_ OCIError *err, CONST dvoid *inum, uword inum_length,
1038: uword inum_s_flag, OCINumber *number _*/);
1039: #else /* ANSI C */
1040: sword OCINumberFromInt( OCIError *err, CONST dvoid *inum, uword inum_length,
1041: uword inum_s_flag, OCINumber *number );
1042: #endif
1043: /*
1044: NAME: OCINumberFromInt - OCINumber convert Integer TO Number
1045: PARAMETERS:
1046: err (IN/OUT) - error handle. If there is an error, it is
1047: recorded in 'err' and this function returns OCI_ERROR.
1048: The error recorded in 'err' can be retrieved by calling
1049: OCIErrorGet().
1050: inum (IN) - pointer to the integer to be converted
1051: inum_length (IN) - size of the integer
1052: inum_s_flag (IN) - flag that designates the sign of the integer; valid
1053: values are OCI_NUMBER_UNSIGNED, OCI_NUMBER_SIGNED
1054: number (OUT) - given integer converted to Oracle number
1055: DESCRIPTION:
1056: Native type conversion function. Converts any Oracle standard
1057: machine-native integer type (xbx) to an Oracle number.
1058: RETURNS:
1059: OCI_SUCCESS if the function completes successfully.
1060: OCI_INVALID_HANDLE if 'err' is NULL.
1061: OCI_ERROR if
1062: 'number' or 'inum' is null
1063: integer too BIG -- the number is too large to fit into an Oracle
1064: number
1065: invalid sign flag value ('inum_s_flag')
1066: */
1067:
1068: /*------------------------- OCINumberToReal ---------------------------------*/
1069:
1070: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1071: sword OCINumberToReal(/*_ OCIError *err, CONST OCINumber *number,
1072: uword rsl_length, dvoid *rsl _*/);
1073: #else /* ANSI C */
1074: sword OCINumberToReal( OCIError *err, CONST OCINumber *number,
1075: uword rsl_length, dvoid *rsl );
1076: #endif
1077: /*
1078: NAME: OCINumberToReal - OCINumber convert number TO Real
1079: PARAMETERS:
1080: err (IN/OUT) - error handle. If there is an error, it is
1081: recorded in 'err' and this function returns OCI_ERROR.
1082: The error recorded in 'err' can be retrieved by calling
1083: OCIErrorGet().
1084: number (IN) - number to be converted
1085: rsl_length (IN) - is the size of the desired result,
1086: sizeof( float | double | long double)
1087: rsl (OUT) - pointer to space for storing the result
1088: DESCRIPTION:
1089: Native type conversion function. Converts an Oracle number into a
1090: machine-native real type. This function only converts numbers up to
1091: LDBL_DIG, DBL_DIG, or FLT_DIG digits of precision and removes
1092: trailing zeroes. The above constants are defined in float.h
1093: RETURNS:
1094: OCI_SUCCESS if the function completes successfully.
1095: OCI_INVALID_HANDLE if 'err' is NULL.
1096: OCI_ERROR if
1097: 'number' or 'rsl' is null
1098: 'rsl_length' is 0
1099: */
1100:
1101: /*-------------------------- OCINumberFromReal ------------------------------*/
1102:
1103: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1104: sword OCINumberFromReal(/*_ OCIError *err, CONST dvoid *rnum,
1105: uword rnum_length, OCINumber *number _*/);
1106: #else /* ANSI C */
1107: sword OCINumberFromReal( OCIError *err, CONST dvoid *rnum,
1108: uword rnum_length, OCINumber *number );
1109: #endif
1110: /*
1111: NAME: OCINumberFromReal - OCINumber convert Real TO Number
1112: PARAMETERS:
1113: err (IN/OUT) - error handle. If there is an error, it is
1114: recorded in 'err' and this function returns OCI_ERROR.
1115: The error recorded in 'err' can be retrieved by calling
1116: OCIErrorGet().
1117: rnum (IN) - pointer to the floating point number to be converted
1118: rnum_length (IN) - size of the desired result, i.e.
1119: sizeof({float | double | long double})
1120: number (OUT) - given float converted to Oracle number
1121: DESCRIPTION:
1122: Native type conversion function. Converts a machine-native floating
1123: point type to an Oracle number.
1124: RETURNS:
1125: OCI_SUCCESS if the function completes successfully.
1126: OCI_INVALID_HANDLE if 'err' is NULL.
1127: OCI_ERROR if
1128: 'number' or 'rnum' is null
1129: 'rnum_length' is 0
1130: */
1131:
1132: /*----------------------------- OCINumberCmp --------------------------------*/
1133:
1134: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1135: sword OCINumberCmp(/*_ OCIError *err, CONST OCINumber *number1,
1136: CONST OCINumber *number2, sword *result _*/);
1137: #else /* ANSI C */
1138: sword OCINumberCmp( OCIError *err, CONST OCINumber *number1,
1139: CONST OCINumber *number2, sword *result );
1140: #endif
1141: /*
1142: NAME: OCINumberCmp - OCINumber CoMPare numbers
1143: PARAMETERS:
1144: err (IN/OUT) - error handle. If there is an error, it is
1145: recorded in 'err' and this function returns OCI_ERROR.
1146: The error recorded in 'err' can be retrieved by calling
1147: OCIErrorGet().
1148: number1, number2 (IN) - numbers to be compared
1149: result (OUT) - 0 if equal, negative if number1 < number2,
1150: positive if number1 > number2
1151: DESCRIPTION:
1152: The function OCINumberCmp compares two numbers.
1153: RETURNS:
1154: OCI_SUCCESS if the function completes successfully.
1155: OCI_INVALID_HANDLE if 'err' is NULL.
1156: OCI_ERROR if
1157: 'number1' or 'number2' or 'result' is null
1158: */
1159:
1160: /*---------------------------- OCINumberSign --------------------------------*/
1161:
1162: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1163: sword OCINumberSign(/*_ OCIError *err, CONST OCINumber *number,
1164: sword *result _*/);
1165: #else /* ANSI C */
1166: sword OCINumberSign( OCIError *err, CONST OCINumber *number,
1167: sword *result );
1168: #endif
1169: /*
1170: NAME: OCINumberSign - OCINumber obtains SiGN of an Oracle number
1171: PARAMETERS:
1172: err (IN/OUT) - error handle. If there is an error, it is
1173: recorded in 'err' and this function returns OCI_ERROR.
1174: The error recorded in 'err' can be retrieved by calling
1175: OCIErrorGet().
1176: number (IN) - number whose sign is returned
1177: result (OUT) - 0 if number == 0, -1 if number < 0,
1178: 1 if number > 0
1179: DESCRIPTION:
1180: Obtains sign of an Oracle number
1181: RETURNS:
1182: OCI_SUCCESS if the function completes successfully.
1183: OCI_INVALID_HANDLE if 'err' is NULL.
1184: OCI_ERROR if
1185: 'number' or 'result' is null
1186: */
1187:
1188: /*---------------------------- OCINumberIsZero ------------------------------*/
1189:
1190: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1191: sword OCINumberIsZero(/*_ OCIError *err, CONST OCINumber *number,
1192: boolean *result _*/);
1193: #else /* ANSI C */
1194: sword OCINumberIsZero( OCIError *err, CONST OCINumber *number,
1195: boolean *result );
1196: #endif
1197: /*
1198: NAME: OCINumberIsZero - OCINumber comparison with ZERo
1199: PARAMETERS:
1200: err (IN/OUT) - error handle. If there is an error, it is
1201: recorded in 'err' and this function returns OCI_ERROR.
1202: The error recorded in 'err' can be retrieved by calling
1203: OCIErrorGet().
1204: number (IN) - numbers to be compared
1205: result (OUT) - set to TRUE if equal to zero else FALSE
1206: DESCRIPTION:
1207: Test if the given number is equal to zero.
1208: RETURNS:
1209: OCI_SUCCESS if the function completes successfully.
1210: OCI_INVALID_HANDLE if 'err' is NULL.
1211: OCI_ERROR if
1212: 'number' or 'result' is null
1213: */
1214:
1215: /*---------------------------- OCINumberIsInt -------------------------------*/
1216:
1217: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1218: sword OCINumberIsInt(/*_ OCIError *err, CONST OCINumber *number,
1219: boolean *result _*/);
1220: #else /* ANSI C */
1221: sword OCINumberIsInt( OCIError *err, CONST OCINumber *number,
1222: boolean *result );
1223: #endif
1224: /*
1225: NAME: OCINumberIsInt - OCINumber Is Integer value.
1226: PARAMETERS:
1227: err (IN/OUT) - error handle. If there is an error, it is
1228: recorded in 'err' and this function returns OCI_ERROR.
1229: The error recorded in 'err' can be retrieved by calling
1230: OCIErrorGet().
1231: number (IN) - number to be tested
1232: result (OUT) - set to TRUE if integer value else FALSE
1233: DESCRIPTION:
1234: Test if the given number is an integer value.
1235: RETURNS:
1236: OCI_SUCCESS if the function completes successfully.
1237: OCI_INVALID_HANDLE if 'err' is NULL.
1238: OCI_ERROR if
1239: 'number' or 'result' is null
1240: */
1241:
1242: /*-------------------------- OCINumberAssign --------------------------------*/
1243:
1244: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1245: sword OCINumberAssign(/*_ OCIError *err, CONST OCINumber *from,
1246: OCINumber *to _*/);
1247: #else /* ANSI C */
1248: sword OCINumberAssign( OCIError *err, CONST OCINumber *from,
1249: OCINumber *to );
1250: #endif
1251: /*
1252: NAME: OCINumberAssign - OCINumber ASsiGn number
1253: PARAMETERS:
1254: err (IN/OUT) - error handle. If there is an error, it is
1255: recorded in 'err' and this function returns OCI_ERROR.
1256: The error recorded in 'err' can be retrieved by calling
1257: OCIErrorGet().
1258: from (IN) - number to be assigned
1259: to (OUT) - number copied into
1260: DESCRIPTION:
1261: Assign number 'from' to 'to'.
1262: RETURNS:
1263: OCI_SUCCESS if the function completes successfully.
1264: OCI_INVALID_HANDLE if 'err' is NULL.
1265: OCI_ERROR if
1266: 'from' or 'to' is null
1267: */
1268:
1269: /*----------------------------- OCINumberAbs --------------------------------*/
1270:
1271: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1272: sword OCINumberAbs(/*_ OCIError *err, CONST OCINumber *number,
1273: OCINumber *result _*/);
1274: #else /* ANSI C */
1275: sword OCINumberAbs( OCIError *err, CONST OCINumber *number,
1276: OCINumber *result );
1277: #endif
1278: /*
1279: NAME: OCINumberAbs - OCINumber compute ABSolute value
1280: PARAMETERS:
1281: err (IN/OUT) - error handle. If there is an error, it is
1282: recorded in 'err' and this function returns OCI_ERROR.
1283: The error recorded in 'err' can be retrieved by calling
1284: OCIErrorGet().
1285: number (IN) - input number
1286: result (OUT) - output which will contain the absolue value of the
1287: input number
1288: DESCRIPTION:
1289: Computes the absolute value of an Oracle number.
1290: RETURNS:
1291: OCI_SUCCESS if the function completes successfully.
1292: OCI_INVALID_HANDLE if 'err' is NULL.
1293: OCI_ERROR if
1294: any of the number arguments is null
1295: */
1296:
1297: /*---------------------------- OCINumberCeil --------------------------------*/
1298:
1299: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1300: sword OCINumberCeil(/*_ OCIError *err, CONST OCINumber *number,
1301: OCINumber *result _*/);
1302: #else /* ANSI C */
1303: sword OCINumberCeil( OCIError *err, CONST OCINumber *number,
1304: OCINumber *result );
1305: #endif
1306: /*
1307: NAME: OCINumberCeil - OCINumber compute the CEiL value of an Oracle number
1308: PARAMETERS:
1309: err (IN/OUT) - error handle. If there is an error, it is
1310: recorded in 'err' and this function returns OCI_ERROR.
1311: The error recorded in 'err' can be retrieved by calling
1312: OCIErrorGet().
1313: number (IN) - input number
1314: result (OUT) - output which will contain the ceil value of the
1315: input number
1316: DESCRIPTION:
1317: Computes the ceil value of an Oracle number.
1318: RETURNS:
1319: OCI_SUCCESS if the function completes successfully.
1320: OCI_INVALID_HANDLE if 'err' is NULL.
1321: OCI_ERROR if
1322: any of the number arguments is null
1323: */
1324:
1325: /*--------------------------- OCINumberFloor --------------------------------*/
1326:
1327: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1328: sword OCINumberFloor(/*_ OCIError *err, CONST OCINumber *number,
1329: OCINumber *result _*/);
1330: #else /* ANSI C */
1331: sword OCINumberFloor( OCIError *err, CONST OCINumber *number,
1332: OCINumber *result );
1333: #endif
1334: /*
1335: NAME: OCINumberFloor - OCINumber compute the FLooR value of an Oracle number
1336: PARAMETERS:
1337: err (IN/OUT) - error handle. If there is an error, it is
1338: recorded in 'err' and this function returns OCI_ERROR.
1339: The error recorded in 'err' can be retrieved by calling
1340: OCIErrorGet().
1341: number (IN) - input number
1342: result (OUT) - output which will contain the floor value of the
1343: input number
1344: DESCRIPTION:
1345: Computes the floor value of an Oracle number.
1346: RETURNS:
1347: OCI_SUCCESS if the function completes successfully.
1348: OCI_INVALID_HANDLE if 'err' is NULL.
1349: OCI_ERROR if
1350: any of the number arguments is null
1351: */
1352:
1353: /*----------------------------- OCINumberSqrt -------------------------------*/
1354:
1355: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1356: sword OCINumberSqrt(/*_ OCIError *err, CONST OCINumber *number,
1357: OCINumber *result _*/);
1358: #else /* ANSI C */
1359: sword OCINumberSqrt( OCIError *err, CONST OCINumber *number,
1360: OCINumber *result );
1361: #endif
1362: /*
1363: NAME: OCINumberSqrt - OCINumber compute the SQuare Root of an Oracle number
1364: PARAMETERS:
1365: err (IN/OUT) - error handle. If there is an error, it is
1366: recorded in 'err' and this function returns OCI_ERROR.
1367: The error recorded in 'err' can be retrieved by calling
1368: OCIErrorGet().
1369: number (IN) - input number
1370: result (OUT) - output which will contain the square root of the
1371: input number
1372: DESCRIPTION:
1373: Computes the square root of an Oracle number.
1374: RETURNS:
1375: OCI_SUCCESS if the function completes successfully.
1376: OCI_INVALID_HANDLE if 'err' is NULL.
1377: OCI_ERROR if
1378: any of the number arguments is null
1379: 'number' is negative
1380: */
1381:
1382: /*--------------------------- OCINumberTrunc --------------------------------*/
1383:
1384: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1385: sword OCINumberTrunc(/*_ OCIError *err, CONST OCINumber *number,
1386: sword decplace, OCINumber *result _*/);
1387: #else /* ANSI C */
1388: sword OCINumberTrunc( OCIError *err, CONST OCINumber *number,
1389: sword decplace, OCINumber *result );
1390: #endif
1391: /*
1392: NAME: OCINumberTrunc - OCINumber TRUncate an Oracle number at a
1393: specified decimal place
1394: PARAMETERS:
1395: err (IN/OUT) - error handle. If there is an error, it is
1396: recorded in 'err' and this function returns OCI_ERROR.
1397: The error recorded in 'err' can be retrieved by calling
1398: OCIErrorGet().
1399: number (IN) - input number
1400: decplace (IN) - number of decimal digits to the right of the
1401: decimal point to truncate at. Negative values are allowed.
1402: result (OUT) - output of truncation
1403: DESCRIPTION:
1404: Truncate an Oracle number at a specified decimal place
1405: RETURNS:
1406: OCI_SUCCESS if the function completes successfully.
1407: OCI_INVALID_HANDLE if 'err' is NULL.
1408: OCI_ERROR if
1409: any of the number arguments is null
1410: */
1411:
1412: /*----------------------------- OCINumberPower ------------------------------*/
1413:
1414: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1415: sword OCINumberPower(/*_ OCIError *err, CONST OCINumber *base,
1416: CONST OCINumber *number, OCINumber *result _*/);
1417: #else /* ANSI C */
1418: sword OCINumberPower( OCIError *err, CONST OCINumber *base,
1419: CONST OCINumber *number, OCINumber *result );
1420: #endif
1421: /*
1422: NAME: OCINumberPower - OCINumber takes an arbitary Base to an
1423: arbitary Power
1424: PARAMETERS:
1425: err (IN/OUT) - error handle. If there is an error, it is
1426: recorded in 'err' and this function returns OCI_ERROR.
1427: The error recorded in 'err' can be retrieved by calling
1428: OCIErrorGet().
1429: base (IN) - base of the exponentiation
1430: number (IN) - exponent to which the base is to be raised
1431: result (OUT) - output of exponentiation
1432: DESCRIPTION:
1433: Takes an arbitary base to an arbitary power.
1434: RETURNS:
1435: OCI_SUCCESS if the function completes successfully.
1436: OCI_INVALID_HANDLE if 'err' is NULL.
1437: OCI_ERROR if
1438: any of the number arguments is null
1439: */
1440:
1441: /*--------------------------- OCINumberRound --------------------------------*/
1442:
1443: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1444: sword OCINumberRound(/*_ OCIError *err, CONST OCINumber *number,
1445: sword decplace, OCINumber *result _*/);
1446: #else /* ANSI C */
1447: sword OCINumberRound( OCIError *err, CONST OCINumber *number,
1448: sword decplace, OCINumber *result );
1449: #endif
1450: /*
1451: NAME: OCINumberRound - OCINumber ROUnds an Oracle number to a specified
1452: decimal place
1453: PARAMETERS:
1454: err (IN/OUT) - error handle. If there is an error, it is
1455: recorded in 'err' and this function returns OCI_ERROR.
1456: The error recorded in 'err' can be retrieved by calling
1457: OCIErrorGet().
1458: number (IN) - round this number and return result in 'result'
1459: decplace (IN) - number of decimal digits to the right of the
1460: decimal point to round to. Negative values are allowed.
1461: result (OUT) - output of rounding
1462: DESCRIPTION:
1463: Rounds an Oracle number to a specified decimal place
1464: RETURNS:
1465: OCI_SUCCESS if the function completes successfully.
1466: OCI_INVALID_HANDLE if 'err' is NULL.
1467: OCI_ERROR if
1468: any of the number arguments is null
1469: */
1470:
1471: /*--------------------------- OCINumberPrec ---------------------------------*/
1472:
1473: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1474: sword OCINumberPrec(/*_ OCIError *err, CONST OCINumber *number,
1475: eword nDigs, OCINumber *result _*/);
1476: #else /* ANSI C */
1477: sword OCINumberPrec( OCIError *err, CONST OCINumber *number,
1478: eword nDigs, OCINumber *result );
1479: #endif
1480: /*
1481: NAME: OCINumberPrec - Rounds an Oracle number to a specified number of
1482: decimal digits.
1483: PARAMETERS:
1484: err (IN/OUT) - error handle. If there is an error, it is
1485: recorded in 'err' and this function returns OCI_ERROR.
1486: The error recorded in 'err' can be retrieved by calling
1487: OCIErrorGet().
1488: number (IN) - number for which to set precision.
1489: nDig (IN) - number of decimal digits desired in the result.
1490: result (OUT) - result.
1491: DESCRIPTION:
1492: Performs a floating point round with respect to the number
1493: of digits.
1494: RETURNS:
1495: OCI_SUCCESS if the function completes successfully.
1496: OCI_INVALID_HANDLE if 'err' is NULL.
1497: OCI_ERROR if
1498: any of the number arguments is null
1499: */
1500:
1501: /*----------------------------- OCINumberSin --------------------------------*/
1502:
1503: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1504: sword OCINumberSin(/*_ OCIError *err, CONST OCINumber *number,
1505: OCINumber *result _*/);
1506: #else /* ANSI C */
1507: sword OCINumberSin( OCIError *err, CONST OCINumber *number,
1508: OCINumber *result );
1509: #endif
1510: /*
1511: NAME: OCINumberSin - OCINumber takes the SINe of an Oracle number
1512: PARAMETERS:
1513: err (IN/OUT) - error handle. If there is an error, it is
1514: recorded in 'err' and this function returns OCI_ERROR.
1515: The error recorded in 'err' can be retrieved by calling
1516: OCIErrorGet().
1517: number (IN) - argument of the sine in radians
1518: result (OUT) - result of the sine
1519: DESCRIPTION:
1520: Takes the sine in radians of an Oracle number.
1521: RETURNS:
1522: OCI_SUCCESS if the function completes successfully.
1523: OCI_INVALID_HANDLE if 'err' is NULL.
1524: OCI_ERROR if
1525: any of the number arguments is null
1526: */
1527:
1528: /*-------------------------- OCINumberArcSin --------------------------------*/
1529:
1530: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1531: sword OCINumberArcSin(/*_ OCIError *err, CONST OCINumber *number,
1532: OCINumber *result _*/);
1533: #else /* ANSI C */
1534: sword OCINumberArcSin( OCIError *err, CONST OCINumber *number,
1535: OCINumber *result );
1536: #endif
1537: /*
1538: NAME: OCINumberArcSin - OCINumber takes the Arc SINe of an Oracle number
1539: PARAMETERS:
1540: err (IN/OUT) - error handle. If there is an error, it is
1541: recorded in 'err' and this function returns OCI_ERROR.
1542: The error recorded in 'err' can be retrieved by calling
1543: OCIErrorGet().
1544: number (IN) - argument of the arc sine
1545: result (OUT) - result of the arc sine in radians
1546: DESCRIPTION:
1547: Takes the arc sine in radians of an Oracle number.
1548: RETURNS:
1549: OCI_SUCCESS if the function completes successfully.
1550: OCI_INVALID_HANDLE if 'err' is NULL.
1551: OCI_ERROR if
1552: any of the number arguments is null
1553: 'number' is < -1 or 'number' is > 1.
1554: */
1555:
1556: /*-------------------------- OCINumberHypSin --------------------------------*/
1557:
1558: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1559: sword OCINumberHypSin(/*_ OCIError *err, CONST OCINumber *number,
1560: OCINumber *result _*/);
1561: #else /* ANSI C */
1562: sword OCINumberHypSin( OCIError *err, CONST OCINumber *number,
1563: OCINumber *result );
1564: #endif
1565: /*
1566: NAME: OCINumberHypSin - OCINumber takes the SiNe Hyperbolic of an
1567: Oracle number
1568: PARAMETERS:
1569: err (IN/OUT) - error handle. If there is an error, it is
1570: recorded in 'err' and this function returns OCI_ERROR.
1571: The error recorded in 'err' can be retrieved by calling
1572: OCIErrorGet().
1573: number (IN) - argument of the sine hyperbolic
1574: result (OUT) - result of the sine hyperbolic
1575: DESCRIPTION:
1576: Takes the hyperbolic sine of an Oracle number.
1577: RETURNS:
1578: OCI_SUCCESS if the function completes successfully.
1579: OCI_INVALID_HANDLE if 'err' is NULL.
1580: OCI_ERROR if
1581: any of the number arguments is null
1582: NOTES:
1583: An Oracle number overflow causes an unpredictable result value.
1584: */
1585:
1586: /*----------------------------- OCINumberCos --------------------------------*/
1587:
1588: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1589: sword OCINumberCos(/*_ OCIError *err, CONST OCINumber *number,
1590: OCINumber *result _*/);
1591: #else /* ANSI C */
1592: sword OCINumberCos( OCIError *err, CONST OCINumber *number,
1593: OCINumber *result );
1594: #endif
1595: /*
1596: NAME: OCINumberCos - OCINumber takes the COSine of an Oracle number
1597: PARAMETERS:
1598: err (IN/OUT) - error handle. If there is an error, it is
1599: recorded in 'err' and this function returns OCI_ERROR.
1600: The error recorded in 'err' can be retrieved by calling
1601: OCIErrorGet().
1602: number (IN) - argument of the cosine in radians
1603: result (OUT) - result of the cosine
1604: DESCRIPTION:
1605: Takes the cosine in radians of an Oracle number.
1606: RETURNS:
1607: OCI_SUCCESS if the function completes successfully.
1608: OCI_INVALID_HANDLE if 'err' is NULL.
1609: OCI_ERROR if
1610: any of the number arguments is null
1611: */
1612:
1613: /*-------------------------- OCINumberArcCos --------------------------------*/
1614:
1615: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1616: sword OCINumberArcCos(/*_ OCIError *err, CONST OCINumber *number,
1617: OCINumber *result _*/);
1618: #else /* ANSI C */
1619: sword OCINumberArcCos( OCIError *err, CONST OCINumber *number,
1620: OCINumber *result );
1621: #endif
1622: /*
1623: NAME: OCINumberArcCos - OCINumber takes the Arc COSine of an Oracle number
1624: PARAMETERS:
1625: err (IN/OUT) - error handle. If there is an error, it is
1626: recorded in 'err' and this function returns OCI_ERROR.
1627: The error recorded in 'err' can be retrieved by calling
1628: OCIErrorGet().
1629: number (IN) - argument of the arc cosine
1630: result (OUT) - result of the arc cosine in radians
1631: DESCRIPTION:
1632: Takes the arc cosine in radians of an Oracle number.
1633: RETURNS:
1634: OCI_SUCCESS if the function completes successfully.
1635: OCI_INVALID_HANDLE if 'err' is NULL.
1636: OCI_ERROR if
1637: any of the number arguments is null
1638: 'number' is < -1 or 'number' is > 1.
1639: */
1640:
1641: /*-------------------------- OCINumberHypCos --------------------------------*/
1642:
1643: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1644: sword OCINumberHypCos(/*_ OCIError *err, CONST OCINumber *number,
1645: OCINumber *result _*/);
1646: #else /* ANSI C */
1647: sword OCINumberHypCos( OCIError *err, CONST OCINumber *number,
1648: OCINumber *result );
1649: #endif
1650: /*
1651: NAME: OCINumberHypCos - OCINumber takes the CoSine Hyperbolic of an
1652: Oracle number
1653: PARAMETERS:
1654: err (IN/OUT) - error handle. If there is an error, it is
1655: recorded in 'err' and this function returns OCI_ERROR.
1656: The error recorded in 'err' can be retrieved by calling
1657: OCIErrorGet().
1658: number (IN) - argument of the cosine hyperbolic
1659: result (OUT) - result of the cosine hyperbolic
1660: DESCRIPTION:
1661: Takes the hyperbolic cosine of an Oracle number.
1662: RETURNS:
1663: OCI_SUCCESS if the function completes successfully.
1664: OCI_INVALID_HANDLE if 'err' is NULL.
1665: OCI_ERROR if
1666: any of the number arguments is null
1667: NOTES:
1668: An Oracle number overflow causes an unpredictable result value.
1669: */
1670:
1671: /*----------------------------- OCINumberTan --------------------------------*/
1672:
1673: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1674: sword OCINumberTan(/*_ OCIError *err, CONST OCINumber *number,
1675: OCINumber *result _*/);
1676: #else /* ANSI C */
1677: sword OCINumberTan( OCIError *err, CONST OCINumber *number,
1678: OCINumber *result );
1679: #endif
1680: /*
1681: NAME: OCINumberTan - OCINumber takes the TANgent of an Oracle number
1682: PARAMETERS:
1683: err (IN/OUT) - error handle. If there is an error, it is
1684: recorded in 'err' and this function returns OCI_ERROR.
1685: The error recorded in 'err' can be retrieved by calling
1686: OCIErrorGet().
1687: number (IN) - argument of the tangent in radians
1688: result (OUT) - result of the tangent
1689: DESCRIPTION:
1690: Takes the tangent in radians of an Oracle number.
1691: RETURNS:
1692: OCI_SUCCESS if the function completes successfully.
1693: OCI_INVALID_HANDLE if 'err' is NULL.
1694: OCI_ERROR if
1695: any of the number arguments is null
1696: */
1697:
1698: /*-------------------------- OCINumberArcTan --------------------------------*/
1699:
1700: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1701: sword OCINumberArcTan(/*_ OCIError *err, CONST OCINumber *number,
1702: OCINumber *result _*/);
1703: #else /* ANSI C */
1704: sword OCINumberArcTan( OCIError *err, CONST OCINumber *number,
1705: OCINumber *result );
1706: #endif
1707: /*
1708: NAME: OCINumberArcTan - OCINumber takes the Arc TANgent of an Oracle number
1709: PARAMETERS:
1710: err (IN/OUT) - error handle. If there is an error, it is
1711: recorded in 'err' and this function returns OCI_ERROR.
1712: The error recorded in 'err' can be retrieved by calling
1713: OCIErrorGet().
1714: number (IN) - argument of the arc tangent
1715: result (OUT) - result of the arc tangent in radians
1716: DESCRIPTION:
1717: Takes the arc tangent in radians of an Oracle number.
1718: RETURNS:
1719: OCI_SUCCESS if the function completes successfully.
1720: OCI_INVALID_HANDLE if 'err' is NULL.
1721: OCI_ERROR if
1722: any of the number arguments is null
1723: */
1724:
1725: /*------------------------ OCINumberArcTan2 ---------------------------------*/
1726:
1727: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1728: sword OCINumberArcTan2(/*_ OCIError *err, CONST OCINumber *number1,
1729: CONST OCINumber *number2, OCINumber *result _*/);
1730: #else /* ANSI C */
1731: sword OCINumberArcTan2( OCIError *err, CONST OCINumber *number1,
1732: CONST OCINumber *number2, OCINumber *result );
1733: #endif
1734: /*
1735: NAME: OCINumberArcTan2 - OCINumber takes the ATan2 of 2 Oracle numbers
1736: PARAMETERS:
1737: err (IN/OUT) - error handle. If there is an error, it is
1738: recorded in 'err' and this function returns OCI_ERROR.
1739: The error recorded in 'err' can be retrieved by calling
1740: OCIErrorGet().
1741: number1 (IN) - first argument of atan2(y,x) function which
1742: corresponds to 'y' parameter in the function
1743: number2 (IN) - second argument of atan2(y,x) function which
1744: corresponds to 'x' parameter in the function
1745: result (OUT) - result of the atan2() in radians
1746: DESCRIPTION:
1747: Takes the atan2(number1, number2).
1748: RETURNS:
1749: OCI_SUCCESS if the function completes successfully.
1750: OCI_INVALID_HANDLE if 'err' is NULL.
1751: OCI_ERROR if
1752: any of the number arguments is null
1753: 'number2' is 0
1754: */
1755:
1756: /*----------------------------- OCINumberHypTan -----------------------------*/
1757:
1758: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1759: sword OCINumberHypTan(/*_ OCIError *err, CONST OCINumber *number,
1760: OCINumber *result _*/);
1761: #else /* ANSI C */
1762: sword OCINumberHypTan( OCIError *err, CONST OCINumber *number,
1763: OCINumber *result );
1764: #endif
1765: /*
1766: NAME: OCINumberHypTan - OCINumber takes the TaNgent Hyperbolic of an Oracle
1767: number
1768: PARAMETERS:
1769: err (IN/OUT) - error handle. If there is an error, it is
1770: recorded in 'err' and this function returns OCI_ERROR.
1771: The error recorded in 'err' can be retrieved by calling
1772: OCIErrorGet().
1773: number (IN) - argument of the tangent hyperbolic
1774: result (OUT) - result of the tangent hyperbolic
1775: DESCRIPTION:
1776: Takes the hyperbolic tangent of an Oracle number.
1777: RETURNS:
1778: OCI_SUCCESS if the function completes successfully.
1779: OCI_INVALID_HANDLE if 'err' is NULL.
1780: OCI_ERROR if
1781: any of the number arguments is null
1782: NOTES:
1783: An Oracle number overflow causes an unpredictable result value.
1784: */
1785:
1786: /*--------------------------- OCINumberExp ----------------------------------*/
1787:
1788: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1789: sword OCINumberExp(/*_ OCIError *err, CONST OCINumber *number,
1790: OCINumber *result _*/);
1791: #else /* ANSI C */
1792: sword OCINumberExp( OCIError *err, CONST OCINumber *number,
1793: OCINumber *result );
1794: #endif
1795: /*
1796: NAME: OCINumberExp - OCINumber EXPonential
1797: PARAMETERS:
1798: err (IN/OUT) - error handle. If there is an error, it is
1799: recorded in 'err' and this function returns OCI_ERROR.
1800: The error recorded in 'err' can be retrieved by calling
1801: OCIErrorGet().
1802: number (IN) - e raised to this Oracle number power
1803: result (OUT) - output of exponentiation
1804: DESCRIPTION:
1805: Raises e to the specified Oracle number power
1806: RETURNS:
1807: OCI_SUCCESS if the function completes successfully.
1808: OCI_INVALID_HANDLE if 'err' is NULL.
1809: OCI_ERROR if
1810: any of the number arguments is null
1811: */
1812:
1813: /*----------------------------- OCINumberLn ---------------------------------*/
1814:
1815: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1816: sword OCINumberLn(/*_ OCIError *err, CONST OCINumber *number,
1817: OCINumber *result _*/);
1818: #else /* ANSI C */
1819: sword OCINumberLn( OCIError *err, CONST OCINumber *number,
1820: OCINumber *result );
1821: #endif
1822: /*
1823: NAME: OCINumberLn - OCINumber Logarithm Natural
1824: PARAMETERS:
1825: err (IN/OUT) - error handle. If there is an error, it is
1826: recorded in 'err' and this function returns OCI_ERROR.
1827: The error recorded in 'err' can be retrieved by calling
1828: OCIErrorGet().
1829: number (IN) - logarithm of this number is computed
1830: result (OUT) - logarithm result
1831: DESCRIPTION:
1832: Takes the logarithm of the given Oracle number with respect
1833: to the given base.
1834: RETURNS:
1835: OCI_SUCCESS if the function completes successfully.
1836: OCI_INVALID_HANDLE if 'err' is NULL.
1837: OCI_ERROR if
1838: any of the number arguments is null
1839: 'number' is <= 0
1840: */
1841:
1842: /*----------------------------- OCINumberLog --------------------------------*/
1843:
1844: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
1845: sword OCINumberLog(/*_ OCIError *err, CONST OCINumber *base,
1846: CONST OCINumber *number, OCINumber *result _*/);
1847: #else /* ANSI C */
1848: sword OCINumberLog( OCIError *err, CONST OCINumber *base,
1849: CONST OCINumber *number, OCINumber *result );
1850: #endif
1851: /*
1852: NAME: OCINumberLog - OCINumber LOGarithm any base
1853: PARAMETERS:
1854: err (IN/OUT) - error handle. If there is an error, it is
1855: recorded in 'err' and this function returns OCI_ERROR.
1856: The error recorded in 'err' can be retrieved by calling
1857: OCIErrorGet().
1858: base (IN) - base of the logarithm
1859: number (IN) - opearnd
1860: result (OUT) - logarithm result
1861: DESCRIPTION:
1862: Takes the logarithm with the specified base of an Oracle number.
1863: RETURNS:
1864: OCI_SUCCESS if the function completes successfully.
1865: OCI_INVALID_HANDLE if 'err' is NULL.
1866: OCI_ERROR if
1867: any of the number arguments is null
1868: 'number' is <= 0
1869: 'base' is <= 0
1870: */
1871:
1872: /*****************************************************************************/
1873: /* ORACLE DATE TYPE */
1874: /*****************************************************************************/
1875:
1876: struct OCITime
1877: {
1878: ub1 OCITimeHH; /* hours; range is 0 <= hours <=23 */
1879: ub1 OCITimeMI; /* minutes; range is 0 <= minutes <= 59 */
1880: ub1 OCITimeSS; /* seconds; range is 0 <= seconds <= 59 */
1881: };
1882: typedef struct OCITime OCITime;
1883:
1884: /*
1885: * OCITime - OCI TiMe portion of date
1886: *
1887: * This structure should be treated as an opaque structure as the format
1888: * of this structure may change. Use OCIDateGetTime/OCIDateSetTime
1889: * to manipulate time portion of OCIDate.
1890: */
1891:
1892: struct OCIDate
1893: {
1894: sb2 OCIDateYYYY; /* gregorian year; range is -4712 <= year <= 9999 */
1895: ub1 OCIDateMM; /* month; range is 1 <= month < 12 */
1896: ub1 OCIDateDD; /* day; range is 1 <= day <= 31 */
1897: OCITime OCIDateTime; /* time */
1898: };
1899: typedef struct OCIDate OCIDate;
1900:
1901: /*
1902: * OCIDate - OCI oracle Date representation in C
1903: *
1904: * OCIDate represents the C mapping of Oracle date.
1905: *
1906: * This structure should be treated as an opaque structure as the format
1907: * of this structure may change. Use OCIDateGetDate/OCIDateSetDate
1908: * to access/initialize OCIDate.
1909: *
1910: * For binding variables of type OCIDate in OCI calls (OCIBindByName(),
1911: * OCIBindByPos(), and OCIDefineByPos()) use the type code SQLT_ODT.
1912: */
1913:
1914: /*
1915: EXAMPLE
1916:
1917: The following example shows how to manipulate an attribute of type
1918: oracle date.
1919:
1920: #define FMT "Month dd, YYYY, HH:MI A.M."
1921: #define LANG "American"
1922:
1923: struct person
1924: {
1925: OCIDate start_date;
1926: };
1927: typedef struct person person;
1928:
1929: OCIError *err;
1930: person *joe;
1931: sword status; /o error status o/
1932:
1933: /o See oci.h for an example of how to initialize OCIError.
1934: o For this example, assume the OCIEnv and OCIError has been
1935: o initialized.
1936: o/
1937:
1938: /o Pin joe person object in the object cache. See ori.h
1939: o for an example on pinning objects. For this example, assume that
1940: o joe is pointing to the pinned object.
1941: o/
1942:
1943: /o set the start date of joe o/
1944: OCIDateSetTime(&joe->start_date, 8, 0, 0);
1945: OCIDateSetDate(&joe->start_date, 1990, 10, 5);
1946:
1947: /o check if the date is valid o/
1948: uword invalid;
1949: if (OCIDateCheck(err, &joe->start_date, &invalid) != OCI_SUCCESS)
1950: /o error handling code o/
1951: if (invalid)
1952: /o error handling code o/
1953:
1954: /o convert date for display purposes o/
1955: char str[100];
1956: ub4 strlen = sizeof(str);
1957: if (OCIDateToText(err, &joe->start_date, FMT, sizeof(FMT)-1, LANG,
1958: sizeof(LANG)-1, &strlen, str) != OCI_SUCCESS)
1959: /o error handling code o/
1960:
1961: */
1962:
1963: /*--------------------------- OCIDateGetTime --------------------------------*/
1964: /* void OCIDateGetTime(/o_ CONST OCIDate *date, ub1 *hour, ub1 *min,
1965: ub1 *sec _o/); */
1966: #define OCIDateGetTime(date, hour, min, sec) \
1967: { \
1968: *hour = (date)->OCIDateTime.OCITimeHH; \
1969: *min = (date)->OCIDateTime.OCITimeMI; \
1970: *sec = (date)->OCIDateTime.OCITimeSS; \
1971: }
1972: /*
1973: NAME: OCIDateGetTime - OCIDate Get Time portion of date
1974: PARAMETERS:
1975: date (IN) - Oracle date whose time data is retrieved
1976: hour (OUT) - hour value returned
1977: min (OUT) - minute value returned
1978: sec (OUT) - second value returned
1979: DESCRIPTION:
1980: Return time inforamtion stored in the given date. The time
1981: information returned is: hour, minute and seconds.
1982: RETURNS:
1983: NONE
1984: */
1985:
1986: /*--------------------------- OCIDateGetDate --------------------------------*/
1987: /* void OCIDateGetDate(/o_ CONST OCIDate *date, sb2 *year, ub1 *month,
1988: ub1 *day _o/); */
1989: #define OCIDateGetDate(date, year, month, day) \
1990: { \
1991: *year = (date)->OCIDateYYYY; \
1992: *month = (date)->OCIDateMM; \
1993: *day = (date)->OCIDateDD; \
1994: }
1995: /*
1996: NAME: OCIDateGetDate - OCIDate Get Date (year, month, day) portion of date
1997: PARAMETERS:
1998: date (IN) - Oracle date whose year, month, day data is retrieved
1999: year (OUT) - year value returned
2000: month (OUT) - month value returned
2001: day (OUT) - day value returned
2002: DESCRIPTION:
2003: Return year, month, day inforamtion stored in the given date.
2004: RETURNS:
2005: NONE
2006: */
2007:
2008: /*--------------------------- OCIDateSetTime --------------------------------*/
2009: /* void OCIDateSetTime(/o_ OCIDate *date, ub1 hour, ub1 min,
2010: ub1 sec _o/); */
2011: #define OCIDateSetTime(date, hour, min, sec) \
2012: { \
2013: (date)->OCIDateTime.OCITimeHH = hour; \
2014: (date)->OCIDateTime.OCITimeMI = min; \
2015: (date)->OCIDateTime.OCITimeSS = sec; \
2016: }
2017: /*
2018: NAME: OCIDateSetTime - OCIDate Set Time portion of date
2019: PARAMETERS:
2020: date (OUT) - Oracle date whose time data is set
2021: hour (IN) - hour value to be set
2022: min (IN) - minute value to be set
2023: sec (IN) - second value to be set
2024: DESCRIPTION:
2025: Set the date with the given time inforamtion.
2026: RETURNS:
2027: NONE
2028: */
2029:
2030: /*--------------------------- OCIDateSetDate --------------------------------*/
2031: /* void OCIDateSetDate(/o_ OCIDate *date, sb2 year, ub1 month, ub1 day _o/); */
2032: #define OCIDateSetDate(date, year, month, day) \
2033: { \
2034: (date)->OCIDateYYYY = year; \
2035: (date)->OCIDateMM = month; \
2036: (date)->OCIDateDD = day; \
2037: }
2038: /*
2039: NAME: OCIDateSetDate - OCIDate Set Date (year, month, day) portion of date
2040: PARAMETERS:
2041: date (IN) - Oracle date whose year, month, day data is set
2042: year (OUT) - year value to be set
2043: month (OUT) - month value to be set
2044: day (OUT) - day value to be set
2045: DESCRIPTION:
2046: Set the date with the given year, month, day inforamtion.
2047: RETURNS:
2048: NONE
2049: */
2050:
2051: /*--------------------------- OCIDateAssign ---------------------------------*/
2052:
2053: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2054: sword OCIDateAssign(/*_ OCIError *err, CONST OCIDate *from,
2055: OCIDate *to _*/);
2056: #else /* ANSI C */
2057: sword OCIDateAssign( OCIError *err, CONST OCIDate *from,
2058: OCIDate *to );
2059: #endif
2060: /*
2061: NAME: OCIDateAssign - OCIDate Assignment
2062: PARAMETERS:
2063: err (IN/OUT) - error handle. If there is an error, it is
2064: recorded in 'err' and this function returns OCI_ERROR.
2065: The error recorded in 'err' can be retrieved by calling
2066: OCIErrorGet().
2067: from (IN) - date to be assigned
2068: to (OUT) - lhs of assignment
2069: DESCRIPTION:
2070: Performs date assignment.
2071: RETURNS:
2072: OCI_SUCCESS
2073: */
2074:
2075: /*--------------------------- OCIDateToText ---------------------------------*/
2076:
2077: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2078: sword OCIDateToText(/*_ OCIError *err, CONST OCIDate *date,
2079: CONST text *fmt, ub1 fmt_length,
2080: CONST text *lang_name, ub4 lang_length,
2081: ub4 *buf_size, text *buf _*/);
2082: #else /* ANSI C */
2083: sword OCIDateToText( OCIError *err, CONST OCIDate *date,
2084: CONST text *fmt, ub1 fmt_length,
2085: CONST text *lang_name, ub4 lang_length,
2086: ub4 *buf_size, text *buf );
2087: #endif
2088: /*
2089: NAME: OCIDateToText - OCIDate convert date TO String
2090: PARAMETERS:
2091: err (IN/OUT) - error handle. If there is an error, it is
2092: recorded in 'err' and this function returns OCI_ERROR.
2093: The error recorded in 'err' can be retrieved by calling
2094: OCIErrorGet().
2095: date (IN) - Oracle date to be converted
2096: fmt (IN) - conversion format, if null string pointer (text*)0, then
2097: the date is converted to a character string in the
2098: date format "DD-MON-YY".
2099: fmt_length (IN) - length of the 'fmt' parameter
2100: lang_name (IN) - specifies the language in which the names and
2101: abbreviations of months and days are returned;
2102: default language of session is used if 'lang_name'
2103: is null i.e. (text *)0
2104: lang_length (IN) - length of the 'nls_params' parameter
2105: buf_size (IN/OUT) - size of the buffer; size of the resulting string
2106: is returned via this parameter
2107: buf (OUT) - buffer into which the converted string is placed
2108: DESCRIPTION:
2109: Converts the given date to a string according to the specified format.
2110: Refer to "TO_DATE" conversion function described in
2111: "Oracle SQL Language Reference Manual" for a description of format
2112: and NLS arguments. The converted null-terminated date string is
2113: stored in the buffer 'buf'.
2114:
2115: An error is reported upon overflow, e.g. trying to convert a number
2116: of value 10 using format '9' causes an overflow.
2117: RETURNS:
2118: OCI_SUCCESS if the function completes successfully.
2119: OCI_INVALID_HANDLE if 'err' is NULL.
2120: OCI_ERROR if
2121: buffer too small
2122: invalid format
2123: unknown language
2124: overflow error
2125: */
2126:
2127: /*---------------------------- OCIDateFromText ------------------------------*/
2128:
2129: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2130: sword OCIDateFromText(/*_ OCIError *err, CONST text *date_str,
2131: ub4 d_str_length, CONST text *fmt, ub1 fmt_length,
2132: CONST text *lang_name, ub4 lang_length,
2133: OCIDate *date _*/);
2134: #else /* ANSI C */
2135: sword OCIDateFromText( OCIError *err, CONST text *date_str,
2136: ub4 d_str_length, CONST text *fmt, ub1 fmt_length,
2137: CONST text *lang_name, ub4 lang_length,
2138: OCIDate *date );
2139: #endif
2140: /*
2141: NAME: OCIDateFromText - OCIDate convert String TO Date
2142: PARAMETERS:
2143: err (IN/OUT) - error handle. If there is an error, it is
2144: recorded in 'err' and this function returns OCI_ERROR.
2145: The error recorded in 'err' can be retrieved by calling
2146: OCIErrorGet().
2147: date_str (IN) - input string to be converted to Oracle date
2148: d_str_length (IN) - size of the input string, if the length is -1
2149: then 'date_str' is treated as a null terminated string
2150: fmt (IN) - conversion format; if 'fmt' is a null pointer, then
2151: the string is expected to be in 'DD-MON-YY' format.
2152: fmt_length (IN) - length of the 'fmt' parameter
2153: lang_name (IN) - language in which the names and abbreviations of
2154: days and months are specified, if null i.e. (text *)0,
2155: the default language of session is used,
2156: lang_length (IN) - length of the 'lang_name' parameter
2157: date (OUT) - given string converted to date
2158: DESCRIPTION:
2159: Converts the given string to Oracle date
2160: according to the specified format. Refer to "TO_DATE" conversion
2161: function described in "Oracle SQL Language Reference Manual" for a
2162: description of format.
2163: RETURNS:
2164: OCI_SUCCESS if the function completes successfully.
2165: OCI_INVALID_HANDLE if 'err' is NULL.
2166: OCI_ERROR if
2167: invalid format
2168: unknown language
2169: invalid input string
2170: <to be discovered>
2171: */
2172:
2173: /*----------------------------- OCIDateCompare ------------------------------*/
2174:
2175: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2176: sword OCIDateCompare(/*_ OCIError *err, CONST OCIDate *date1,
2177: CONST OCIDate *date2, sword *result _*/);
2178: #else /* ANSI C */
2179: sword OCIDateCompare( OCIError *err, CONST OCIDate *date1,
2180: CONST OCIDate *date2, sword *result );
2181: #endif
2182: /*
2183: NAME: OCIDateCompare - OCIDate CoMPare dates
2184: PARAMETERS:
2185: err (IN/OUT) - error handle. If there is an error, it is
2186: recorded in 'err' and this function returns OCI_ERROR.
2187: The error recorded in 'err' can be retrieved by calling
2188: OCIErrorGet().
2189: date1, date2 (IN) - dates to be compared
2190: result (OUT) - comparison result, 0 if equal, -1 if date1 < date2,
2191: 1 if date1 > date2
2192: DESCRIPTION:
2193: The function OCIDateCompare compares two dates. It returns -1 if date1 is
2194: smaller than date2, 0 if they are equal, and 1 if date1 is greater
2195: than date2.
2196: RETURNS:
2197: OCI_SUCCESS if the function completes successfully.
2198: OCI_INVALID_HANDLE if 'err' is NULL.
2199: OCI_ERROR if
2200: invalid date
2201: <to be discovered>
2202: */
2203:
2204: /*------------------------- OCIDateAddMonths --------------------------------*/
2205:
2206: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2207: sword OCIDateAddMonths(/*_ OCIError *err, CONST OCIDate *date, sb4 num_months,
2208: OCIDate *result _*/);
2209: #else /* ANSI C */
2210: sword OCIDateAddMonths( OCIError *err, CONST OCIDate *date, sb4 num_months,
2211: OCIDate *result );
2212: #endif
2213: /*
2214: NAME: OCIDateAddMonths - OCIDate ADd or subtract Months
2215: PARAMETERS:
2216: err (IN/OUT) - error handle. If there is an error, it is
2217: recorded in 'err' and this function returns OCI_ERROR.
2218: The error recorded in 'err' can be retrieved by calling
2219: OCIErrorGet().
2220: date (IN) - 'num_months' added or subtracted from 'date'
2221: num_months (IN) - number of months to be added or subtracted
2222: (a negative value will be subtracted)
2223: result (IN/OUT) - result of adding or subtracting to 'date'
2224: DESCRIPTION:
2225: The function OCIDateAddDays adds or subtracts num_months from the
2226: date 'date'.
2227: If the input 'date' is the last day of a month, then
2228: appropriate adjustments are made to ensure that the output date is
2229: also the last day of the month. For example, Feb. 28 + 1 month =
2230: March 31, and November 30 - 3 months = August 31. Otherwise the
2231: 'result' date has the same day component as 'date'.
2232: RETURNS:
2233: OCI_SUCCESS if the function completes successfully.
2234: OCI_INVALID_HANDLE if 'err' is NULL.
2235: OCI_ERROR if
2236: invalid date
2237: <to be discovered>
2238: */
2239:
2240: /*--------------------------- OCIDateAddDays --------------------------------*/
2241:
2242: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2243: sword OCIDateAddDays(/*_ OCIError *err, CONST OCIDate *date, sb4 num_days,
2244: OCIDate *result _*/);
2245: #else /* ANSI C */
2246: sword OCIDateAddDays( OCIError *err, CONST OCIDate *date, sb4 num_days,
2247: OCIDate *result );
2248: #endif
2249: /*
2250: NAME: OCIDateAddDays - OCIDate ADd or subtract Days
2251: PARAMETERS:
2252: err (IN/OUT) - error handle. If there is an error, it is
2253: recorded in 'err' and this function returns OCI_ERROR.
2254: The error recorded in 'err' can be retrieved by calling
2255: OCIErrorGet().
2256: date (IN) - 'num_days' added or subtracted from 'date'
2257: num_days (IN) - number of days to be added or subtracted
2258: (a negative value will be subtracted)
2259: result (IN/OUT) - result of adding or subtracting to 'date'
2260: DESCRIPTION:
2261: The function OCIDateAddDays adds or subtracts num_days from the
2262: date 'date'.
2263: RETURNS:
2264: OCI_SUCCESS if the function completes successfully.
2265: OCI_INVALID_HANDLE if 'err' is NULL.
2266: OCI_ERROR if
2267: invalid date
2268: <to be discovered>
2269: */
2270:
2271: /*--------------------------- OCIDateLastDay --------------------------------*/
2272:
2273: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2274: sword OCIDateLastDay(/*_ OCIError *err, CONST OCIDate *date,
2275: OCIDate *last_day _*/);
2276: #else /* ANSI C */
2277: sword OCIDateLastDay( OCIError *err, CONST OCIDate *date,
2278: OCIDate *last_day );
2279: #endif
2280: /*
2281: NAME: OCIDateLastDay - OCIDate get date of the LaST day of the month
2282: PARAMETERS:
2283: err (IN/OUT) - error handle. If there is an error, it is
2284: recorded in 'err' and this function returns OCI_ERROR.
2285: The error recorded in 'err' can be retrieved by calling
2286: OCIErrorGet().
2287: date (IN) - input date
2288: last_day (OUT) - last day of the month in date 'date'
2289: DESCRIPTION:
2290: The function OCIDateLastDay returns the date of the last day of the
2291: month in date 'date'.
2292: RETURNS:
2293: OCI_SUCCESS if the function completes successfully.
2294: OCI_INVALID_HANDLE if 'err' is NULL.
2295: OCI_ERROR if
2296: invalid date
2297: <to be discovered>
2298: */
2299:
2300: /*----------------------- OCIDateDaysBetween --------------------------------*/
2301:
2302: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2303: sword OCIDateDaysBetween(/*_ OCIError *err, CONST OCIDate *date1,
2304: CONST OCIDate *date2, sb4 *num_days _*/);
2305: #else /* ANSI C */
2306: sword OCIDateDaysBetween( OCIError *err, CONST OCIDate *date1,
2307: CONST OCIDate *date2, sb4 *num_days );
2308: #endif
2309: /*
2310: NAME: OCIDateDaysBetween - OCIDate get number of days BeTWeen two dates
2311: PARAMETERS:
2312: err (IN/OUT) - error handle. If there is an error, it is
2313: recorded in 'err' and this function returns OCI_ERROR.
2314: The error recorded in 'err' can be retrieved by calling
2315: OCIErrorGet().
2316: date1, date2 (IN) - input dates
2317: num_days (OUT) - number of days between date1 and date2
2318: DESCRIPTION:
2319: The function OCIDateDaysBetween returns the number of days between
2320: date1 and date2. The time is ignored in this computation.
2321: RETURNS:
2322: OCI_SUCCESS if the function completes successfully.
2323: OCI_INVALID_HANDLE if 'err' is NULL.
2324: OCI_ERROR if
2325: invalid date
2326: <to be discovered>
2327: */
2328:
2329: /*------------------------ OCIDateZoneToZone --------------------------------*/
2330:
2331: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2332: sword OCIDateZoneToZone(/*_ OCIError *err, CONST OCIDate *date1,
2333: CONST text *zon1,
2334: ub4 zon1_length, CONST text *zon2, ub4 zon2_length,
2335: OCIDate *date2 _*/);
2336: #else /* ANSI C */
2337: sword OCIDateZoneToZone( OCIError *err, CONST OCIDate *date1,
2338: CONST text *zon1,
2339: ub4 zon1_length, CONST text *zon2, ub4 zon2_length,
2340: OCIDate *date2 );
2341: #endif
2342: /*
2343: NAME: OCIDateZoneToZone - OCIDate convert date from one Zone TO another Zone
2344: PARAMETERS:
2345: err (IN/OUT) - error handle. If there is an error, it is
2346: recorded in 'err' and this function returns OCI_ERROR.
2347: The error recorded in 'err' can be retrieved by calling
2348: OCIErrorGet().
2349: date1 (IN) - date to be converted
2350: zon1 (IN) - zone of input date
2351: zon1_length (IN) - length in bytes of string 'zon1'
2352: zon2 (IN) - zone to be converted to
2353: zon2_length (IN) - length in bytes of string 'zon2'
2354: date2 (OUT) - converted date (in 'zon2')
2355: DESCRIPTION:
2356: Converts date from one time zone to another. Given date 'date1'
2357: in time zone 'zon1' returns date 'date2' in time zone 'zon2'.
2358: RETURNS:
2359: OCI_SUCCESS if the function completes successfully.
2360: OCI_INVALID_HANDLE if 'err' is NULL.
2361: OCI_ERROR if
2362: invlid date
2363: invald input time zone
2364: invald output time zone
2365: <to be discovered>
2366: */
2367:
2368: /*--------------------------- OCIDateNextDay --------------------------------*/
2369:
2370: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2371: sword OCIDateNextDay(/*_ OCIError *err, CONST OCIDate *date, CONST text *day_p,
2372: ub4 day_length, OCIDate *next_day _*/);
2373: #else /* ANSI C */
2374: sword OCIDateNextDay( OCIError *err, CONST OCIDate *date, CONST text *day_p,
2375: ub4 day_length, OCIDate *next_day );
2376: #endif
2377: /*
2378: NAME: OCIDateNextDay - OCIDate get date of Next DaY
2379: PARAMETERS:
2380: err (IN/OUT) - error handle. If there is an error, it is
2381: recorded in 'err' and this function returns OCI_ERROR.
2382: The error recorded in 'err' can be retrieved by calling
2383: OCIErrorGet().
2384: date (IN) - returned date should be later than this date
2385: day (IN) - first day of week named by this is returned
2386: day_length (IN) - length in bytes of string 'day'
2387: next_day (OUT) - first day of the week named by 'day' later than 'date'
2388: DESCRIPTION:
2389: Returns the date of the first day of the
2390: week named by 'day' that is later than date 'date'.
2391: RETURNS:
2392: OCI_SUCCESS if the function completes successfully.
2393: OCI_INVALID_HANDLE if 'err' is NULL.
2394: OCI_ERROR if
2395: invalid date
2396: invalid day
2397: <to be discovered>
2398: */
2399:
2400: /*----------------------------- OCIDateCheck --------------------------------*/
2401:
2402: /* Listing of error bits used by OCIDateCheck() */
2403: #define OCI_DATE_INVALID_DAY 0x1 /* Bad DAy */
2404: #define OCI_DATE_DAY_BELOW_VALID 0x2 /* Bad DAy Low/high bit (1=low)*/
2405: #define OCI_DATE_INVALID_MONTH 0x4 /* Bad MOnth */
2406: #define OCI_DATE_MONTH_BELOW_VALID 0x8 /* Bad MOnth Low/high bit (1=low)*/
2407: #define OCI_DATE_INVALID_YEAR 0x10 /* Bad YeaR */
2408: #define OCI_DATE_YEAR_BELOW_VALID 0x20 /* Bad YeaR Low/high bit (1=low)*/
2409: #define OCI_DATE_INVALID_HOUR 0x40 /* Bad HouR */
2410: #define OCI_DATE_HOUR_BELOW_VALID 0x80 /* Bad HouR Low/high bit (1=low)*/
2411: #define OCI_DATE_INVALID_MINUTE 0x100 /* Bad MiNute */
2412: #define OCI_DATE_MINUTE_BELOW_VALID 0x200
2413: /* Bad MiNute Low/high bit (1=low)*/
2414: #define OCI_DATE_INVALID_SECOND 0x400 /* Bad SeCond */
2415: #define OCI_DATE_SECOND_BELOW_VALID 0x800
2416: /* bad second Low/high bit (1=low)*/
2417: #define OCI_DATE_DAY_MISSING_FROM_1582 0x1000
2418: /* Day is one of those "missing" from 1582 */
2419: #define OCI_DATE_YEAR_ZERO 0x2000 /* Year may not equal zero */
2420: #define OCI_DATE_INVALID_FORMAT 0x8000 /* Bad date format input */
2421:
2422: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2423: sword OCIDateCheck(/*_ OCIError *err, CONST OCIDate *date, uword *valid _*/);
2424: #else /* ANSI C */
2425: sword OCIDateCheck( OCIError *err, CONST OCIDate *date, uword *valid );
2426: #endif
2427: /*
2428: NAME: OCIDateCheck - OCIDate CHecK if the given date is valid
2429: PARAMETERS:
2430: err (IN/OUT) - error handle. If there is an error, it is
2431: recorded in 'err' and this function returns OCI_ERROR.
2432: The error recorded in 'err' can be retrieved by calling
2433: OCIErrorGet().
2434: date (IN) - date to be checked
2435: valid (OUT) - returns zero for a valid date, otherwise
2436: the ORed combination of all error bits specified below:
2437:
2438: Macro name Bit number Error
2439: ---------- ---------- -----
2440: OCI_DATE_INVALID_DAY 0x1 Bad day
2441: OCI_DATE_DAY_BELOW_VALID 0x2 Bad DAy Low/high bit (1=low)
2442: OCI_DATE_INVALID_MONTH 0x4 Bad MOnth
2443: OCI_DATE_MONTH_BELOW_VALID 0x8 Bad MOnth Low/high bit (1=low)
2444: OCI_DATE_INVALID_YEAR 0x10 Bad YeaR
2445: OCI_DATE_YEAR_BELOW_VALID 0x20 Bad YeaR Low/high bit (1=low)
2446: OCI_DATE_INVALID_HOUR 0x40 Bad HouR
2447: OCI_DATE_HOUR_BELOW_VALID 0x80 Bad HouR Low/high bit (1=low)
2448: OCI_DATE_INVALID_MINUTE 0x100 Bad MiNute
2449: OCI_DATE_MINUTE_BELOW_VALID 0x200 Bad MiNute Low/high bit (1=low)
2450: OCI_DATE_INVALID_SECOND 0x400 Bad SeCond
2451: OCI_DATE_SECOND_BELOW_VALID 0x800 bad second Low/high bit (1=low)
2452: OCI_DATE_DAY_MISSING_FROM_1582 0x1000 Day is one of those "missing"
2453: from 1582
2454: OCI_DATE_YEAR_ZERO 0x2000 Year may not equal zero
2455: OCI_DATE_INVALID_FORMAT 0x8000 Bad date format input
2456:
2457: So, for example, if the date passed in was 2/0/1990 25:61:10 in
2458: (month/day/year hours:minutes:seconds format), the erroor returned
2459: would be OCI_DATE_INVALID_DAY | OCI_DATE_DAY_BELOW_VALID |
2460: OCI_DATE_INVALID_HOUR | OCI_DATE_INVALID_MINUTE
2461:
2462: DESCRIPTION:
2463: Check if the given date is valid.
2464: RETURNS:
2465: OCI_SUCCESS if the function completes successfully.
2466: OCI_INVALID_HANDLE if 'err' is NULL.
2467: OCI_ERROR if
2468: 'date' and 'valid' pointers are NULL pointers
2469: */
2470:
2471: /*--------------------------- OCIDateSysDate --------------------------------*/
2472:
2473: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2474: sword OCIDateSysDate(/*_ OCIError *err, OCIDate *sys_date _*/);
2475: #else /* ANSI C */
2476: sword OCIDateSysDate( OCIError *err, OCIDate *sys_date );
2477: #endif
2478: /*
2479: NAME: OCIDateSysDate - OCIDate get current SYStem date and time
2480: PARAMETERS:
2481: err (IN/OUT) - error handle. If there is an error, it is
2482: recorded in 'err' and this function returns OCI_ERROR.
2483: The error recorded in 'err' can be retrieved by calling
2484: OCIErrorGet().
2485: sys_date (OUT) - current system date and time
2486: DESCRIPTION:
2487: Returns the current system date and time.
2488: RETURNS:
2489: OCI_SUCCESS if the function completes successfully.
2490: OCI_INVALID_HANDLE if 'err' is NULL.
2491: OCI_ERROR if
2492: <to be discovered>
2493: */
2494:
2495: /*****************************************************************************/
2496: /* FIXED-LENGTH STRING - CHAR (N) */
2497: /*****************************************************************************/
2498:
2499: /*
2500: * An ADT attribute declared as "x CHAR(n)" is mapped to "OCIString *x;".
2501: * The representation of OCIString * is shown below.
2502: */
2503:
2504: /*****************************************************************************/
2505: /* VARIABLE-LENGTH STRING */
2506: /*****************************************************************************/
2507:
2508: /*
2509: * The variable-length string is represented in C as a pointer to OCIString
2510: * structure. The OCIString structure is opaque to the user. Functions are
2511: * provided to allow the user to manipulate a variable-length string.
2512: *
2513: * A variable-length string can be declared as:
2514: *
2515: * OCIString *vstr;
2516: *
2517: * For binding variables of type OCIString* in OCI calls (OCIBindByName(),
2518: * OCIBindByPos() and OCIDefineByPos()) use the external type code SQLT_VST.
2519: */
2520: typedef struct OCIString OCIString;
2521:
2522: /*-------------------------- OCIStringAssign --------------------------------*/
2523:
2524: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2525: sword OCIStringAssign(/*_ OCIEnv *env, OCIError *err, CONST OCIString *rhs,
2526: OCIString **lhs _*/);
2527: #else /* ANSI C */
2528: sword OCIStringAssign( OCIEnv *env, OCIError *err, CONST OCIString *rhs,
2529: OCIString **lhs );
2530: #endif
2531: /*
2532: NAME: OCIStringAssign - OCIString Assign String to String
2533: PARAMETERS:
2534: env (IN/OUT) - OCI environment handle initialized in object mode.
2535: err (IN/OUT) - error handle. If there is an error, it is
2536: recorded in 'err' and this function returns OCI_ERROR.
2537: The error recorded in 'err' can be retrieved by calling
2538: OCIErrorGet().
2539: rhs (IN) - RHS of the assignment, the type of rhs is also OCIString
2540: lhs (IN/OUT) - LHS of the assignment
2541: DESCRIPTION:
2542: Assign 'rhs' string to 'lhs' string. The 'lhs' string may be
2543: resized depending upon the size of the 'rhs'. The assigned string is
2544: null-terminated. The 'length' field will not include the extra byte
2545: needed for null termination.
2546: RETURNS:
2547: OCI_SUCCESS if the function completes successfully.
2548: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
2549: OCI_ERROR if
2550: out of space error
2551: */
2552:
2553: /*---------------------- OCIStringAssignText --------------------------------*/
2554:
2555: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2556: sword OCIStringAssignText(/*_ OCIEnv *env, OCIError *err, CONST text *rhs,
2557: ub4 rhs_len, OCIString **lhs _*/);
2558: #else /* ANSI C */
2559: sword OCIStringAssignText( OCIEnv *env, OCIError *err, CONST text *rhs,
2560: ub4 rhs_len, OCIString **lhs );
2561: #endif
2562: /*
2563: NAME: OCIStringAssignText - OCIString Assign Text string to String
2564: PARAMETERS:
2565: env (IN/OUT) - OCI environment handle initialized in object mode.
2566: err (IN/OUT) - error handle. If there is an error, it is
2567: recorded in 'err' and this function returns OCI_ERROR.
2568: The error recorded in 'err' can be retrieved by calling
2569: OCIErrorGet().
2570: rhs (IN) - RHS of the assignment, the type of rhs is a text string
2571: rhs_len (IN) - length of the 'rhs' string
2572: lhs (IN/OUT) - LHS of the assignment
2573: DESCRIPTION:
2574: Assign 'rhs' string to 'lhs' string. The 'lhs' string may be
2575: resized depending upon the size of the 'rhs'. The assigned string is
2576: null-terminated. The 'length' field will not include the extra byte
2577: needed for null termination.
2578: RETURNS:
2579: OCI_SUCCESS if the function completes successfully.
2580: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
2581: OCI_ERROR if
2582: out of space error
2583: */
2584:
2585: /*-------------------------- OCIStringResize --------------------------------*/
2586:
2587: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2588: sword OCIStringResize(/*_ OCIEnv *env, OCIError *err, ub4 new_size,
2589: OCIString **str _*/);
2590: #else /* ANSI C */
2591: sword OCIStringResize( OCIEnv *env, OCIError *err, ub4 new_size,
2592: OCIString **str );
2593: #endif
2594: /*
2595: NAME: OCIStringResize - OCIString ReSiZe string memory
2596: PARAMETERS:
2597: env (IN/OUT) - OCI environment handle initialized in object mode.
2598: err (IN/OUT) - error handle. If there is an error, it is
2599: recorded in 'err' and this function returns OCI_ERROR.
2600: The error recorded in 'err' can be retrieved by calling
2601: OCIErrorGet().
2602: new_size (IN) - new memory size of the string in bytes
2603: str (IN/OUT) - allocated memory for the string is freed from the
2604: OOCI heap
2605: DESCRIPTION:
2606: This function resizes the memory of the given variable-length string in
2607: the object cache. The contents of the string are NOT preserved.
2608: This function may allocate the string in a new memory region in
2609: which case the original memory occupied by the given string will
2610: be freed. If the input string is null (str == NULL), then this
2611: function will allocate memory for the string.
2612:
2613: If the new_size is 0, then this function frees the memory occupied
2614: by 'str' and a null pointer value is returned.
2615:
2616: NOTE: The caller must compute 'new_size' taking into account space
2617: for the null character ('\0').
2618: RETURNS:
2619: OCI_SUCCESS if the function completes successfully.
2620: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
2621: OCI_ERROR if
2622: out of space error
2623: */
2624:
2625: /*---------------------------- OCIStringSize --------------------------------*/
2626:
2627: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2628: ub4 OCIStringSize(/*_ OCIEnv *env, CONST OCIString *vs _*/);
2629: #else /* ANSI C */
2630: ub4 OCIStringSize( OCIEnv *env, CONST OCIString *vs );
2631: #endif
2632: /*
2633: NAME: OCIStringSize - OCIString Get String siZe
2634: PARAMETERS:
2635: env(IN) - pointer to OCI environment handle
2636: vs (IN) - string whose size is returned
2637: DESCRIPTION:
2638: Return the size of the given string.
2639: RETURNS:
2640: size of the string in bytes is returned
2641: */
2642:
2643: /*----------------------------- OCIStringPtr --------------------------------*/
2644:
2645: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2646: text *OCIStringPtr(/*_ OCIEnv *env, CONST OCIString *vs _*/);
2647: #else /* ANSI C */
2648: text *OCIStringPtr( OCIEnv *env, CONST OCIString *vs );
2649: #endif
2650: /*
2651: NAME: OCIStringPtr - OCIString Get String Pointer
2652: PARAMETERS:
2653: env(IN) - pointer to OCI environment handle
2654: vs (IN) - pointer to the text of this string is returned
2655: DESCRIPTION:
2656: Return the pointer to the text of the given string.
2657: RETURNS:
2658: pointer to the text of the string is returned
2659: */
2660:
2661: /*----------------------- OCIStringAllocSize --------------------------------*/
2662:
2663: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2664: sword OCIStringAllocSize(/*_ OCIEnv *env, OCIError *err, CONST OCIString *vs,
2665: ub4 *allocsize _*/);
2666: #else /* ANSI C */
2667: sword OCIStringAllocSize( OCIEnv *env, OCIError *err, CONST OCIString *vs,
2668: ub4 *allocsize );
2669: #endif
2670: /*
2671: NAME: OCIStringAllocSize - OCIString get Allocated SiZe of string memory
2672: in bytes
2673: PARAMETERS:
2674: env (IN/OUT) - OCI environment handle initialized in object mode.
2675: err (IN/OUT) - error handle. If there is an error, it is
2676: recorded in 'err' and this function returns OCI_ERROR.
2677: The error recorded in 'err' can be retrieved by calling
2678: OCIErrorGet().
2679: vs (IN) - string whose allocated size in bytes is returned
2680: allocsize (OUT) - allocated size of string memory in bytes is returned
2681: DESCRIPTION:
2682: Return the allocated size of the string memory in bytes. The
2683: allocated size is >= actual string size.
2684: REQUIRES:
2685: vs is a non-null pointer
2686: RETURNS:
2687: OCI_SUCCESS if the function completes successfully.
2688: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
2689: OCI_ERROR on error
2690: */
2691:
2692: /*****************************************************************************/
2693: /* VARIABLE-LENGTH RAW */
2694: /*****************************************************************************/
2695:
2696: /*
2697: * The variable-length raw is represented in C as a pointer to OCIRaw
2698: * structure. The OCIRaw structure is opaque to the user. Functions are
2699: * provided to allow the user to manipulate a variable-length raw.
2700: *
2701: * A variable-length raw can be declared as:
2702: *
2703: * OCIRaw *raw;
2704: *
2705: * For binding variables of type OCIRaw* in OCI calls (OCIBindByName(),
2706: * OCIBindByPos() and OCIDefineByPos()) use the external type code SQLT_LVB.
2707: */
2708: typedef struct OCIRaw OCIRaw;
2709:
2710: /*-------------------------- OCIRawAssignRaw --------------------------------*/
2711:
2712: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2713: sword OCIRawAssignRaw(/*_ OCIEnv *env, OCIError *err, CONST OCIRaw *rhs,
2714: OCIRaw **lhs _*/);
2715: #else /* ANSI C */
2716: sword OCIRawAssignRaw( OCIEnv *env, OCIError *err, CONST OCIRaw *rhs,
2717: OCIRaw **lhs );
2718: #endif
2719: /*
2720: NAME: OCIRawAssignRaw - OCIRaw Assign Raw (of type OCIRaw*) to
2721: Raw (of type OCIRaw*)
2722: PARAMETERS:
2723: env (IN/OUT) - OCI environment handle initialized in object mode.
2724: err (IN/OUT) - error handle. If there is an error, it is
2725: recorded in 'err' and this function returns OCI_ERROR.
2726: The error recorded in 'err' can be retrieved by calling
2727: OCIErrorGet().
2728: rhs (IN) - RHS of the assignment, the type of rhs is also OCIRaw
2729: lhs (IN/OUT) - LHS of the assignment
2730: DESCRIPTION:
2731: Assign 'rhs' raw to 'lhs' raw. The 'lhs' raw may be
2732: resized depending upon the size of the 'rhs'.
2733: RETURNS:
2734: OCI_SUCCESS if the function completes successfully.
2735: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
2736: OCI_ERROR if
2737: out of space error
2738: */
2739:
2740: /*------------------------ OCIRawAssignBytes --------------------------------*/
2741:
2742: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2743: sword OCIRawAssignBytes(/*_ OCIEnv *env, OCIError *err, CONST ub1 *rhs,
2744: ub4 rhs_len, OCIRaw **lhs _*/);
2745: #else /* ANSI C */
2746: sword OCIRawAssignBytes( OCIEnv *env, OCIError *err, CONST ub1 *rhs,
2747: ub4 rhs_len, OCIRaw **lhs );
2748: #endif
2749: /*
2750: NAME: OCIRawAssignBytes - OCIRaw Assign raw Bytes (of type ub1*) to Raw
2751: (of type OCIRaw*)
2752: PARAMETERS:
2753: env (IN/OUT) - OCI environment handle initialized in object mode.
2754: err (IN/OUT) - error handle. If there is an error, it is
2755: recorded in 'err' and this function returns OCI_ERROR.
2756: The error recorded in 'err' can be retrieved by calling
2757: OCIErrorGet().
2758: rhs (IN) - RHS of the assignment, the type of rhs is ub1 *
2759: rhs_len (IN) - length of the 'rhs' raw
2760: lhs (IN/OUT) - LHS of the assignment
2761: DESCRIPTION:
2762: Assign 'rhs' raw to 'lhs' raw. The 'lhs' raw may be
2763: resized depending upon the size of the 'rhs'.
2764: RETURNS:
2765: OCI_SUCCESS if the function completes successfully.
2766: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
2767: OCI_ERROR if
2768: out of space error
2769: */
2770:
2771: /*---------------------------- OCIRawResize ---------------------------------*/
2772:
2773: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2774: sword OCIRawResize(/*_ OCIEnv *env, OCIError *err, ub4 new_size,
2775: OCIRaw **raw _*/);
2776: #else /* ANSI C */
2777: sword OCIRawResize( OCIEnv *env, OCIError *err, ub4 new_size,
2778: OCIRaw **raw );
2779: #endif
2780: /*
2781: NAME: OCIRawResize - OCIRaw ReSiZe memory of variable-length raw
2782: PARAMETERS:
2783: env (IN/OUT) - OCI environment handle initialized in object mode.
2784: err (IN/OUT) - error handle. If there is an error, it is
2785: recorded in 'err' and this function returns OCI_ERROR.
2786: The error recorded in 'err' can be retrieved by calling
2787: OCIErrorGet().
2788: new_size (IN) - new size of the raw data in bytes
2789: raw (IN) - variable-length raw pointer; the raw is
2790: resized to 'new_size'
2791: DESCRIPTION:
2792: This function resizes the memory of the given variable-length raw in
2793: the object cache.
2794: The previous contents of the raw are NOT preserved.
2795: This function may allocate the raw in a new memory region in
2796: which case the original memory occupied by the given raw will
2797: be freed. If the input raw is null (raw == NULL), then this
2798: function will allocate memory for the raw data.
2799:
2800: If the new_size is 0, then this function frees the memory occupied
2801: by 'raw' and a null pointer value is returned.
2802: RETURNS:
2803: OCI_SUCCESS if the function completes successfully.
2804: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
2805: OCI_ERROR if
2806: out of space error
2807: */
2808:
2809: /*------------------------------- OCIRawSize --------------------------------*/
2810:
2811: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2812: ub4 OCIRawSize(/*_ OCIEnv * env, CONST OCIRaw *raw _*/);
2813: #else /* ANSI C */
2814: ub4 OCIRawSize( OCIEnv * env, CONST OCIRaw *raw );
2815: #endif
2816: /*
2817: NAME: OCIRawSize - OCIRaw Get Raw siZe
2818: PARAMETERS:
2819: env (IN) - pointer to OCI environment handle
2820: raw (INT) - raw whose size is returned
2821: DESCRIPTION:
2822: Return the size of the given raw.
2823: RETURNS:
2824: size of the raw in bytes is returned
2825: */
2826:
2827: /*--------------------------------- OCIRawPtr -------------------------------*/
2828: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2829: ub1 *OCIRawPtr(/*_ OCIEnv * env, CONST OCIRaw *raw _*/);
2830: #else /* ANSI C */
2831: ub1 *OCIRawPtr( OCIEnv * env, CONST OCIRaw *raw );
2832: #endif
2833: /*
2834: NAME: OCIRawPtr - OCIRaw Get Raw data Pointer
2835: PARAMETERS:
2836: env (IN) - pointer to OCI environment handle
2837: raw (IN) - pointer to the data of this raw is returned
2838: DESCRIPTION:
2839: Return the pointer to the data of the given raw.
2840: RETURNS:
2841: pointer to the data of the raw is returned
2842: */
2843:
2844: /*------------------------------ OCIRawAllocSize ----------------------------*/
2845:
2846: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2847: sword OCIRawAllocSize(/*_ OCIEnv *env, OCIError *err, CONST OCIRaw *raw,
2848: ub4 *allocsize _*/);
2849: #else /* ANSI C */
2850: sword OCIRawAllocSize( OCIEnv *env, OCIError *err, CONST OCIRaw *raw,
2851: ub4 *allocsize );
2852: #endif
2853: /*
2854: NAME: OCIRawAllocSize - OCIRaw get Allocated SiZe of raw memory in bytes
2855: PARAMETERS:
2856: env (IN/OUT) - OCI environment handle initialized in object mode.
2857: err (IN/OUT) - error handle. If there is an error, it is
2858: recorded in 'err' and this function returns OCI_ERROR.
2859: The error recorded in 'err' can be retrieved by calling
2860: OCIErrorGet().
2861: raw (IN) - raw whose allocated size in bytes is returned
2862: allocsize (OUT) - allocated size of raw memory in bytes is returned
2863: DESCRIPTION:
2864: Return the allocated size of the raw memory in bytes. The
2865: allocated size is >= actual raw size.
2866: REQUIRES:
2867: raw is a non-null pointer
2868: RETURNS:
2869: OCI_SUCCESS if the function completes successfully.
2870: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
2871: OCI_ERROR upon error
2872: */
2873:
2874: /*****************************************************************************/
2875: /* OBJECT REFERENCE OPERATIONS */
2876: /*****************************************************************************/
2877:
2878: /*
2879: * See the definition of OCIRef in oro.h.
2880: *
2881: * For binding variables of type OCIRef* in OCI calls (OCIBindByName(),
2882: * OCIBindByPos() and OCIDefineByPos()) use the code SQLT_REF.
2883: *
2884: */
2885:
2886: /*---------------------------- OCIRefClear ----------------------------------*/
2887: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2888: void OCIRefClear(/*_ OCIEnv *env, OCIRef *ref _*/);
2889: #else /* ANSI C */
2890: void OCIRefClear( OCIEnv *env, OCIRef *ref );
2891: #endif
2892: /*
2893: NAME: OCIRefClear - OCIRef CLeaR or nullify a ref
2894: PARAMETERS:
2895: env (IN) - pointer to OCI environment handle
2896: ref (IN/OUT) - ref to clear
2897: DESCRIPTION:
2898: Clear or nullify the given ref. A ref is considered to be a null ref
2899: if it does not contain a valid OID (and thus doesn't point to an
2900: object). Logically, a null ref is a dangling ref.
2901:
2902: Note that a null ref is still a valid SQL value and is not SQL-ly null.
2903: It can be used as a valid non-null constant ref value for NOT NULL
2904: column or attribute of a row in a table.
2905:
2906: If a null pointer value is passed as a ref,
2907: then this function is a no-op.
2908: */
2909:
2910: /*--------------------------- OCIRefAssign ----------------------------------*/
2911: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2912: sword OCIRefAssign(/*_ OCIEnv *env, OCIError *err, CONST OCIRef *source,
2913: OCIRef **target _*/);
2914: #else /* ANSI C */
2915: sword OCIRefAssign( OCIEnv *env, OCIError *err, CONST OCIRef *source,
2916: OCIRef **target );
2917: #endif
2918: /*
2919: NAME: OCIRefAssign - OCIRef CoPY a ref to another
2920: PARAMETERS:
2921: env (IN/OUT) - OCI environment handle initialized in object mode.
2922: err (IN/OUT) - error handle. If there is an error, it is
2923: recorded in 'err' and this function returns OCI_ERROR.
2924: The error recorded in 'err' can be retrieved by calling
2925: OCIErrorGet().
2926: source (IN) - ref to copy from
2927: target (IN/OUT) - ref to copy to
2928: DESCRIPTION:
2929: Copy 'source' ref to 'target' ref; both then reference the same
2930: object. If the target ref pointer is null (i.e. *target == NULL)
2931: then the copy function will allocate memory for the target ref
2932: in OOCI heap prior to the copy.
2933: RETURNS:
2934: OCI_SUCCESS if the function completes successfully.
2935: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
2936: OCI_ERROR if
2937: 1) out of memory
2938: */
2939:
2940: /*-------------------------- OCIRefIsEqual ----------------------------------*/
2941: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2942: boolean OCIRefIsEqual(/*_ OCIEnv *env, CONST OCIRef *x, CONST OCIRef *y _*/);
2943: #else /* ANSI C */
2944: boolean OCIRefIsEqual( OCIEnv *env, CONST OCIRef *x, CONST OCIRef *y );
2945: #endif
2946: /*
2947: NAME: OCIRefIsEqual - OCIRef compare two refs for EQUality
2948: PARAMETERS:
2949: env (IN) - pointer to OCI environment handle
2950: x (IN) - ref to compare
2951: y (IN) - ref to compare
2952: DESCRIPTION:
2953: Compare the given refs for equality.
2954: Two refs are equal if and only if:
2955: - they are both referencing the same persistent object, or
2956: - they are both referencing the same transient object.
2957:
2958: NOTE THAT TWO NULL REFS ARE CONSIDERED NOT EQUAL BY THIS FUNCTION.
2959: RETURNS:
2960: TRUE if the two refs are equal
2961: FALSE if the two refs are not equal, or X is NULL, or Y is NULL
2962: */
2963:
2964: /*--------------------------- OCIRefIsNull ----------------------------------*/
2965: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2966: boolean OCIRefIsNull(/*_ OCIEnv *env, CONST OCIRef *ref _*/);
2967: #else /* ANSI C */
2968: boolean OCIRefIsNull( OCIEnv *env, CONST OCIRef *ref );
2969: #endif
2970: /*
2971: NAME: OCIRefIsNull - OCIRef test if a ref is NULl
2972: PARAMETERS:
2973: env (IN) - pointer to OCI environment handle
2974: ref (IN) - ref to test for null
2975: DESCRIPTION:
2976: Return TRUE if the given ref is null; otherwise, return FALSE.
2977: A ref is null if and only if:
2978: - it is supposed to be referencing a persistent object, but
2979: its OID is null, or
2980: - it is supposed to be referencing a transient object, but it is
2981: currently not pointing to an object.
2982: A ref is a dangling ref if the object that it points to does not
2983: exist.
2984: RETURNS:
2985: TRUE if the given ref is NULL
2986: FALSE if the given ref is not NULL
2987: */
2988:
2989: /*-------------------------- OCIRefHexSize ----------------------------------*/
2990: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
2991: ub4 OCIRefHexSize(/*_ OCIEnv *env, CONST OCIRef *ref _*/);
2992: #else /* ANSI C */
2993: ub4 OCIRefHexSize( OCIEnv *env, CONST OCIRef *ref );
2994: #endif
2995: /*
2996: NAME: OCIRefHexSize - OCIRef Hexadecimal buffer SiZe in bytes
2997: PARAMETERS:
2998: env (IN) - pointer to OCI environment handle
2999: ref (IN) - ref whose size in hexadecimal representation in bytes is
3000: returned
3001: DESCRIPTION:
3002: Return the size of the buffer in bytes required for the hexadecimal
3003: representation of the ref. A buffer of at-least this size must be
3004: passed to ref-to-hex (OCIRefToHex) conversion function.
3005: RETURNS:
3006: size of hexadecimal representation of ref
3007: */
3008:
3009: /*-------------------------- OCIRefFromHex ---------------------------------*/
3010: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3011: sword OCIRefFromHex(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
3012: CONST text *hex, ub4 length, OCIRef **ref _*/);
3013: #else /* ANSI C */
3014: sword OCIRefFromHex( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
3015: CONST text *hex, ub4 length, OCIRef **ref );
3016: #endif
3017: /*
3018: NAME:
3019: OCIRefFromHex - OCIRef convert a Hexadecimal string TO a Ref
3020: PARAMETERS:
3021: env (IN/OUT) - OCI environment handle initialized in object mode
3022: err (IN/OUT) - error handle. If there is an error, it is
3023: recorded in 'err' and this function returns OCI_ERROR.
3024: The error recorded in 'err' can be retrieved by
3025: calling OCIErrorGet().
3026: svc (IN) - OCI service context handle; if the resulting ref is
3027: initialized with this service context
3028: hex (IN) - hexadecimal string (that was produced by 'OCIRefToHex()"
3029: previously) to be convert into a ref
3030: length (IN) - length of the hexadecimal string
3031: ref (IN/OUT) - ref is initialized with the given value ('hex').
3032: If *ref is null, then space for the ref is allocated in the
3033: object cache, otherwise the memory occupied by the given ref
3034: is re-used.
3035: DESCRIPTION:
3036: Convert the given hexadecimal string into a ref. This function
3037: ensures that the resulting ref is well formed. It does NOT ensure
3038: that the object pointed to by the resulting ref exists or not.
3039: RETURNS:
3040: OCI_SUCCESS if the function completes successfully.
3041: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3042: OCI_ERROR if
3043: */
3044:
3045: /*--------------------------- OCIRefToHex -----------------------------------*/
3046: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3047: sword OCIRefToHex(/*_ OCIEnv *env, OCIError *err, CONST OCIRef *ref,
3048: text *hex, ub4 *hex_length _*/);
3049: #else /* ANSI C */
3050: sword OCIRefToHex( OCIEnv *env, OCIError *err, CONST OCIRef *ref,
3051: text *hex, ub4 *hex_length );
3052: #endif
3053: /*
3054: NAME:
3055: OCIRefToHex - OCIRef convert ref to a Hexadecimal string
3056: PARAMETERS:
3057: env (IN/OUT) - OCI environment handle initialized in object mode
3058: err (IN/OUT) - error handle. If there is an error, it is
3059: recorded in 'err' and this function returns OCI_ERROR.
3060: The error recorded in 'err' can be retrieved by
3061: calling OCIErrorGet().
3062: ref (IN) - ref to be converted into a hexadecimal string; if the
3063: ref is a null ref (i.e. OCIRefIsNull(ref) == TRUE) then
3064: a zero hex_length value is returned
3065: hex (OUT) - buffer that is large enough to contain the resulting
3066: hexadecimal string; the contents of the string is opaque
3067: to the caller
3068: hex_length (IN/OUT) - on input specifies the size of the 'hex' buffer,
3069: on output specifies the actual size of the hexadecimal
3070: string being returned in 'hex'
3071: DESCRIPTION:
3072: Convert the given ref into a hexadecimal string, and return the length
3073: of the string. The resulting string is opaque to the caller.
3074: RETURNS:
3075: OCI_SUCCESS if the function completes successfully.
3076: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3077: OCI_ERROR if
3078: the given buffer is not big enough to hold the resulting string
3079: */
3080:
3081:
3082: /*****************************************************************************/
3083: /* COLLECTION FUNCTIONS */
3084: /*****************************************************************************/
3085:
3086: /*
3087: The generic collection is represented by the type 'OCIColl'. The following
3088: operations OCIColl*() are provided on a generic collection:
3089: - get current size of collection
3090: - get upper bound of collection
3091: - get pointer to an element given its index
3092: - set element at given index (assign element)
3093: - append an element
3094: - trim the given number of elements from the end of the collection
3095: - collection assignment
3096:
3097: The following iterator based scanning functions are also provided on a
3098: generic collection. These functions make use of an iterator which is
3099: defined to be of type OCIIter.
3100:
3101: - create an iterator for scanning collection
3102: - destroy iterator
3103: - reset iterator to the beginning of collection
3104: - get pointer to current element pointed by iterator
3105: - get pointer to next element
3106: - get pointer to previous element
3107:
3108: The collections variable-length array (varray) and nested table
3109: are sub-types of generic collection. This means that the OCIColl*()
3110: functions can also be used to manipulate varray and nested table.
3111:
3112: The varray is represented by OCIArray type and nested table by OCITable.
3113: Besides OCIColl*() functions no additional functions are provided for
3114: manipulating varrays. The OCIColl*() functions are a complete set of
3115: functions to manipulate varrays.
3116:
3117: Besides OCIColl*() functions, the following functions OCITable*() can be
3118: used to manipulate nested table. The OCITable*() functions operate on
3119: nested tables only and should not be used on a varray.
3120:
3121: - delete an element at index i. Note that the position
3122: ordinals of the remaining elements of the table is not changed by the
3123: delete operation. So delete creates "holes" in the table.
3124: - check if an element exists at the given index i
3125: - return the smallest value of i for which exists(i) is true
3126: - return the largest value of i for which exists(i) is true
3127: - return pointer to the smallest position j, greater than i, such that
3128: OCITableExists(j) is true
3129: - return pointer to the largest position j, less than i, such that
3130: OCITableExists(j) is true
3131:
3132: For binding variables of type OCIColl* or OCITable* in OCI calls
3133: (OCIBindByName(), OCIBindByPos() and OCIDefineByPos()) use the external
3134: type code SQLT_NTY.
3135: */
3136:
3137: /* OCIColl - generic collection type */
3138: typedef struct OCIColl OCIColl;
3139:
3140: /* OCIArray - varray collection type */
3141: typedef OCIColl OCIArray;
3142:
3143: /* OCITable - nested table collection type */
3144: typedef OCIColl OCITable;
3145:
3146: /* OCIIter - collection iterator */
3147: typedef struct OCIIter OCIIter;
3148:
3149: /*----------------------------- OCICollSize ---------------------------------*/
3150:
3151: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3152: sword OCICollSize(/*_ OCIEnv *env, OCIError *err, CONST OCIColl *coll,
3153: sb4 *size _*/);
3154: #else /* ANSI C */
3155: sword OCICollSize( OCIEnv *env, OCIError *err, CONST OCIColl *coll,
3156: sb4 *size );
3157: #endif
3158: /*
3159: NAME: OCICollSize - OCIColl return current SIZe of the given collection
3160: PARAMETERS:
3161: env(IN) - pointer to OCI environment handle
3162: err (IN/OUT) - error handle. If there is an error, it is
3163: recorded in 'err' and this function returns OCI_ERROR.
3164: The error recorded in 'err' can be retrieved by calling
3165: OCIErrorGet().
3166: coll (IN) - collection whose number of elements is returned
3167: size (OUT) - current number of elements in the collection
3168: DESCRIPTION:
3169: Returns the current number of elements in the given collection.
3170:
3171: For collections of type nested table wherein 'delete element'
3172: operation is allowed, the count returned by OCICollSize() will
3173: NOT be decremented upon deleting elements. For example:
3174:
3175: OCICollSize(...);
3176: // assume 'size' returned is equal to 5
3177: OCITableDelete(...); // delete one element
3178: OCICollSize(...);
3179: // 'size' returned will still be 5
3180:
3181: To get the count minus the deleted elements use OCITableSize().
3182: Continuing the above example,
3183:
3184: OCITableSize(...)
3185: // 'size' returned will be equal to 4
3186:
3187: Note, a trim operation (OCICollTrim) will decrement the count
3188: by the number of trimmed elements. Continuing the above example,
3189:
3190: OCICollTrim(..,1..); // trim one element
3191: OCICollSize(...);
3192: // 'size' returned will be equal to 4
3193: RETURNS:
3194: OCI_SUCCESS if the function completes successfully.
3195: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3196: OCI_ERROR if
3197: error during loading of collection into object cache
3198: any of the input parameters is null
3199: */
3200:
3201: /*------------------------------ OCICollMax ---------------------------------*/
3202:
3203: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3204: sb4 OCICollMax(/*_ OCIEnv *env, CONST OCIColl *coll _*/);
3205: #else /* ANSI C */
3206: sb4 OCICollMax( OCIEnv *env, CONST OCIColl *coll );
3207: #endif
3208: /*
3209: NAME: OCICollMax - OCIColl return MAXimum size (upper-bound) of the
3210: given collection (in number of elements)
3211: PARAMETERS:
3212: env(IN) - pointer to OCI environment handle
3213: coll (IN) - collection whose upper-bound in number of elements
3214: is returned
3215: DESCRIPTION:
3216: Returns the max number of elements that the given collection can hold.
3217: A value 0 indicates that the collection has no upper-bound.
3218: REQUIRES:
3219: coll must point to a valid collection descriptor
3220: RETURNS:
3221: upper-bound of the given collection
3222: */
3223:
3224: /*-------------------------- OCICollGetElem ---------------------------------*/
3225:
3226: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3227: sword OCICollGetElem(/*_ OCIEnv *env, OCIError *err, CONST OCIColl *coll,
3228: sb4 index, boolean *exists, dvoid **elem,
3229: dvoid **elemind _*/);
3230: #else /* ANSI C */
3231: sword OCICollGetElem( OCIEnv *env, OCIError *err, CONST OCIColl *coll,
3232: sb4 index, boolean *exists, dvoid **elem,
3233: dvoid **elemind );
3234: #endif
3235: /*
3236: NAME: OCICollGetElem - OCIColl GET pointer to the element at the given index
3237: PARAMETERS:
3238: env (IN/OUT) - OCI environment handle initialized in object mode.
3239: err (IN/OUT) - error handle. If there is an error, it is
3240: recorded in 'err' and this function returns OCI_ERROR.
3241: The error recorded in 'err' can be retrieved by calling
3242: OCIErrorGet().
3243: coll (IN) - pointer to the element in this collection is returned
3244: index (IN) - index of the element whose pointer is returned
3245: exists (OUT) - set to FALSE if element at the specified index does
3246: not exist else TRUE
3247: elem (OUT) - address of the desired element is returned
3248: elemind (OUT) [optional] - address of the null indicator information
3249: is returned; if (elemind == NULL) then the null indicator
3250: information will NOT be returned
3251: DESCRIPTION:
3252: Get the address of the element at the given position. Optionally
3253: this function also returns the address of the element's null indicator
3254: information.
3255:
3256: The following table describes for each collection element type
3257: what the corresponding element pointer type is. The element pointer
3258: is returned via the 'elem' parameter of OCICollGetElem().
3259:
3260: Element Type *elem is set to
3261: ----------------------- ---------------
3262: Oracle Number (OCINumber) OCINumber*
3263: Date (OCIDate) OCIDate*
3264: Variable-length string (OCIString*) OCIString**
3265: Variable-length raw (OCIRaw*) OCIRaw**
3266: object reference (OCIRef*) OCIRef**
3267: lob locator (OCILobLocator*) OCILobLocator**
3268: object type (e.g. person) person*
3269:
3270: The element pointer returned by OCICollGetElem() is in a form
3271: such that it can not only be used to access the
3272: element data but also is in a form that can be used as the target
3273: (i.e left-hand-side) of an assignment statement.
3274:
3275: For example, assume the user is iterating over the elements of
3276: a collection whose element type is object reference (OCIRef*). A call
3277: to OCICollGetElem() returns pointer to a reference handle
3278: (i.e. OCIRef**). After getting, the pointer to the collection
3279: element, the user may wish to modify it by assigning a new reference.
3280: This can be accomplished via the ref assignment function shown below:
3281:
3282: sword OCIRefAssign( OCIEnv *env, OCIError *err, CONST OCIRef *source,
3283: OCIRef **target );
3284:
3285: Note that the 'target' parameter of OCIRefAssign() is of type
3286: 'OCIRef**'. Hence OCICollGetElem() returns 'OCIRef**'.
3287: If '*target == NULL' a new ref will be allocated by OCIRefAssign()
3288: and returned via the 'target' parameter.
3289:
3290: Similarly, if the collection element was of type string (OCIString*),
3291: OCICollGetElem() returns pointer to string handle
3292: (i.e. OCIString**). If a new string is assigned, via
3293: OCIStringAssign() or OCIStringAssignText() the type of the target
3294: must be 'OCIString **'.
3295:
3296: If the collection element is of type Oracle number, OCICollGetElem()
3297: returns OCINumber*. The prototype of OCINumberAssign() is shown below:
3298:
3299: sword OCINumberAssign(OCIError *err, CONST OCINumber *from,
3300: OCINumber *to);
3301: RETURNS:
3302: OCI_SUCCESS if the function completes successfully.
3303: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3304: OCI_ERROR if
3305: any of the input parameters is null
3306: */
3307:
3308: /*----------------------- OCICollAssignElem ---------------------------------*/
3309:
3310: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3311: sword OCICollAssignElem(/*_ OCIEnv *env, OCIError *err, sb4 index,
3312: CONST dvoid *elem,
3313: CONST dvoid *elemind, OCIColl *coll _*/);
3314: #else /* ANSI C */
3315: sword OCICollAssignElem( OCIEnv *env, OCIError *err, sb4 index,
3316: CONST dvoid *elem,
3317: CONST dvoid *elemind, OCIColl *coll );
3318: #endif
3319: /*
3320: NAME: OCICollAssignElem - OCIColl ASsign Element
3321: PARAMETERS:
3322: env (IN/OUT) - OCI environment handle initialized in object mode.
3323: err (IN/OUT) - error handle. If there is an error, it is
3324: recorded in 'err' and this function returns OCI_ERROR.
3325: The error recorded in 'err' can be retrieved by calling
3326: OCIErrorGet().
3327: index (IN) - index of the element whose is assigned to
3328: elem (IN) - element which is assigned from (source element)
3329: elemind (IN) [optional] - pointer to the element's null indicator
3330: information; if (elemind == NULL) then the null indicator
3331: information of the assigned element will be set to non-null.
3332: coll (IN/OUT) - collection to be updated
3333: DESCRIPTION:
3334: Assign the given element value 'elem' to the element at coll[index].
3335: If the collection is of type nested table, the element at the given
3336: index may not exist (i.e. may have been deleted). In this case, the
3337: given element is inserted at index 'index'.
3338: Otherwise, the element at index 'index' is updated with the value
3339: of 'elem'.
3340:
3341: Note that the given element is deep-copied and
3342: 'elem' is strictly an input parameter.
3343: RETURNS:
3344: OCI_SUCCESS if the function completes successfully.
3345: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3346: OCI_ERROR if
3347: any of the input parameters is null
3348: out of memory error
3349: given index is out of bounds of the given collection
3350: */
3351:
3352: /*--------------------------- OCICollAssign ---------------------------------*/
3353:
3354: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3355: sword OCICollAssign(/*_ OCIEnv *env, OCIError *err, CONST OCIColl *rhs,
3356: OCIColl *lhs _*/);
3357: #else /* ANSI C */
3358: sword OCICollAssign( OCIEnv *env, OCIError *err, CONST OCIColl *rhs,
3359: OCIColl *lhs );
3360: #endif
3361: /*
3362: NAME: OCICollAssign - OCIColl ASsiGn collection
3363: PARAMETERS:
3364: env (IN/OUT) - OCI environment handle initialized in object mode.
3365: err (IN/OUT) - error handle. If there is an error, it is
3366: recorded in 'err' and this function returns OCI_ERROR.
3367: The error recorded in 'err' can be retrieved by calling
3368: OCIErrorGet().
3369: rhs (IN) - collection to be assigned from
3370: lhs (OUT) - collection to be assigned to
3371: DESCRIPTION:
3372: Assign 'rhs' to 'lhs'. The 'lhs' collection may be decreased or
3373: increased depending upon the size of 'rhs'. If the 'lhs' contains
3374: any elements then the elements will be deleted prior to the
3375: assignment. This function performs a deep-copy. The memory for the
3376: elements comes from the object cache.
3377:
3378: An error is returned if the element types of the lhs and rhs
3379: collections do not match. Also, an error is returned if the
3380: upper-bound of the lhs collection is less than the current number of
3381: elements in the rhs collection.
3382: RETURNS:
3383: OCI_SUCCESS if the function completes successfully.
3384: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3385: OCI_ERROR if
3386: any of the input parameters is null
3387: out of memory error
3388: type mis-match of lhs and rhs collections
3389: upper-bound of lhs collection is less than the current number of
3390: elements in the rhs collection
3391: */
3392:
3393: /*--------------------------- OCICollAppend ---------------------------------*/
3394:
3395: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3396: sword OCICollAppend(/*_ OCIEnv *env, OCIError *err, CONST dvoid *elem,
3397: CONST dvoid *elemind, OCIColl *coll _*/);
3398: #else /* ANSI C */
3399: sword OCICollAppend( OCIEnv *env, OCIError *err, CONST dvoid *elem,
3400: CONST dvoid *elemind, OCIColl *coll );
3401: #endif
3402: /*
3403: NAME: OCICollAppend - OCIColl APPend collection
3404: PARAMETERS:
3405: env (IN/OUT) - OCI environment handle initialized in object mode.
3406: err (IN/OUT) - error handle. If there is an error, it is
3407: recorded in 'err' and this function returns OCI_ERROR.
3408: The error recorded in 'err' can be retrieved by calling
3409: OCIErrorGet().
3410: elem (IN) - pointer to the element which is appended to the end
3411: of the given collection
3412: elemind (IN) [optional] - pointer to the element's null indicator
3413: information; if (elemind == NULL) then the null indicator
3414: information of the appended element will be set to non-null.
3415: coll (IN/OUT) - updated collection
3416: DESCRIPTION:
3417: Append the given element to the end of the given collection.
3418: Appending an element is equivalent to:
3419: - increasing the size of the collection by 1 element
3420: - updating (deep-copying) the last element's data with the given
3421: element's data
3422:
3423: Note that the pointer to the given element 'elem' will not be saved
3424: by this function. So 'elem' is strictly an input parameter.
3425: An error is returned if the current size of the collection
3426: is equal to the max size (upper-bound) of the collection prior to
3427: appending the element.
3428: RETURNS:
3429: OCI_SUCCESS if the function completes successfully.
3430: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3431: OCI_ERROR if
3432: any of the input parameters is null
3433: out of memory error
3434: current size of collection == max size of the collection
3435: */
3436:
3437: /*----------------------------- OCICollTrim ---------------------------------*/
3438:
3439: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3440: sword OCICollTrim(/*_ OCIEnv *env, OCIError *err, sb4 trim_num,
3441: OCIColl *coll _*/);
3442: #else /* ANSI C */
3443: sword OCICollTrim( OCIEnv *env, OCIError *err, sb4 trim_num,
3444: OCIColl *coll );
3445: #endif
3446: /*
3447: NAME: OCICollTrim - OCIColl Trim elements from the end of the collection
3448: PARAMETERS:
3449: env (IN/OUT) - OCI environment handle initialized in object mode.
3450: err (IN/OUT) - error handle. If there is an error, it is
3451: recorded in 'err' and this function returns OCI_ERROR.
3452: The error recorded in 'err' can be retrieved by calling
3453: OCIErrorGet().
3454: trim_num (IN) - number of elements to trim
3455: coll (IN/OUT) - 'trim_num' of elements are removed (freed) from the
3456: end of the collection
3457: DESCRIPTION:
3458: Trim the collection by the given number of elements. The elements are
3459: removed from the end of the collection.
3460:
3461: An error is returned if the 'trim_num' is greater than the current
3462: size of the collection.
3463: RETURNS:
3464: OCI_SUCCESS if the function completes successfully.
3465: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3466: OCI_ERROR if
3467: any of the input parameters is null
3468: 'trim_num' is greater than the current size of the collection.
3469: */
3470:
3471: /*--------------------------- OCICollIsLocator ------------------------------*/
3472:
3473: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3474: sword OCICollIsLocator(/*_ OCIEnv *env, OCIError *err, CONST OCIColl *coll,
3475: boolean *result _*/);
3476: #else /* ANSI C */
3477: sword OCICollIsLocator(OCIEnv *env, OCIError *err, CONST OCIColl *coll,
3478: boolean *result );
3479: #endif
3480: /*
3481: Name: OCICollIsLocator - OCIColl indicates whether a collection is locator
3482: based or not.
3483: Parameters:
3484: env(IN) - pointer to OCI environment handle
3485: err (IN/OUT) - error handle. If there is an error, it is
3486: recorded in 'err' and this function returns OCI_ERROR.
3487: The error recorded in 'err' can be retrieved by calling
3488: OCIErrorGet().
3489: coll (IN) - collection item.
3490: result (OUT) - TRUE if the collection item is a locator, FALSE
3491: otherwise
3492: Description:
3493: Returns TRUE in the result OUT parameter if the collection item is a
3494: locator, otherwise returns FALSE.
3495: Returns:
3496: OCI_SUCCESS if the function completes successfully.
3497: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3498: */
3499:
3500: /*---------------------------- OCIIterCreate --------------------------------*/
3501:
3502: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3503: sword OCIIterCreate(/*_ OCIEnv *env, OCIError *err, CONST OCIColl *coll,
3504: OCIIter **itr _*/);
3505: #else /* ANSI C */
3506: sword OCIIterCreate( OCIEnv *env, OCIError *err, CONST OCIColl *coll,
3507: OCIIter **itr );
3508: #endif
3509: /*
3510: NAME: OCIIterCreate - OCIColl Create an ITerator to scan the collection
3511: elements
3512: PARAMETERS:
3513: env (IN/OUT) - OCI environment handle initialized in object mode.
3514: err (IN/OUT) - error handle. If there is an error, it is
3515: recorded in 'err' and this function returns OCI_ERROR.
3516: The error recorded in 'err' can be retrieved by calling
3517: OCIErrorGet().
3518: coll (IN) - collection which will be scanned; the different
3519: collection types are varray and nested table
3520: itr (OUT) - address to the allocated collection iterator is
3521: returned by this function
3522: DESCRIPTION:
3523: Create an iterator to scan the elements of the collection. The
3524: iterator is created in the object cache. The iterator is initialized
3525: to point to the beginning of the collection.
3526:
3527: If the next function (OCIIterNext) is called immediately
3528: after creating the iterator then the first element of the collection
3529: is returned.
3530: If the previous function (OCIIterPrev) is called immediately after
3531: creating the iterator then "at beginning of collection" error is
3532: returned.
3533: RETURNS:
3534: OCI_SUCCESS if the function completes successfully.
3535: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3536: OCI_ERROR if
3537: any of the input parameters is null
3538: out of memory error
3539: */
3540:
3541: /*----------------------------- OCIIterDelete ------------------------------*/
3542:
3543: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3544: sword OCIIterDelete(/*_ OCIEnv *env, OCIError *err, OCIIter **itr _*/);
3545: #else /* ANSI C */
3546: sword OCIIterDelete( OCIEnv *env, OCIError *err, OCIIter **itr );
3547: #endif
3548: /*
3549: NAME: OCIIterDelete - OCIColl Delete ITerator
3550: PARAMETERS:
3551: env (IN/OUT) - OCI environment handle initialized in object mode.
3552: err (IN/OUT) - error handle. If there is an error, it is
3553: recorded in 'err' and this function returns OCI_ERROR.
3554: The error recorded in 'err' can be retrieved by calling
3555: OCIErrorGet().
3556: itr (IN/OUT) - the allocated collection iterator is destroyed and
3557: the 'itr' is set to NULL prior to returning
3558: DESCRIPTION:
3559: Delete the iterator which was previously created by a call to
3560: OCIIterCreate.
3561: RETURNS:
3562: OCI_SUCCESS if the function completes successfully.
3563: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3564: OCI_ERROR if
3565: any of the input parameters is null
3566: to be discovered
3567: */
3568:
3569: /*----------------------------- OCIIterInit ---------------------------------*/
3570:
3571: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3572: sword OCIIterInit(/*_ OCIEnv *env, OCIError *err, CONST OCIColl *coll,
3573: OCIIter *itr _*/);
3574: #else /* ANSI C */
3575: sword OCIIterInit( OCIEnv *env, OCIError *err, CONST OCIColl *coll,
3576: OCIIter *itr );
3577: #endif
3578: /*
3579: NAME: OCIIterInit - OCIColl Initialize ITerator to scan the given
3580: collection
3581: PARAMETERS:
3582: env (IN/OUT) - OCI environment handle initialized in object mode.
3583: err (IN/OUT) - error handle. If there is an error, it is
3584: recorded in 'err' and this function returns OCI_ERROR.
3585: The error recorded in 'err' can be retrieved by calling
3586: OCIErrorGet().
3587: coll (IN) - collection which will be scanned; the different
3588: collection types are varray and nested table
3589: itr (IN/OUT) - pointer to an allocated collection iterator
3590: DESCRIPTION:
3591: Initializes the given iterator to point to the beginning of the
3592: given collection. This function can be used to:
3593:
3594: a. reset an iterator to point back to the beginning of the collection
3595: b. reuse an allocated iterator to scan a different collection
3596: RETURNS:
3597: OCI_SUCCESS if the function completes successfully.
3598: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3599: OCI_ERROR if
3600: any of the input parameters is null
3601: */
3602:
3603: /*------------------------ OCIIterGetCurrent --------------------------------*/
3604:
3605: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3606: sword OCIIterGetCurrent(/*_ OCIEnv *env, OCIError *err, CONST OCIIter *itr,
3607: dvoid **elem, dvoid **elemind _*/);
3608: #else /* ANSI C */
3609: sword OCIIterGetCurrent( OCIEnv *env, OCIError *err, CONST OCIIter *itr,
3610: dvoid **elem, dvoid **elemind );
3611: #endif
3612: /*
3613: NAME: OCIIterGetCurrent - OCIColl Iterator based, get CURrent collection
3614: element
3615: PARAMETERS:
3616: env (IN/OUT) - OCI environment handle initialized in object mode.
3617: err (IN/OUT) - error handle. If there is an error, it is
3618: recorded in 'err' and this function returns OCI_ERROR.
3619: The error recorded in 'err' can be retrieved by calling
3620: OCIErrorGet().
3621: itr (IN) - iterator which points to the current element
3622: elem (OUT) - address of the element pointed by the iterator is returned
3623: elemind (OUT) [optional] - address of the element's null indicator
3624: information is returned; if (elemind == NULL) then the null
3625: indicator information will NOT be returned
3626: DESCRIPTION:
3627: Returns pointer to the current element and its corresponding null
3628: information.
3629: RETURNS:
3630: OCI_SUCCESS if the function completes successfully.
3631: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3632: OCI_ERROR if
3633: any of the input parameters is null
3634: */
3635:
3636: /*------------------------------ OCIIterNext --------------------------------*/
3637:
3638: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3639: sword OCIIterNext(/*_ OCIEnv *env, OCIError *err, OCIIter *itr,
3640: dvoid **elem, dvoid **elemind, boolean *eoc _*/);
3641: #else /* ANSI C */
3642: sword OCIIterNext( OCIEnv *env, OCIError *err, OCIIter *itr,
3643: dvoid **elem, dvoid **elemind, boolean *eoc );
3644: #endif
3645: /*
3646: NAME: OCIIterNext - OCIColl Iterator based, get NeXT collection element
3647: PARAMETERS:
3648: env (IN/OUT) - OCI environment handle initialized in object mode.
3649: err (IN/OUT) - error handle. If there is an error, it is
3650: recorded in 'err' and this function returns OCI_ERROR.
3651: The error recorded in 'err' can be retrieved by calling
3652: OCIErrorGet().
3653: itr (IN/OUT) - iterator is updated to point to the next element
3654: elem (OUT) - after updating the iterator to point to the next element,
3655: address of the element is returned
3656: elemind (OUT) [optional] - address of the element's null indicator
3657: information is returned; if (elemind == NULL) then the null
3658: indicator information will NOT be returned
3659: eoc (OUT) - TRUE if iterator is at End Of Collection (i.e. next
3660: element does not exist) else FALSE
3661: DESCRIPTION:
3662: Returns pointer to the next element and its corresponding null
3663: information. The iterator is updated to point to the next element.
3664:
3665: If the iterator is pointing to the last element of the collection
3666: prior to executing this function, then calling this function will
3667: set eoc flag to TRUE. The iterator will be left unchanged in this
3668: situation.
3669: RETURNS:
3670: OCI_SUCCESS if the function completes successfully.
3671: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3672: OCI_ERROR if
3673: any of the input parameters is null
3674: */
3675:
3676: /*------------------------------ OCIIterPrev --------------------------------*/
3677:
3678: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3679: sword OCIIterPrev(/*_ OCIEnv *env, OCIError *err, OCIIter *itr,
3680: dvoid **elem, dvoid **elemind, boolean *boc _*/);
3681: #else /* ANSI C */
3682: sword OCIIterPrev( OCIEnv *env, OCIError *err, OCIIter *itr,
3683: dvoid **elem, dvoid **elemind, boolean *boc );
3684: #endif
3685: /*
3686: NAME: OCIIterPrev - OCIColl Iterator based, get PReVious collection element
3687: PARAMETERS:
3688: env (IN/OUT) - OCI environment handle initialized in object mode.
3689: err (IN/OUT) - error handle. If there is an error, it is
3690: recorded in 'err' and this function returns OCI_ERROR.
3691: The error recorded in 'err' can be retrieved by calling
3692: OCIErrorGet().
3693: itr (IN/OUT) - iterator is updated to point to the previous
3694: element
3695: elem (OUT) - after updating the iterator to point to the previous
3696: element, address of the element is returned
3697: elemind (OUT) [optional] - address of the element's null indicator
3698: information is returned; if (elemind == NULL) then the null
3699: indicator information will NOT be returned
3700: boc (OUT) - TRUE if iterator is at Beginning Of Collection (i.e.
3701: previous element does not exist) else FALSE.
3702: DESCRIPTION:
3703: Returns pointer to the previous element and its corresponding null
3704: information. The iterator is updated to point to the previous element.
3705:
3706: If the iterator is pointing to the first element of the collection
3707: prior to executing this function, then calling this function will
3708: set 'boc' to TRUE. The iterator will be left unchanged in this
3709: situation.
3710: RETURNS:
3711: OCI_SUCCESS if the function completes successfully.
3712: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3713: OCI_ERROR if
3714: any of the input parameters is null
3715: */
3716:
3717: /*****************************************************************************/
3718: /* FUNCTIONS WHICH OPERATE ONLY ON NESTED TABLE OCITable*() */
3719: /*****************************************************************************/
3720:
3721: /*---------------------------- OCITableSize ---------------------------------*/
3722:
3723: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3724: sword OCITableSize(/*_ OCIEnv *env, OCIError *err, CONST OCITable *tbl,
3725: sb4 *size _*/);
3726: #else /* ANSI C */
3727: sword OCITableSize( OCIEnv *env, OCIError *err, CONST OCITable *tbl,
3728: sb4 *size);
3729: #endif
3730: /*
3731: NAME: OCITableSize - OCITable return current SIZe of the given
3732: nested table (not including deleted elements)
3733: PARAMETERS:
3734: env(IN) - pointer to OCI environment handle
3735: err (IN/OUT) - error handle. If there is an error, it is
3736: recorded in 'err' and this function returns OCI_ERROR.
3737: The error recorded in 'err' can be retrieved by calling
3738: OCIErrorGet().
3739: tbl (IN) - nested table whose number of elements is returned
3740: size (OUT) - current number of elements in the nested table. The count
3741: does not include deleted elements.
3742: DESCRIPTION:
3743: Returns the count of elements in the given nested table.
3744:
3745: The count returned by OCITableSize() will be decremented upon
3746: deleting elements from the nested table. So, this count DOES NOT
3747: includes any "holes" created by deleting elements.
3748: For example:
3749:
3750: OCITableSize(...);
3751: // assume 'size' returned is equal to 5
3752: OCITableDelete(...); // delete one element
3753: OCITableSize(...);
3754: // 'size' returned will be equal to 4
3755:
3756: To get the count plus the count of deleted elements use
3757: OCICollSize(). Continuing the above example,
3758:
3759: OCICollSize(...)
3760: // 'size' returned will still be equal to 5
3761: RETURNS:
3762: OCI_SUCCESS if the function completes successfully.
3763: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3764: OCI_ERROR if
3765: error during loading of nested table into object cache
3766: any of the input parameters is null
3767: */
3768:
3769: /*---------------------- OCITableExists ---------------------------------*/
3770:
3771: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3772: sword OCITableExists(/*_ OCIEnv *env, OCIError *err, CONST OCITable *tbl,
3773: sb4 index, boolean *exists _*/);
3774: #else /* ANSI C */
3775: sword OCITableExists( OCIEnv *env, OCIError *err, CONST OCITable *tbl,
3776: sb4 index, boolean *exists );
3777: #endif
3778: /*
3779: NAME: OCITableExists - OCITable test whether element at the given index
3780: EXIsts
3781: PARAMETERS:
3782: env (IN/OUT) - OCI environment handle initialized in object mode.
3783: err (IN/OUT) - error handle. If there is an error, it is
3784: recorded in 'err' and this function returns OCI_ERROR.
3785: The error recorded in 'err' can be retrieved by calling
3786: OCIErrorGet().
3787: tbl (IN) - table in which the given index is checked
3788: index (IN) - index of the element which is checked for existence
3789: exists (OUT) - set to TRUE if element at given 'index' exists
3790: else set to FALSE
3791: DESCRIPTION:
3792: Test whether an element exists at the given 'index'.
3793: RETURNS:
3794: OCI_SUCCESS if the function completes successfully.
3795: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3796: OCI_ERROR if
3797: any of the input parameters is null
3798: */
3799:
3800: /*--------------------------- OCITableDelete -------------------------------*/
3801:
3802: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3803: sword OCITableDelete(/*_ OCIEnv *env, OCIError *err, sb4 index,
3804: OCITable *tbl _*/);
3805: #else /* ANSI C */
3806: sword OCITableDelete( OCIEnv *env, OCIError *err, sb4 index,
3807: OCITable *tbl );
3808: #endif
3809: /*
3810: NAME: OCITableDelete - OCITable DELete element at the specified index
3811: PARAMETERS:
3812: env (IN/OUT) - OCI environment handle initialized in object mode.
3813: err (IN/OUT) - error handle. If there is an error, it is
3814: recorded in 'err' and this function returns OCI_ERROR.
3815: The error recorded in 'err' can be retrieved by calling
3816: OCIErrorGet().
3817: index (IN) - index of the element which must be deleted
3818: tbl (IN) - table whose element is deleted
3819: DESCRIPTION:
3820: Delete the element at the given 'index'. Note that the position
3821: ordinals of the remaining elements of the table is not changed by the
3822: delete operation. So delete creates "holes" in the table.
3823:
3824: An error is returned if the element at the specified 'index' has
3825: been previously deleted.
3826: RETURNS:
3827: OCI_SUCCESS if the function completes successfully.
3828: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3829: OCI_ERROR if
3830: any of the input parameters is null
3831: given index is not valid
3832: */
3833:
3834: /*--------------------------- OCITableFirst ---------------------------------*/
3835:
3836: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3837: sword OCITableFirst(/*_ OCIEnv *env, OCIError *err, CONST OCITable *tbl,
3838: sb4 *index _*/);
3839: #else /* ANSI C */
3840: sword OCITableFirst( OCIEnv *env, OCIError *err, CONST OCITable *tbl,
3841: sb4 *index );
3842: #endif
3843: /*
3844: NAME: OCITableFirst - OCITable return FirST index of table
3845: PARAMETERS:
3846: env (IN/OUT) - OCI environment handle initialized in object mode.
3847: err (IN/OUT) - error handle. If there is an error, it is
3848: recorded in 'err' and this function returns OCI_ERROR.
3849: The error recorded in 'err' can be retrieved by calling
3850: OCIErrorGet().
3851: tbl (IN) - table which is scanned
3852: index (OUT) - first index of the element which exists in the given
3853: table is returned
3854: DESCRIPTION:
3855: Return the first index of the element which exists in the given
3856: table.
3857: RETURNS:
3858: OCI_SUCCESS if the function completes successfully.
3859: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3860: OCI_ERROR if
3861: table is empty
3862: */
3863:
3864: /*---------------------------- OCITableLast ---------------------------------*/
3865:
3866: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3867: sword OCITableLast(/*_ OCIEnv *env, OCIError *err, CONST OCITable *tbl,
3868: sb4 *index _*/);
3869: #else /* ANSI C */
3870: sword OCITableLast( OCIEnv *env, OCIError *err, CONST OCITable *tbl,
3871: sb4 *index );
3872: #endif
3873: /*
3874: NAME: OCITableFirst - OCITable return LaST index of table
3875: PARAMETERS:
3876: env (IN/OUT) - OCI environment handle initialized in object mode.
3877: err (IN/OUT) - error handle. If there is an error, it is
3878: recorded in 'err' and this function returns OCI_ERROR.
3879: The error recorded in 'err' can be retrieved by calling
3880: OCIErrorGet().
3881: tbl (IN) - table which is scanned
3882: index (OUT) - last index of the element which exists in the given
3883: table is returned
3884: DESCRIPTION:
3885: Return the last index of the element which exists in the given
3886: table.
3887: RETURNS:
3888: OCI_SUCCESS if the function completes successfully.
3889: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3890: OCI_ERROR if
3891: table is empty
3892: */
3893:
3894: /*---------------------------- OCITableNext ---------------------------------*/
3895:
3896: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3897: sword OCITableNext(/*_ OCIEnv *env, OCIError *err, sb4 index,
3898: CONST OCITable *tbl, sb4 *next_index,
3899: boolean *exists _*/);
3900: #else /* ANSI C */
3901: sword OCITableNext( OCIEnv *env, OCIError *err, sb4 index,
3902: CONST OCITable *tbl, sb4 *next_index,
3903: boolean *exists );
3904: #endif
3905: /*
3906: NAME: OCITableNext - OCITable return NeXT available index of table
3907: PARAMETERS:
3908: env (IN/OUT) - OCI environment handle initialized in object mode.
3909: err (IN/OUT) - error handle. If there is an error, it is
3910: recorded in 'err' and this function returns OCI_ERROR.
3911: The error recorded in 'err' can be retrieved by calling
3912: OCIErrorGet().
3913: index (IN) - starting at 'index' the index of the next element
3914: which exists is returned
3915: tbl (IN) - table which is scanned
3916: next_index (OUT) - index of the next element which exists
3917: is returned
3918: exists (OUT) - FALSE if no next index available else TRUE
3919: DESCRIPTION:
3920: Return the smallest position j, greater than 'index', such that
3921: exists(j) is TRUE.
3922: RETURNS:
3923: OCI_SUCCESS if the function completes successfully.
3924: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3925: OCI_ERROR if
3926: no next index available
3927: */
3928:
3929: /*---------------------------- OCITablePrev ---------------------------------*/
3930:
3931: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
3932: sword OCITablePrev(/*_ OCIEnv *env, OCIError *err, sb4 index,
3933: CONST OCITable *tbl, sb4 *prev_index,
3934: boolean *exists _*/);
3935: #else /* ANSI C */
3936: sword OCITablePrev( OCIEnv *env, OCIError *err, sb4 index,
3937: CONST OCITable *tbl, sb4 *prev_index,
3938: boolean *exists );
3939: #endif
3940: /*
3941: NAME: OCITablePrev - OCITable return PReVious available index of table
3942: PARAMETERS:
3943: env (IN/OUT) - OCI environment handle initialized in object mode.
3944: err (IN/OUT) - error handle. If there is an error, it is
3945: recorded in 'err' and this function returns OCI_ERROR.
3946: The error recorded in 'err' can be retrieved by calling
3947: OCIErrorGet().
3948: index (IN) - starting at 'index' the index of the previous element
3949: which exists is returned
3950: tbl (IN) - table which is scanned
3951: prev_index (OUT) - index of the previous element which exists
3952: is returned
3953: exists (OUT) - FALSE if no next index available else TRUE
3954: DESCRIPTION:
3955: Return the largest position j, less than 'index', such that
3956: exists(j) is TRUE.
3957: RETURNS:
3958: OCI_SUCCESS if the function completes successfully.
3959: OCI_INVALID_HANDLE if 'env' or 'err' is NULL.
3960: OCI_ERROR if
3961: no previous index available
3962: */
3963:
3964: /*------------------------ OCINumberToLnx -----------------------------------*/
3965: /* void OCINumberToLnx(/o_ OCINumber *num _o/); */
3966:
3967: #define OCINumberToLnx(num) ((lnxnum_t *)num)
3968:
3969: /*
3970: NAME: OCINumberToLnx
3971: PARAMETERS:
3972: num (IN) - OCINumber to convert ;
3973: DESCRIPTION:
3974: Converts OCINumber to its internal lnx format
3975: This is not to be used in Public interfaces , but
3976: has been provided due to special requirements from
3977: SQLPLUS development group as they require to call
3978: Core funtions directly .
3979: */
3980:
3981: #endif /* ORL_ORACLE */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to orl.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