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