Annotation of win32/sql/oracle/include/oci/ociap.h, revision 1.1.1.1
1.1 parser 1: /*
2: * $Header: /var/lib/cvsroot/parser3/parser3/src/sql/oracle/oracle32/include/oci/ociap.h,v 1.1 2001/08/22 14:02:18 parser Exp $
3: */
4:
5: /* Copyright (c) Oracle Corporation 1996, 1997, 1998, 1999.
6: All Rights Reserved. */
7:
8: /* NOTE: See 'header_template.doc' in the 'doc' dve under the 'forms'
9: directory for the header file template that includes instructions.
10: */
11:
12: /*
13: NAME
14: ociap.h - Oracle Call Interface - Ansi Prototypes
15:
16: DESCRIPTION
17: <short description of component this file declares/defines>
18:
19: RELATED DOCUMENTS
20:
21: INSPECTION STATUS
22: Inspection date:
23: Inspection status:
24: Estimated increasing cost defects per page:
25: Rule sets:
26:
27: ACCEPTANCE REVIEW STATUS
28: Review date:
29: Review status:
30: Reviewers:
31:
32: PUBLIC FUNCTION(S)
33: <list of external functions declared/defined - with one-line descriptions>
34:
35: PRIVATE FUNCTION(S)
36: <list of static functions defined in .c file - with one-line descriptions>
37:
38: EXAMPLES
39:
40: NOTES
41: <other useful comments, qualifications, etc.>
42:
43: MODIFIED (MM/DD/YY)
44: porangas 09/22/99 - fix lines that exceed 80 chars:bug#974710
45: slari 09/01/99 - remove OCIEnvCallback
46: slari 08/23/99 - add OCIUcb in user callback functions
47: dsaha 07/07/99 - Add OCIFEnvCreate for forms
48: vyanaman 06/21/99 - Change OCI DateTime/Interval APIs.
49: esoyleme 07/01/99 - expose MTS performance enhancements
50: whe 06/14/99 - bug727872:add CONST to match definitions
51: kkarun 02/23/99 - Fix OCIDateTime APIs
52: jiyang 12/07/98 - Add comments for OCI_NLS_DUAL_CURRENCY
53: aroy 12/01/98 - add OCIEnvCreate
54: slari 11/23/98 - use ORASTDARG
55: slari 11/21/98 - replace ellipsis by arglist in OCIUserCallback
56: thchang 10/20/98 - correct comment on OCILobCreateTemporary
57: slari 09/08/98 - allow envh to receive error info also in CallbackReg/
58: kkarun 09/02/98 - Change const to CONST
59: aroy 08/04/98 - add OCITerminate calls
60: nramakri 06/25/98 - remove CONST from some OCIPickler APIs
61: jiyang 06/22/98 - Fix a lint error
62: nmallava 06/08/98 - ociistemporary -> envhp
63: jhasenbe 05/27/98 - Remove definitions for U-Calls (Unicode)
64: nmallava 05/18/98 - add comments
65: sgollapu 05/19/98 - Change text to OraText
66: aroy 04/20/98 - merge forward 8.0.5 -> 8.1.3
67: nbhatt 05/14/98 - aq listen call
68: lchidamb 03/02/98 - Client Notification prototypes
69: vyanaman 04/19/98 - System Timestamp
70: kkarun 04/17/98 - Add more Interval functions
71: vyanaman 04/17/98 - Fix min (proc error)
72: vyanaman 04/16/98 - Add get/set TZ
73: kkarun 04/13/98 - Add Datetime prototypes
74: rkasamse 04/13/98 - change OCIEnv* to dvoid* for context/memory cart serv
75: rkasamse 04/15/98 - chage pickler cart interface
76: slari 03/20/98 - change proto of OCIUserCallback
77: slari 02/17/98 - add OCIUserCallback
78: jiyang 04/02/98 - Accept both env and user handles for NLS
79: rkasamse 03/20/98 - remove prototypes for OCIMemoryDuration* functions.
80: tsaulys 03/20/98 - use environment or session handle
81: nmallava 04/09/98 - OCILobLocatorAssign
82: nmallava 04/07/98 - lobgetchunksize and writeappend apis
83: jhasenbe 04/06/98 - Add new interfaces for Unicode support
84: nmallava 03/17/98 - add interfaces
85: nmallava 03/16/98 - add open/close apis
86: nmallava 03/10/98 - add temporary lobs apis
87: sgollapu 07/10/97 - Add OCIReset
88: sgollapu 02/09/98 - OCI non-blocking
89: nramakri 01/16/98 - remove #ifdef NEVER clause for OCIExtract
90: rmurthy 01/08/98 - OCIContextGenerateKey: change ub1 to ub4
91: ewaugh 12/18/97 - Turn type wrappers into functions.
92: skabraha 12/02/97 - adding OCIFile functions
93: rhwu 12/02/97 - add OCI Thread
94: nramakri 12/15/97 - move to core4
95: nramakri 12/11/97 - modify OCIExtract prototype
96: ewaugh 12/10/97 - add OCIFormat prototypes
97: nmallava 12/17/97 - Add ilob open and close apis
98: rkasamse 12/03/97 - Change some of the function names for pickler cartrid
99: nramakri 11/12/97 - add OCIExtract prototypes
100: rkasamse 11/21/97 - add prototypes for memory cartridge services and cont
101: rkasamse 11/03/97 - Add pickler cartridge interfaces.
102: jiyang 11/11/97 - Add NLS service for cartridge
103: tanguyen 08/19/97 -
104: cxcheng 07/30/97 - replace OCISvcCtx with OCISvcCtx
105: schandra 06/25/97 - AQ OCI interface
106: bnainani 07/21/97 - add prototypes for Oracle XA extensions
107: esoyleme 05/13/97 - move failover callback prototype
108: skmishra 05/06/97 - stdc compiler fixes
109: skmishra 04/24/97 - C++ Compatibility changes
110: skotsovo 04/21/97 - make lob parameter names consistent
111: rwhitman 04/16/97 - Fix LOB prototypes - Olint OCI 8.0.3
112: ramkrish 04/15/97 - Add free flag to OCILobFlushBuffer
113: dchatter 04/10/97 - add nzt.h inclusion
114: cxcheng 04/09/97 - change objnamp from CONST text* to dvoid*
115: cxcheng 04/08/97 - fix prototype of OCIDescribeAny()
116: skotsovo 03/31/97 - remove OCILobLocatorSize
117: skotsovo 03/27/97 - add OCILobLoadFromFile
118: bcchang 02/18/97 - Fix syntax error
119: dchatter 01/13/97 - fix comments on LOB calls
120: aroy 01/10/97 - remove ocilobfilecreate delete
121: sgollapu 12/27/96 - Correct OCILogon prototype
122: dchatter 01/04/97 - comments to describe the functions
123: sgollapu 11/25/96 - Change OCILobFileIsExistent
124: schandra 11/18/96 - Remove xa.h include
125: sgollapu 11/09/96 - Change prototype of OCIDescribeAny
126: dchatter 10/31/96 - delete CONST from lob write cb fn
127: dchatter 10/30/96 - more changes
128: dchatter 10/26/96 - lob/file long name corrections
129: slari 10/16/96 - delete unused calls
130: rwessman 10/29/96 - Fixed OCISecurityGetIdentity prototype
131: bcchang 10/25/96 - Fix syntax error
132: sgollapu 10/22/96 - Add OCILogon and OCILogoff
133: rwessman 10/16/96 - Added cryptographic and digital signature functions
134: sgollapu 10/10/96 - Add ocibdp and ocibdn
135: rxgovind 10/07/96 - add oci file calls
136: skotsovo 10/01/96 - move orl lob fnts to oci
137: skotsovo 09/20/96 - in OCILobGetLength(), remove the 'isnull' parameter.
138: aroy 08/29/96 - change prototype for Nchar Lob support
139: dchatter 08/21/96 - OCIResultSetToStmt prototype change
140: sthakur 08/14/96 - add OCIParamSet
141: schandra 07/26/96 - TX OCI return values - sb4->sword
142: aroy 07/17/96 - terminology change: OCILobLocator => OCILobLocator
143: dchatter 07/01/96 - create ANSI prototypes
144: dchatter 07/01/96 - Creation
145:
146: */
147:
148:
149: #ifndef OCIAP_ORACLE
150: # define OCIAP_ORACLE
151:
152: # ifndef ORATYPES
153: # include <oratypes.h>
154: # endif
155:
156: #ifndef ORASTDARG
157: #include <stdarg.h>
158: #define ORASTDARG
159: #endif
160:
161: #ifndef OCIDFN
162: #include <ocidfn.h>
163: #endif
164:
165: #ifndef NZT_ORACLE
166: #include <nzt.h>
167: #endif /* NZT_ORACLE */
168:
169: #ifndef OCI_ORACLE
170: #include <oci.h>
171: #endif
172:
173: #ifndef ORT_ORACLE
174: #include <ort.h>
175: #endif
176:
177:
178:
179: /*---------------------------------------------------------------------------
180: PUBLIC TYPES AND CONSTANTS
181: ---------------------------------------------------------------------------*/
182:
183:
184: /*---------------------------------------------------------------------------
185: PRIVATE TYPES AND CONSTANTS
186: ---------------------------------------------------------------------------*/
187:
188:
189: /*---------------------------------------------------------------------------
190: PUBLIC FUNCTIONS
191: ---------------------------------------------------------------------------*/
192:
193: /*****************************************************************************
194: DESCRIPTION
195: ******************************************************************************
196: Note: the descriptions of the functions are alphabetically arranged. Please
197: maintain the arrangement when adding a new function description. The actual
198: prototypes are below this comment section and donot follow any alphabetical
199: ordering.
200:
201:
202: --------------------------------OCIAttrGet------------------------------------
203:
204: OCIAttrGet()
205: Name
206: OCI Attribute Get
207: Purpose
208: This call is used to get a particular attribute of a handle.
209: Syntax
210: sword OCIAttrGet ( CONST dvoid *trgthndlp,
211: ub4 trghndltyp,
212: dvoid *attributep,
213: ub4 *sizep,
214: ub4 attrtype,
215: OCIError *errhp );
216: Comments
217: This call is used to get a particular attribute of a handle.
218: See Appendix B, "Handle Attributes", for a list of handle types and their
219: readable attributes.
220: Parameters
221: trgthndlp (IN) - is the pointer to a handle type.
222: trghndltyp (IN) - is the handle type.
223: attributep (OUT) - is a pointer to the storage for an attribute value. The
224: attribute value is filled in.
225: sizep (OUT) - is the size of the attribute value.
226: This can be passed in as NULL for most parameters as the size is well known.
227: For text* parameters, a pointer to a ub4 must be passed in to get the length
228: of the string.
229: attrtype (IN) - is the type of attribute.
230: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
231: diagnostic information in the event of an error.
232: Related Functions
233: OCIAttrSet()
234:
235: --------------------------------OCIAttrSet------------------------------------
236:
237:
238: OCIAttrSet()
239: Name
240: OCI Attribute Set
241: Purpose
242: This call is used to set a particular attribute of a handle or a descriptor.
243: Syntax
244: sword OCIAttrSet ( dvoid *trgthndlp,
245: ub4 trghndltyp,
246: dvoid *attributep,
247: ub4 size,
248: ub4 attrtype,
249: OCIError *errhp );
250: Comments
251: This call is used to set a particular attribute of a handle or a descriptor.
252: See Appendix B for a list of handle types and their writeable attributes.
253: Parameters
254: trghndlp (IN/OUT) - the pointer to a handle type whose attribute gets
255: modified.
256: trghndltyp (IN/OUT) - is the handle type.
257: attributep (IN) - a pointer to an attribute value.
258: The attribute value is copied into the target handle. If the attribute value
259: is a pointer, then only the pointer is copied, not the contents of the pointer.
260: size (IN) - is the size of an attribute value. This can be passed in as 0 for
261: most attributes as the size is already known by the OCI library. For text*
262: attributes, a ub4 must be passed in set to the length of the string.
263: attrtype (IN) - the type of attribute being set.
264: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
265: diagnostic information in the event of an error.
266: Related Functions
267: OCIAttrGet()
268:
269:
270:
271: --------------------------------OCIBindArrayOfStruct--------------------------
272:
273:
274:
275: OCIBindArrayOfStruct()
276: Name
277: OCI Bind for Array of Structures
278: Purpose
279: This call sets up the skip parameters for a static array bind.
280: Syntax
281: sword OCIBindArrayOfStruct ( OCIBind *bindp,
282: OCIError *errhp,
283: ub4 pvskip,
284: ub4 indskip,
285: ub4 alskip,
286: ub4 rcskip );
287: Comments
288: This call sets up the skip parameters necessary for a static array bind.
289: This call follows a call to OCIBindByName() or OCIBindByPos(). The bind
290: handle returned by that initial bind call is used as a parameter for the
291: OCIBindArrayOfStruct() call.
292: For information about skip parameters, see the section "Arrays of Structures"
293: on page 4-16.
294: Parameters
295: bindp (IN) - the handle to a bind structure.
296: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
297: diagnostic information in the event of an error.
298: pvskip (IN) - skip parameter for the next data value.
299: indskip (IN) - skip parameter for the next indicator value or structure.
300: alskip (IN) - skip parameter for the next actual length value.
301: rcskip (IN) - skip parameter for the next column-level return code value.
302: Related Functions
303: OCIAttrGet()
304:
305:
306: --------------------------------OCIBindByName---------------------------------
307:
308: OCIBindByName()
309: Name
310: OCI Bind by Name
311: Purpose
312: Creates an association between a program variable and a placeholder in a SQL
313: statement or PL/SQL block.
314: Syntax
315: sword OCIBindByName (
316: OCIStmt *stmtp,
317: OCIBind **bindp,
318: OCIError *errhp,
319: CONST OraText *placeholder,
320: sb4 placeh_len,
321: dvoid *valuep,
322: sb4 value_sz,
323: ub2 dty,
324: dvoid *indp,
325: ub2 *alenp,
326: ub2 *rcodep,
327: ub4 maxarr_len,
328: ub4 *curelep,
329: ub4 mode );
330: Description
331: This call is used to perform a basic bind operation. The bind creates an
332: association between the address of a program variable and a placeholder in a
333: SQL statement or PL/SQL block. The bind call also specifies the type of data
334: which is being bound, and may also indicate the method by which data will be
335: provided at runtime.
336: This function also implicitly allocates the bind handle indicated by the bindp
337: parameter.
338: Data in an OCI application can be bound to placeholders statically or
339: dynamically. Binding is static when all the IN bind data and the OUT bind
340: buffers are well-defined just before the execute. Binding is dynamic when the
341: IN bind data and the OUT bind buffers are provided by the application on
342: demand at execute time to the client library. Dynamic binding is indicated by
343: setting the mode parameter of this call to OCI_DATA_AT_EXEC.
344: Related Functions: For more information about dynamic binding, see
345: the section "Runtime Data Allocation and Piecewise Operations" on
346: page 5-16.
347: Both OCIBindByName() and OCIBindByPos() take as a parameter a bind handle,
348: which is implicitly allocated by the bind call A separate bind handle is
349: allocated for each placeholder the application is binding.
350: Additional bind calls may be required to specify particular attributes
351: necessary when binding certain data types or handling input data in certain
352: ways:
353: If arrays of structures are being utilized, OCIBindArrayOfStruct() must
354: be called to set up the necessary skip parameters.
355: If data is being provided dynamically at runtime, and the application
356: will be using user-defined callback functions, OCIBindDynamic() must
357: be called to register the callbacks.
358: If a named data type is being bound, OCIBindObject() must be called to
359: specify additional necessary information.
360: Parameters
361: stmth (IN/OUT) - the statement handle to the SQL or PL/SQL statement
362: being processed.
363: bindp (IN/OUT) - a pointer to a pointer to a bind handle which is implicitly
364: allocated by this call. The bind handle maintains all the bind information for
365: this particular input value. The handle is feed implicitly when the statement
366: handle is deallocated.
367: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
368: diagnostic information in the event of an error.
369: placeholder (IN) - the placeholder attributes are specified by name if ocibindn()
370: is being called.
371: placeh_len (IN) - the length of the placeholder name specified in placeholder.
372: valuep (IN/OUT) - a pointer to a data value or an array of data values of the
373: type specified in the dty parameter. An array of data values can be specified
374: for mapping into a PL/SQL table or for providing data for SQL multiple-row
375: operations. When an array of bind values is provided, this is called an array
376: bind in OCI terms. Additional attributes of the array bind (not bind to a
377: column of ARRAY type) are set up in OCIBindArrayOfStruct() call.
378: For a REF, named data type bind, the valuep parameter is used only for IN
379: bind data. The pointers to OUT buffers are set in the pgvpp parameter
380: initialized by OCIBindObject(). For named data type and REF binds, the bind
381: values are unpickled into the Object Cache. The OCI object navigational calls
382: can then be used to navigate the objects and the refs in the Object Cache.
383: If the OCI_DATA_AT_EXEC mode is specified in the mode parameter, valuep
384: is ignored for all data types. OCIBindArrayOfStruct() cannot be used and
385: OCIBindDynamic() must be invoked to provide callback functions if desired.
386: value_sz (IN) - the size of a data value. In the case of an array bind, this is the
387: maximum size of any element possible with the actual sizes being specified in
388: the alenp parameter.
389: If the OCI_DATA_AT_EXEC mode is specified, valuesz defines the maximum
390: size of the data that can be ever provided at runtime for data types other than
391: named data types or REFs.
392: dty (IN) - the data type of the value(s) being bound. Named data types
393: (SQLT_NTY) and REFs (SQLT_REF) are valid only if the application has been
394: initialized in object mode. For named data types, or REFs, additional calls
395: must be made with the bind handle to set up the datatype-specific attributes.
396: indp (IN/OUT) - pointer to an indicator variable or array. For scalar data
397: types, this is a pointer to sb2 or an array of sb2s. For named data types,
398: this pointer is ignored and the actual pointer to the indicator structure or
399: an array of indicator structures is initialized by OCIBindObject().
400: Ignored for dynamic binds.
401: See the section "Indicator Variables" on page 2-43 for more information about
402: indicator variables.
403: alenp (IN/OUT) - pointer to array of actual lengths of array elements. Each
404: element in alenp is the length of the data in the corresponding element in the
405: bind value array before and after the execute. This parameter is ignored for
406: dynamic binds.
407: rcodep (OUT) - pointer to array of column level return codes. This parameter
408: is ignored for dynamic binds.
409: maxarr_len (IN) - the maximum possible number of elements of type dty in a
410: PL/SQL binds. This parameter is not required for non-PL/SQL binds. If
411: maxarr_len is non-zero, then either OCIBindDynamic() or
412: OCIBindArrayOfStruct() can be invoked to set up additional bind attributes.
413: curelep(IN/OUT) - a pointer to the actual number of elements. This parameter
414: is only required for PL/SQL binds.
415: mode (IN) - the valid modes for this parameter are:
416: OCI_DEFAULT. This is default mode.
417: OCI_DATA_AT_EXEC. When this mode is selected, the value_sz
418: parameter defines the maximum size of the data that can be ever
419: provided at runtime. The application must be ready to provide the OCI
420: library runtime IN data buffers at any time and any number of times.
421: Runtime data is provided in one of the two ways:
422: callbacks using a user-defined function which must be registered
423: with a subsequent call to OCIBindDynamic().
424: a polling mechanism using calls supplied by the OCI. This mode
425: is assumed if no callbacks are defined.
426: For more information about using the OCI_DATA_AT_EXEC mode, see
427: the section "Runtime Data Allocation and Piecewise Operations" on
428: page 5-16.
429: When the allocated buffers are not required any more, they should be
430: freed by the client.
431: Related Functions
432: OCIBindDynamic(), OCIBindObject(), OCIBindArrayOfStruct(), OCIAttrGet()
433:
434:
435:
436: -------------------------------OCIBindByPos-----------------------------------
437:
438:
439: OCIBindByPos()
440: Name
441: OCI Bind by Position
442: Purpose
443: Creates an association between a program variable and a placeholder in a SQL
444: statement or PL/SQL block.
445: Syntax
446: sword OCIBindByPos (
447: OCIStmt *stmtp,
448: OCIBind **bindp,
449: OCIError *errhp,
450: ub4 position,
451: dvoid *valuep,
452: sb4 value_sz,
453: ub2 dty,
454: dvoid *indp,
455: ub2 *alenp,
456: ub2 *rcodep,
457: ub4 maxarr_len,
458: ub4 *curelep,
459: ub4 mode);
460:
461: Description
462: This call is used to perform a basic bind operation. The bind creates an
463: association between the address of a program variable and a placeholder in a
464: SQL statement or PL/SQL block. The bind call also specifies the type of data
465: which is being bound, and may also indicate the method by which data will be
466: provided at runtime.
467: This function also implicitly allocates the bind handle indicated by the bindp
468: parameter.
469: Data in an OCI application can be bound to placeholders statically or
470: dynamically. Binding is static when all the IN bind data and the OUT bind
471: buffers are well-defined just before the execute. Binding is dynamic when the
472: IN bind data and the OUT bind buffers are provided by the application on
473: demand at execute time to the client library. Dynamic binding is indicated by
474: setting the mode parameter of this call to OCI_DATA_AT_EXEC.
475: Related Functions: For more information about dynamic binding, see
476: the section "Runtime Data Allocation and Piecewise Operations" on
477: page 5-16
478: Both OCIBindByName() and OCIBindByPos() take as a parameter a bind handle,
479: which is implicitly allocated by the bind call A separate bind handle is
480: allocated for each placeholder the application is binding.
481: Additional bind calls may be required to specify particular attributes
482: necessary when binding certain data types or handling input data in certain
483: ways:
484: If arrays of structures are being utilized, OCIBindArrayOfStruct() must
485: be called to set up the necessary skip parameters.
486: If data is being provided dynamically at runtime, and the application
487: will be using user-defined callback functions, OCIBindDynamic() must
488: be called to register the callbacks.
489: If a named data type is being bound, OCIBindObject() must be called to
490: specify additional necessary information.
491: Parameters
492: stmth (IN/OUT) - the statement handle to the SQL or PL/SQL statement
493: being processed.
494: bindp (IN/OUT) - a pointer to a pointer to a bind handle which is implicitly
495: allocated by this call. The bind handle maintains all the bind information for
496: this particular input value. The handle is feed implicitly when the statement
497: handle is deallocated.
498: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
499: diagnostic information in the event of an error.
500: position (IN) - the placeholder attributes are specified by position if ocibindp()
501: is being called.
502: valuep (IN/OUT) - a pointer to a data value or an array of data values of the
503: type specified in the dty parameter. An array of data values can be specified
504: for mapping into a PL/SQL table or for providing data for SQL multiple-row
505: operations. When an array of bind values is provided, this is called an array
506: bind in OCI terms. Additional attributes of the array bind (not bind to a
507: column of ARRAY type) are set up in OCIBindArrayOfStruct() call.
508: For a REF, named data type bind, the valuep parameter is used only for IN
509: bind data. The pointers to OUT buffers are set in the pgvpp parameter
510: initialized by OCIBindObject(). For named data type and REF binds, the bind
511: values are unpickled into the Object Cache. The OCI object navigational calls
512: can then be used to navigate the objects and the refs in the Object Cache.
513: If the OCI_DATA_AT_EXEC mode is specified in the mode parameter, valuep
514: is ignored for all data types. OCIBindArrayOfStruct() cannot be used and
515: OCIBindDynamic() must be invoked to provide callback functions if desired.
516: value_sz (IN) - the size of a data value. In the case of an array bind, this is the
517: maximum size of any element possible with the actual sizes being specified in
518: the alenp parameter.
519: If the OCI_DATA_AT_EXEC mode is specified, valuesz defines the maximum
520: size of the data that can be ever provided at runtime for data types other than
521: named data types or REFs.
522: dty (IN) - the data type of the value(s) being bound. Named data types
523: (SQLT_NTY) and REFs (SQLT_REF) are valid only if the application has been
524: initialized in object mode. For named data types, or REFs, additional calls
525: must be made with the bind handle to set up the datatype-specific attributes.
526: indp (IN/OUT) - pointer to an indicator variable or array. For scalar data
527: types, this is a pointer to sb2 or an array of sb2s. For named data types,
528: this pointer is ignored and the actual pointer to the indicator structure or
529: an array of indicator structures is initialized by OCIBindObject(). Ignored
530: for dynamic binds.
531: See the section "Indicator Variables" on page 2-43 for more information about
532: indicator variables.
533: alenp (IN/OUT) - pointer to array of actual lengths of array elements. Each
534: element in alenp is the length of the data in the corresponding element in the
535: bind value array before and after the execute. This parameter is ignored for
536: dynamic binds.
537: rcodep (OUT) - pointer to array of column level return codes. This parameter
538: is ignored for dynamic binds.
539: maxarr_len (IN) - the maximum possible number of elements of type dty in a
540: PL/SQL binds. This parameter is not required for non-PL/SQL binds. If
541: maxarr_len is non-zero, then either OCIBindDynamic() or
542: OCIBindArrayOfStruct() can be invoked to set up additional bind attributes.
543: curelep(IN/OUT) - a pointer to the actual number of elements. This parameter
544: is only required for PL/SQL binds.
545: mode (IN) - the valid modes for this parameter are:
546: OCI_DEFAULT. This is default mode.
547: OCI_DATA_AT_EXEC. When this mode is selected, the value_sz
548: parameter defines the maximum size of the data that can be ever
549: provided at runtime. The application must be ready to provide the OCI
550: library runtime IN data buffers at any time and any number of times.
551: Runtime data is provided in one of the two ways:
552: callbacks using a user-defined function which must be registered
553: with a subsequent call to OCIBindDynamic() .
554: a polling mechanism using calls supplied by the OCI. This mode
555: is assumed if no callbacks are defined.
556: For more information about using the OCI_DATA_AT_EXEC mode, see
557: the section "Runtime Data Allocation and Piecewise Operations" on
558: page 5-16.
559: When the allocated buffers are not required any more, they should be
560: freed by the client.
561: Related Functions
562: OCIBindDynamic(), OCIBindObject(), OCIBindArrayOfStruct(), OCIAttrGet()
563:
564:
565:
566: -------------------------------OCIBindDynamic---------------------------------
567:
568: OCIBindDynamic()
569: Name
570: OCI Bind Dynamic Attributes
571: Purpose
572: This call is used to register user callbacks for dynamic data allocation.
573: Syntax
574: sword OCIBindDynamic( OCIBind *bindp,
575: OCIError *errhp,
576: dvoid *ictxp,
577: OCICallbackInBind (icbfp)(
578: dvoid *ictxp,
579: OCIBind *bindp,
580: ub4 iter,
581: ub4 index,
582: dvoid **bufpp,
583: ub4 *alenp,
584: ub1 *piecep,
585: dvoid **indp ),
586: dvoid *octxp,
587: OCICallbackOutBind (ocbfp)(
588: dvoid *octxp,
589: OCIBind *bindp,
590: ub4 iter,
591: ub4 index,
592: dvoid **bufp,
593: ub4 **alenpp,
594: ub1 *piecep,
595: dvoid **indpp,
596: ub2 **rcodepp) );
597: Comments
598: This call is used to register user-defined callback functions for providing
599: data for an UPDATE or INSERT if OCI_DATA_AT_EXEC mode was specified in a
600: previous call to OCIBindByName() or OCIBindByPos().
601: The callback function pointers must return OCI_CONTINUE if it the call is
602: successful. Any return code other than OCI_CONTINUE signals that the client
603: wishes to abort processing immediately.
604: For more information about the OCI_DATA_AT_EXEC mode, see the section
605: "Runtime Data Allocation and Piecewise Operations" on page 5-16.
606: Parameters
607: bindp (IN/OUT) - a bind handle returned by a call to OCIBindByName() or
608: OCIBindByPos().
609: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
610: diagnostic information in the event of an error.
611: ictxp (IN) - the context pointer required by the call back function icbfp.
612: icbfp (IN) - the callback function which returns a pointer to the IN bind
613: value or piece at run time. The callback takes in the following parameters.
614: ictxp (IN/OUT) - the context pointer for this callback function.
615: bindp (IN) - the bind handle passed in to uniquely identify this bind
616: variable.
617: iter (IN) - 1-based execute iteration value.
618: index (IN) - index of the current array, for an array bind. 1 based not
619: greater than curele parameter of the bind call.
620: index (IN) - index of the current array, for an array bind. This parameter
621: is 1-based, and may not be greater than curele parameter of the bind call.
622: bufpp (OUT) - the pointer to the buffer.
623: piecep (OUT) - which piece of the bind value. This can be one of the
624: following values - OCI_ONE_PIECE, OCI_FIRST_PIECE,
625: OCI_NEXT_PIECE and OCI_LAST_PIECE.
626: indp (OUT) - contains the indicator value. This is apointer to either an
627: sb2 value or a pointer to an indicator structure for binding named data
628: types.
629: indszp (OUT) - contains the indicator value size. A pointer containing
630: the size of either an sb2 or an indicator structure pointer.
631: octxp (IN) - the context pointer required by the callback function ocbfp.
632: ocbfp (IN) - the callback function which returns a pointer to the OUT bind
633: value or piece at run time. The callback takes in the following parameters.
634: octxp (IN/OUT) - the context pointer for this call back function.
635: bindp (IN) - the bind handle passed in to uniquely identify this bind
636: variable.
637: iter (IN) - 1-based execute iteration value.
638: index (IN) - index of the current array, for an array bind. This parameter
639: is 1-based, and must not be greater than curele parameter of the bind call.
640: bufpp (OUT) - a pointer to a buffer to write the bind value/piece.
641: buflp (OUT) - returns the buffer size.
642: alenpp (OUT) - a pointer to a storage for OCI to fill in the size of the bind
643: value/piece after it has been read.
644: piecep (IN/OUT) - which piece of the bind value. It will be set by the
645: library to be one of the following values - OCI_ONE_PIECE or
646: OCI_NEXT_PIECE. The callback function can leave it unchanged or set
647: it to OCI_FIRST_PIECE or OCI_LAST_PIECE. By default -
648: OCI_ONE_PIECE.
649: indpp (OUT) - returns a pointer to contain the indicator value which
650: either an sb2 value or a pointer to an indicator structure for named data
651: types.
652: indszpp (OUT) - returns a pointer to return the size of the indicator
653: value which is either size of an sb2 or size of an indicator structure.
654: rcodepp (OUT) - returns a pointer to contains the return code.
655: Related Functions
656: OCIAttrGet()
657:
658:
659: ---------------------------------OCIBindObject--------------------------------
660:
661:
662: OCIBindObject()
663: Name
664: OCI Bind Object
665: Purpose
666: This function sets up additional attributes which are required for a named
667: data type (object) bind.
668: Syntax
669: sword OCIBindObject ( OCIBind *bindp,
670: OCIError *errhp,
671: CONST OCIType *type,
672: dvoid **pgvpp,
673: ub4 *pvszsp,
674: dvoid **indpp,
675: ub4 *indszp, );
676: Comments
677: This function sets up additional attributes which binding a named data type
678: or a REF. An error will be returned if this function is called when the OCI
679: environment has been initialized in non-object mode.
680: This call takes as a paramter a type descriptor object (TDO) of datatype
681: OCIType for the named data type being defined. The TDO can be retrieved
682: with a call to OCITypeByName().
683: If the OCI_DATA_AT_EXEC mode was specified in ocibindn() or ocibindp(), the
684: pointers to the IN buffers are obtained either using the callback icbfp
685: registered in the OCIBindDynamic() call or by the OCIStmtSetPieceInfo() call.
686: The buffers are dynamically allocated for the OUT data and the pointers to
687: these buffers are returned either by calling ocbfp() registered by the
688: OCIBindDynamic() or by setting the pointer to the buffer in the buffer passed
689: in by OCIStmtSetPieceInfo() called when OCIStmtExecute() returned
690: OCI_NEED_DATA. The memory of these client library- allocated buffers must be
691: freed when not in use anymore by using the OCIObjectFreee() call.
692: Parameters
693: bindp ( IN/OUT) - the bind handle returned by the call to OCIBindByName()
694: or OCIBindByPos().
695: errhp ( IN/OUT) - an error handle which can be passed to OCIErrorGet() for
696: diagnostic information in the event of an error.
697: type ( IN) - points to the TDO which describes the type of the program
698: variable being bound. Retrieved by calling OCITypeByName().
699: pgvpp ( IN/OUT) - points to a pointer to the program variable buffer. For an
700: array, pgvpp points to an array of pointers. When the bind variable is also an
701: OUT variable, the OUT Named Data Type value or REF is allocated
702: (unpickled) in the Object Cache, and a pointer to the value or REF is returned,
703: At the end of execute, when all OUT values have been received, pgvpp points
704: to an array of pointer(s) to these newly allocated named data types in the
705: object cache.
706: pgvpp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the Named
707: Data Type buffers are requested at runtime. For static array binds, skip
708: factors may be specified using the OCIBindArrayOfStruct() call. The skip
709: factors are used to compute the address of the next pointer to the value, the
710: indicator structure and their sizes.
711: pvszsp ( IN/OUT) - points to the size of the program variable. The size of the
712: named data type is not required on input. For an array, pvszsp is an array of
713: ub4s. On return, for OUT bind variables, this points to size(s) of the Named
714: Data Types and REFs received. pvszsp is ignored if the OCI_DATA_AT_EXEC
715: mode is set. Then the size of the buffer is taken at runtime.
716: indpp ( IN/OUT) - points to a pointer to the program variable buffer
717: containing the parallel indicator structure. For an array, points to an array of
718: pointers. When the bind variable is also an OUT bind variable, memory is
719: allocated in the object cache, to store the unpickled OUT indicator values. At
720: the end of the execute when all OUT values have been received, indpp points
721: to the pointer(s) to these newly allocated indicator structure(s).
722: indpp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the indicator
723: is requested at runtime.
724: indszp ( IN/OUT) - points to the size of the IN indicator structure program
725: variable. For an array, it is an array of sb2s. On return for OUT bind variables,
726: this points to size(s) of the received OUT indicator structures.
727: indszp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the indicator
728: size is requested at runtime.
729: Related Functions
730: OCIAttrGet()
731:
732:
733:
734: ----------------------------------OCIBreak------------------------------------
735:
736:
737: OCIBreak()
738: Name
739: OCI Break
740: Purpose
741: This call performs an immediate (asynchronous) abort of any currently
742: executing OCI function that is associated with a server .
743: Syntax
744: sword OCIBreak ( dvoid *hndlp,
745: OCIError *errhp);
746: Comments
747: This call performs an immediate (asynchronous) abort of any currently
748: executing OCI function that is associated with a server. It is normally used
749: to stop a long-running OCI call being processed on the server.
750: This call can take either the service context handle or the server context
751: handle as a parameter to identify the function to be aborted.
752: Parameters
753: hndlp (IN) - the service context handle or the server context handle.
754: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
755: diagnostic information in the event of an error.
756: Related Functions
757:
758: ------------------------------OCIDateTimeAssign --------------------------
759: sword OCIDateTimeAssign(dvoid *hndl, OCIError *err, CONST OCIDateTime *from,
760: OCIDateTime *to);
761: NAME: OCIDateTimeAssign - OCIDateTime Assignment
762: PARAMETERS:
763: hndl (IN) - Session/Env handle.
764: err (IN/OUT) - error handle. If there is an error, it is
765: recorded in 'err' and this function returns OCI_ERROR.
766: The error recorded in 'err' can be retrieved by calling
767: OCIErrorGet().
768: from (IN) - datetime to be assigned
769: to (OUT) - lhs of assignment
770: DESCRIPTION:
771: Performs date assignment. The type of the output will be same as that
772: of input
773:
774: ------------------------------OCIDateTimeCheck----------------------------
775: sword OCIDateTimeCheck(dvoid *hndl, OCIError *err, CONST OCIDateTime *date,
776: ub4 *valid );
777: NAME: OCIDateTimeCheck - OCIDateTime CHecK if the given date is valid
778: PARAMETERS:
779: hndl (IN) - Session/Env handle.
780: err (IN/OUT) - error handle. If there is an error, it is
781: recorded in 'err' and this function returns OCI_ERROR.
782: The error recorded in 'err' can be retrieved by calling
783: OCIErrorGet().
784: date (IN) - date to be checked
785: valid (OUT) - returns zero for a valid date, otherwise
786: the ORed combination of all error bits specified below:
787: Macro name Bit number Error
788: ---------- ---------- -----
789: OCI_DATE_INVALID_DAY 0x1 Bad day
790: OCI_DATE_DAY_BELOW_VALID 0x2 Bad DAy Low/high bit (1=low)
791: OCI_DATE_INVALID_MONTH 0x4 Bad MOnth
792: OCI_DATE_MONTH_BELOW_VALID 0x8 Bad MOnth Low/high bit (1=low)
793: OCI_DATE_INVALID_YEAR 0x10 Bad YeaR
794: OCI_DATE_YEAR_BELOW_VALID 0x20 Bad YeaR Low/high bit (1=low)
795: OCI_DATE_INVALID_HOUR 0x40 Bad HouR
796: OCI_DATE_HOUR_BELOW_VALID 0x80 Bad HouR Low/high bit (1=low)
797: OCI_DATE_INVALID_MINUTE 0x100 Bad MiNute
798: OCI_DATE_MINUTE_BELOW_VALID 0x200 Bad MiNute Low/high bit (1=low)
799: OCI_DATE_INVALID_SECOND 0x400 Bad SeCond
800: OCI_DATE_SECOND_BELOW_VALID 0x800 bad second Low/high bit (1=low)
801: OCI_DATE_DAY_MISSING_FROM_1582 0x1000 Day is one of those "missing"
802: from 1582
803: OCI_DATE_YEAR_ZERO 0x2000 Year may not equal zero
804: OCI_DATE_INVALID_TIMEZONE 0x4000 Bad Timezone
805: OCI_DATE_INVALID_FORMAT 0x8000 Bad date format input
806:
807: So, for example, if the date passed in was 2/0/1990 25:61:10 in
808: (month/day/year hours:minutes:seconds format), the error returned
809: would be OCI_DATE_INVALID_DAY | OCI_DATE_DAY_BELOW_VALID |
810: OCI_DATE_INVALID_HOUR | OCI_DATE_INVALID_MINUTE
811:
812: DESCRIPTION:
813: Check if the given date is valid.
814: RETURNS:
815: OCI_SUCCESS if the function completes successfully.
816: OCI_INVALID_HANDLE if 'err' is NULL.
817: OCI_ERROR if
818: 'date' and 'valid' pointers are NULL pointers
819:
820: ------------------------------- OCIDateTimeCompare----------------------------
821: sword OCIDateTimeCompare(dvoid *hndl, OCIError *err, CONST OCIDateTime *date1,
822: CONST OCIDateTime *date2, sword *result );
823: NAME: OCIDateTimeCompare - OCIDateTime CoMPare dates
824: PARAMETERS:
825: hndl (IN) - Session/Env handle.
826: err (IN/OUT) - error handle. If there is an error, it is
827: recorded in 'err' and this function returns OCI_ERROR.
828: The error recorded in 'err' can be retrieved by calling
829: OCIErrorGet().
830: date1, date2 (IN) - dates to be compared
831: result (OUT) - comparison result, 0 if equal, -1 if date1 < date2,
832: 1 if date1 > date2
833: DESCRIPTION:
834: The function OCIDateCompare compares two dates. It returns -1 if
835: date1 is smaller than date2, 0 if they are equal, and 1 if date1 is
836: greater than date2.
837: RETURNS:
838: OCI_SUCCESS if the function completes successfully.
839: OCI_INVALID_HANDLE if 'err' is NULL.
840: OCI_ERROR if
841: invalid date
842: input dates are not mutually comparable
843:
844: ------------------------------OCIDateTimeConvert----------------------
845: sword OCIDateTimeConvert(dvoid *hndl, OCIError *err, OCIDateTime *indate,
846: OCIDateTime *outdate);
847: NAME: OCIDateTimeConvert - Conversion between different DATETIME types
848: PARAMETERS:
849: hndl (IN) - Session/Env handle.
850: err (IN/OUT) - error handle. If there is an error, it is
851: recorded in 'err' and this function returns OCI_ERROR.
852: The error recorded in 'err' can be retrieved by calling
853: OCIErrorGet().
854: indate (IN) - pointer to input date
855: outdate (OUT) - pointer to output datetime
856: DESCRIPTION: Converts one datetime type to another. The result type is
857: the type of the 'outdate' descriptor.
858: RETURNS:
859: OCI_SUCCESS if the function completes successfully.
860: OCI_INVALID_HANDLE if 'err' is NULL.
861: OCI_ERROR if
862: conversion not possible.
863:
864: ---------------------------- OCIDateTimeFromText-----------------------
865: sword OCIDateTimeFromText(dvoid *hndl, OCIError *err, CONST OraText *date_str,
866: size_t d_str_length, CONST OraText *fmt, ub1 fmt_length,
867: CONST OraText *lang_name, size_t lang_length, OCIDateTime *date );
868: NAME: OCIDateTimeFromText - OCIDateTime convert String FROM Date
869: PARAMETERS:
870: hndl (IN) - Session/Env handle. If Session Handle is passed, the
871: conversion takes place in session NLS_LANGUAGE and
872: session NLS_CALENDAR, otherwise the default is used.
873: err (IN/OUT) - error handle. If there is an error, it is
874: recorded in 'err' and this function returns OCI_ERROR.
875: The error recorded in 'err' can be retrieved by calling
876: OCIErrorGet().
877: date_str (IN) - input string to be converted to Oracle date
878: d_str_length (IN) - size of the input string, if the length is -1
879: then 'date_str' is treated as a null terminated string
880: fmt (IN) - conversion format; if 'fmt' is a null pointer, then
881: the string is expected to be in the default format for
882: the datetime type.
883: fmt_length (IN) - length of the 'fmt' parameter
884: lang_name (IN) - language in which the names and abbreviations of
885: days and months are specified, if null i.e. (OraText *)0,
886: the default language of session is used,
887: lang_length (IN) - length of the 'lang_name' parameter
888: date (OUT) - given string converted to date
889: DESCRIPTION:
890: Converts the given string to Oracle datetime type set in the
891: OCIDateTime descriptor according to the specified format. Refer to
892: "TO_DATE" conversion function described in "Oracle SQL Language
893: Reference Manual" for a description of format.
894: RETURNS:
895: OCI_SUCCESS if the function completes successfully.
896: OCI_INVALID_HANDLE if 'err' is NULL.
897: OCI_ERROR if
898: invalid format
899: unknown language
900: invalid input string
901:
902: --------------------------- OCIDateTimeGetDate-------------------------
903: sword OCIDateTimeGetDate(dvoid *hndl, OCIError *err, CONST OCIDateTime *date,
904: sb2 *year, ub1 *month, ub1 *day );
905: NAME: OCIDateTimeGetDate - OCIDateTime Get Date (year, month, day)
906: portion of DATETIME.
907: PARAMETERS:
908: hndl (IN) - Session/Env handle.
909: err (IN/OUT) - error handle. If there is an error, it is
910: recorded in 'err' and this function returns OCI_ERROR.
911: The error recorded in 'err' can be retrieved by calling
912: OCIErrorGet().
913: datetime (IN) - Pointer to OCIDateTime
914: year (OUT) - year value
915: month (OUT) - month value
916: day (OUT) - day value
917:
918: --------------------------- OCIDateTimeGetTime ------------------------
919: sword OCIDateTimeGetTime(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
920: ub1 *hour, ub1 *minute, ub1 *sec, ub4 *fsec);
921: NAME: OCIDateTimeGetTime - OCIDateTime Get Time (hour, min, second,
922: fractional second) of DATETIME.
923: PARAMETERS:
924: hndl (IN) - Session/Env handle.
925: err (IN/OUT) - error handle. If there is an error, it is
926: recorded in 'err' and this function returns OCI_ERROR.
927: The error recorded in 'err' can be retrieved by calling
928: OCIErrorGet().
929: datetime (IN) - Pointer to OCIDateTime
930: hour (OUT) - hour value
931: minute (OUT) - minute value
932: sec (OUT) - second value
933: fsec (OUT) - Fractional Second value
934:
935: --------------------------- OCIDateTimeGetTimeZoneOffset ----------------------
936: sword OCIDateTimeGetTimeZoneOffset(dvoid *hndl,OCIError *err,CONST
937: OCIDateTime *datetime,sb1 *hour,sb1 *minute);
938:
939: NAME: OCIDateTimeGetTimeZoneOffset - OCIDateTime Get TimeZone (hour, minute)
940: portion of DATETIME.
941: PARAMETERS:
942: hndl (IN) - Session/Env handle.
943: err (IN/OUT) - error handle. If there is an error, it is
944: recorded in 'err' and this function returns OCI_ERROR.
945: The error recorded in 'err' can be retrieved by calling
946: OCIErrorGet().
947: datetime (IN) - Pointer to OCIDateTime
948: hour (OUT) - TimeZone Hour value
949: minute (OUT) - TimeZone Minute value
950:
951: --------------------------- OCIDateTimeSysTimeStamp---------------------
952: sword OCIDateTimeSysTimeStamp(dvoid *hndl, OCIError *err,
953: OCIDateTime *sys_date );
954:
955: NAME: OCIDateTimeSysTimeStamp - Returns system date/time as a TimeStamp with
956: timezone
957: PARAMETERS:
958: hndl (IN) - Session/Env handle.
959: err (IN/OUT) - error handle. If there is an error, it is
960: recorded in 'err' and this function returns OCI_ERROR.
961: The error recorded in 'err' can be retrieved by calling
962: OCIErrorGet().
963: sys_date (OUT) - Pointer to output timestamp
964:
965: DESCRIPTION:
966: Gets the system current date and time as a timestamp with timezone
967: RETURNS:
968: OCI_SUCCESS if the function completes successfully.
969: OCI_INVALID_HANDLE if 'err' is NULL.
970:
971:
972: ------------------------------OCIDateTimeIntervalAdd----------------------
973: sword OCIDateTimeIntervalAdd(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
974: OCIInterval *inter, OCIDateTime *outdatetime);
975: NAME: OCIDateTimeIntervalAdd - Adds an interval to datetime
976: PARAMETERS:
977: hndl (IN) - Session/Env handle.
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: datetime (IN) - pointer to input datetime
983: inter (IN) - pointer to interval
984: outdatetime (IN) - pointer to output datetime. The output datetime
985: will be of same type as input datetime
986: DESCRIPTION:
987: Adds an interval to a datetime to produce a resulting datetime
988: RETURNS:
989: OCI_SUCCESS if the function completes successfully.
990: OCI_INVALID_HANDLE if 'err' is NULL.
991: OCI_ERROR if:
992: resulting date is before Jan 1, -4713
993: resulting date is after Dec 31, 9999
994:
995: ------------------------------OCIDateTimeIntervalSub----------------------
996: sword OCIDateTimeIntervalSub(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
997: OCIInterval *inter, OCIDateTime *outdatetime);
998: NAME: OCIDateTimeIntervalSub - Subtracts an interval from a datetime
999: PARAMETERS:
1000: hndl (IN) - Session/Env handle.
1001: err (IN/OUT) - error handle. If there is an error, it is
1002: recorded in 'err' and this function returns OCI_ERROR.
1003: The error recorded in 'err' can be retrieved by calling
1004: OCIErrorGet().
1005: datetime (IN) - pointer to input datetime
1006: inter (IN) - pointer to interval
1007: outdatetime (IN) - pointer to output datetime. The output datetime
1008: will be of same type as input datetime
1009: DESCRIPTION:
1010: Subtracts an interval from a datetime and stores the result in a
1011: datetime
1012: RETURNS:
1013: OCI_SUCCESS if the function completes successfully.
1014: OCI_INVALID_HANDLE if 'err' is NULL.
1015: OCI_ERROR if:
1016: resulting date is before Jan 1, -4713
1017: resulting date is after Dec 31, 9999
1018:
1019: --------------------------- OCIDateTimeConstruct-------------------------
1020: sword OCIDateTimeConstruct(dvoid *hndl,OCIError *err,OCIDateTime *datetime,
1021: sb2 year,ub1 month,ub1 day,ub1 hour,ub1 min,ub1 sec,ub4 fsec,
1022: OraText *timezone,size_t timezone_length);
1023:
1024: NAME: OCIDateTimeConstruct - Construct an OCIDateTime. Only the relevant
1025: fields for the OCIDateTime descriptor types are used.
1026: PARAMETERS:
1027: hndl (IN) - Session/Env handle.
1028: err (IN/OUT) - error handle. If there is an error, it is
1029: recorded in 'err' and this function returns OCI_ERROR.
1030: The error recorded in 'err' can be retrieved by calling
1031: OCIErrorGet().
1032: datetime (IN) - Pointer to OCIDateTime
1033: year (IN) - year value
1034: month (IN) - month value
1035: day (IN) - day value
1036: hour (IN) - hour value
1037: min (IN) - minute value
1038: sec (IN) - second value
1039: fsec (IN) - Fractional Second value
1040: timezone (IN) - Timezone string
1041: timezone_length(IN) - Length of timezone string
1042:
1043: DESCRIPTION:
1044: Constructs a DateTime descriptor. The type of the datetime is the
1045: type of the OCIDateTime descriptor. Only the relevant fields based
1046: on the type are used. For Types with timezone, the date and time
1047: fields are assumed to be in the local time of the specified timezone.
1048: If timezone is not specified, then session default timezone is
1049: assumed.
1050: RETURNS:
1051: OCI_SUCCESS if the function completes successfully.
1052: OCI_ERROR if datetime is not valid.
1053:
1054: ------------------------------OCIDateTimeSubtract-----------------------
1055: sword OCIDateTimeSubtract(dvoid *hndl, OCIError *err, OCIDateTime *indate1,
1056: OCIDateTime *indate2, OCIInterval *inter);
1057: NAME: OCIDateTimeSubtract - subtracts two datetimes to return an interval
1058: PARAMETERS:
1059: hndl (IN) - Session/Env handle.
1060: err (IN/OUT) - error handle. If there is an error, it is
1061: recorded in 'err' and this function returns OCI_ERROR.
1062: The error recorded in 'err' can be retrieved by calling
1063: OCIErrorGet().
1064: indate1(IN) - pointer to subtrahend
1065: indate2(IN) - pointer to minuend
1066: inter (OUT) - pointer to output interval
1067: DESCRIPTION:
1068: Takes two datetimes as input and stores their difference in an
1069: interval. The type of the interval is the type of the 'inter'
1070: descriptor.
1071: RETURNS:
1072: OCI_SUCCESS if the function completes successfully.
1073: OCI_INVALID_HANDLE if 'err' is NULL.
1074: OCI_ERROR if
1075: datetimes are not comparable.
1076:
1077: --------------------------- OCIDateTimeToText--------------------------
1078: sword OCIDateTimeToText(dvoid *hndl, OCIError *err, CONST OCIDateTime *date,
1079: CONST OraText *fmt, ub1 fmt_length, ub1 fsprec,
1080: CONST OraText *lang_name, size_t lang_length,
1081: size_t *buf_size, OraText *buf );
1082: NAME: OCIDateTimeToText - OCIDateTime convert date TO String
1083: PARAMETERS:
1084: hndl (IN) - Session/Env handle. If Session Handle is passed, the
1085: conversion takes place in session NLS_LANGUAGE and
1086: session NLS_CALENDAR, otherwise the default is used.
1087: err (IN/OUT) - error handle. If there is an error, it is
1088: recorded in 'err' and this function returns OCI_ERROR.
1089: The error recorded in 'err' can be retrieved by calling
1090: OCIErrorGet().
1091: date (IN) - Oracle datetime to be converted
1092: fmt (IN) - conversion format, if null string pointer (OraText*)0, then
1093: the date is converted to a character string in the
1094: default format for that type.
1095: fmt_length (IN) - length of the 'fmt' parameter
1096: fsprec (IN) - specifies the fractional second precision in which the
1097: fractional seconds is returned.
1098: lang_name (IN) - specifies the language in which the names and
1099: abbreviations of months and days are returned;
1100: default language of session is used if 'lang_name'
1101: is null i.e. (OraText *)0
1102: lang_length (IN) - length of the 'nls_params' parameter
1103: buf_size (IN/OUT) - size of the buffer; size of the resulting string
1104: is returned via this parameter
1105: buf (OUT) - buffer into which the converted string is placed
1106: DESCRIPTION:
1107: Converts the given date to a string according to the specified format.
1108: Refer to "TO_DATE" conversion function described in
1109: "Oracle SQL Language Reference Manual" for a description of format
1110: and NLS arguments. The converted null-terminated date string is
1111: stored in the buffer 'buf'.
1112: RETURNS:
1113: OCI_SUCCESS if the function completes successfully.
1114: OCI_INVALID_HANDLE if 'err' is NULL.
1115: OCI_ERROR if
1116: buffer too small
1117: invalid format
1118: unknown language
1119: overflow error
1120:
1121:
1122: ------------------------------OCIDefineArrayOfStruct--------------------------
1123:
1124:
1125: OCIDefineArrayOfStruct()
1126: Name
1127: OCI Define for Array of Structures
1128: Purpose
1129: This call specifies additional attributes necessary for a static array define.
1130: Syntax
1131: sword OCIDefineArrayOfStruct ( OCIDefine *defnp,
1132: OCIError *errhp,
1133: ub4 pvskip,
1134: ub4 indskip,
1135: ub4 rlskip,
1136: ub4 rcskip );
1137: Comments
1138: This call specifies additional attributes necessary for an array define, used in
1139: an array of structures (multi-row, multi-column) fetch.
1140: For more information about skip parameters, see the section "Skip Parameters"
1141: on page 4-17.
1142: Parameters
1143: defnp (IN) - the handle to the define structure which was returned by a call
1144: to OCIDefineByPos().
1145: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
1146: diagnostic information in the event of an error.
1147: pvskip (IN) - skip parameter for the next data value.
1148: indskip (IN) - skip parameter for the next indicator location.
1149: rlskip (IN) - skip parameter for the next return length value.
1150: rcskip (IN) - skip parameter for the next return code.
1151: Related Functions
1152: OCIAttrGet()
1153:
1154:
1155:
1156:
1157:
1158: OCIDefineByPos()
1159: Name
1160: OCI Define By Position
1161: Purpose
1162: Associates an item in a select-list with the type and output data buffer.
1163: Syntax
1164: sb4 OCIDefineByPos (
1165: OCIStmt *stmtp,
1166: OCIDefine **defnp,
1167: OCIError *errhp,
1168: ub4 position,
1169: dvoid *valuep,
1170: sb4 value_sz,
1171: ub2 dty,
1172: dvoid *indp,
1173: ub2 *rlenp,
1174: ub2 *rcodep,
1175: ub4 mode );
1176: Comments
1177: This call defines an output buffer which will receive data retreived from
1178: Oracle. The define is a local step which is necessary when a SELECT statement
1179: returns data to your OCI application.
1180: This call also implicitly allocates the define handle for the select-list item.
1181: Defining attributes of a column for a fetch is done in one or more calls. The
1182: first call is to OCIDefineByPos(), which defines the minimal attributes
1183: required to specify the fetch.
1184: This call takes as a parameter a define handle, which must have been
1185: previously allocated with a call to OCIHandleAlloc().
1186: Following the call to OCIDefineByPos() additional define calls may be
1187: necessary for certain data types or fetch modes:
1188: A call to OCIDefineArrayOfStruct() is necessary to set up skip parameters
1189: for an array fetch of multiple columns.
1190: A call to OCIDefineObject() is necessary to set up the appropriate
1191: attributes of a named data type fetch. In this case the data buffer pointer
1192: in ocidefn() is ignored.
1193: Both OCIDefineArrayOfStruct() and OCIDefineObject() must be called
1194: after ocidefn() in order to fetch multiple rows with a column of named
1195: data types.
1196: For a LOB define, the buffer pointer must be a lob locator of type
1197: OCILobLocator , allocated by the OCIDescAlloc() call. LOB locators, and not
1198: LOB values, are always returned for a LOB column. LOB values can then be
1199: fetched using OCI LOB calls on the fetched locator.
1200: For NCHAR (fixed and varying length), the buffer pointer must point to an
1201: array of bytes sufficient for holding the required NCHAR characters.
1202: Nested table columns are defined and fetched like any other named data type.
1203: If the mode parameter is this call is set to OCI_DYNAMIC_FETCH, the client
1204: application can fetch data dynamically at runtime.
1205: Runtime data can be provided in one of two ways:
1206: callbacks using a user-defined function which must be registered with a
1207: subsequent call to OCIDefineDynamic(). When the client library needs a
1208: buffer to return the fetched data, the callback will be invoked and the
1209: runtime buffers provided will return a piece or the whole data.
1210: a polling mechanism using calls supplied by the OCI. This mode is
1211: assumed if no callbacks are defined. In this case, the fetch call returns the
1212: OCI_NEED_DATA error code, and a piecewise polling method is used
1213: to provide the data.
1214: Related Functions: For more information about using the
1215: OCI_DYNAMIC_FETCH mode, see the section "Runtime Data
1216: Allocation and Piecewise Operations" on page 5-16 of Volume 1..
1217: For more information about the define step, see the section "Defining"
1218: on page 2-30.
1219: Parameters
1220: stmtp (IN) - a handle to the requested SQL query operation.
1221: defnp (IN/OUT) - a pointer to a pointer to a define handle which is implicitly
1222: allocated by this call. This handle is used to store the define information
1223: for this column.
1224: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
1225: diagnostic information in the event of an error.
1226: position (IN) - the position of this value in the select list. Positions are
1227: 1-based and are numbered from left to right. For example, in the SELECT
1228: statement
1229: SELECT empno, ssn, mgrno FROM employees;
1230: empno is at position 1, ssn is at position 2, and mgrno is at position 3.
1231: valuep (IN/OUT) - a pointer to a buffer or an array of buffers of the type
1232: specified in the dty parameter. A number of buffers can be specified when
1233: results for more than one row are desired in a single fetch call.
1234: value_sz (IN) - the size of each valuep buffer in bytes. If the data is stored
1235: internally in VARCHAR2 format, the number of characters desired, if different
1236: from the buffer size in bytes, may be additionally specified by the using
1237: OCIAttrSet().
1238: In an NLS conversion environment, a truncation error will be generated if the
1239: number of bytes specified is insufficient to handle the number of characters
1240: desired.
1241: dty (IN) - the data type. Named data type (SQLT_NTY) and REF (SQLT_REF)
1242: are valid only if the environment has been intialized with in object mode.
1243: indp - pointer to an indicator variable or array. For scalar data types,
1244: pointer to sb2 or an array of sb2s. Ignored for named data types. For named
1245: data types, a pointer to a named data type indicator structure or an array of
1246: named data type indicator structures is associated by a subsequent
1247: OCIDefineObject() call.
1248: See the section "Indicator Variables" on page 2-43 for more information about
1249: indicator variables.
1250: rlenp (IN/OUT) - pointer to array of length of data fetched. Each element in
1251: rlenp is the length of the data in the corresponding element in the row after
1252: the fetch.
1253: rcodep (OUT) - pointer to array of column-level return codes
1254: mode (IN) - the valid modes are:
1255: OCI_DEFAULT. This is the default mode.
1256: OCI_DYNAMIC_FETCH. For applications requiring dynamically
1257: allocated data at the time of fetch, this mode must be used. The user may
1258: additionally call OCIDefineDynamic() to set up a callback function that
1259: will be invoked to receive the dynamically allocated buffers and to set
1260: up the memory allocate/free callbacks and the context for the callbacks.
1261: valuep and value_sz are ignored in this mode.
1262: Related Functions
1263: OCIDefineArrayOfStruct(), OCIDefineDynamic(), OCIDefineObject()
1264:
1265:
1266:
1267:
1268: OCIDefineDynamic()
1269: Name
1270: OCI Define Dynamic Fetch Attributes
1271: Purpose
1272: This call is used to set the additional attributes required if the
1273: OCI_DYNAMIC_FETCH mode was selected in OCIDefineByPos().
1274: Syntax
1275: sword OCIDefineDynamic( OCIDefine *defnp,
1276: OCIError *errhp,
1277: dvoid *octxp,
1278: OCICallbackDefine (ocbfp)(
1279: dvoid *octxp,
1280: OCIDefine *defnp,
1281: ub4 iter,
1282: dvoid **bufpp,
1283: ub4 **alenpp,
1284: ub1 *piecep,
1285: dvoid **indpp,
1286: ub2 **rcodep) );
1287: Comments
1288: This call is used to set the additional attributes required if the
1289: OCI_DYNAMIC_FETCH mode has been selected in a call to
1290: OCIDefineByPos().
1291: When the OCI_DYNAMIC_FETCH mode is selected, buffers will be
1292: dynamically allocated for REF, and named data type, values to receive the
1293: data. The pointers to these buffers will be returned.
1294: If OCI_DYNAMIC_FETCH mode was selected, and the call to
1295: OCIDefineDynamic() is skipped, then the application can fetch data piecewise
1296: using OCI calls.
1297: For more information about OCI_DYNAMIC_FETCH mode, see the section
1298: "Runtime Data Allocation and Piecewise Operations" on page 5-16.
1299: Parameters
1300: defnp (IN/OUT) - the handle to a define structure returned by a call to
1301: OCIDefineByPos().
1302: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
1303: diagnostic information in the event of an error.
1304: octxp (IN) - points to a context for the callback function.
1305: ocbfp (IN) - points to a callback function. This is invoked at runtime to get
1306: a pointer to the buffer into which the fetched data or a piece of it will be
1307: retreived. The callback also specifies the indicator, the return code and the
1308: lengths of the data piece and indicator. The callback has the following
1309: parameters:
1310: octxp (IN) - a context pointer passed as an argument to all the callback
1311: functions.
1312: defnp (IN) - the define handle.
1313: iter (IN) - which row of this current fetch.
1314: bufpp (OUT) - returns a pointer to a buffer to store the column value, ie.
1315: *bufp points to some appropriate storage for the column value.
1316: alenpp (OUT) - returns a pointer to the length of the buffer. *alenpp
1317: contains the size of the buffer after return from callback. Gets set to
1318: actual data size after fetch.
1319: piecep (IN/OUT) - returns a piece value, as follows:
1320: The IN value can be OCI_ONE_PIECE, OCI_FIRST_PIECE or
1321: OCI_NEXT_PIECE.
1322: The OUT value can be OCI_ONE_PIECE if the IN value was
1323: OCI_ONE_PIECE.
1324: The OUT value can be OCI_ONE_PIECE or OCI_FIRST_PIECE if
1325: the IN value was OCI_FIRST_PIECE.
1326: The OUT value can only be OCI_NEXT_PIECE or
1327: OCI_LAST_PIECE if the IN value was OCI_NEXT_PIECE.
1328: indpp (IN) - indicator variable pointer
1329: rcodep (IN) - return code variable pointer
1330: Related Functions
1331: OCIAttrGet()
1332: OCIDefineObject()
1333:
1334:
1335:
1336:
1337: OCIDefineObject()
1338: Name
1339: OCI Define Named Data Type attributes
1340: Purpose
1341: Sets up additional attributes necessary for a Named Data Type define.
1342: Syntax
1343: sword OCIDefineObject ( OCIDefine *defnp,
1344: OCIError *errhp,
1345: CONST OCIType *type,
1346: dvoid **pgvpp,
1347: ub4 *pvszsp,
1348: dvoid **indpp,
1349: ub4 *indszp );
1350: Comments
1351: This call sets up additional attributes necessary for a Named Data Type define.An error will be returned if this function is called when the OCI environment
1352: has been initialized in non-Object mode.
1353: This call takes as a paramter a type descriptor object (TDO) of datatype
1354: OCIType for the named data type being defined. The TDO can be retrieved
1355: with a call to OCITypeByName().
1356: See the description of OCIInitialize() on page 13 - 43 for more information
1357: about initializing the OCI process environment.
1358: Parameters
1359: defnp (IN/OUT) - a define handle previously allocated in a call to
1360: OCIDefineByPos().
1361: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
1362: diagnostic information in the event of an error.
1363: type (IN, optional) - points to the Type Descriptor Object (TDO) which
1364: describes the type of the program variable. Only used for program variables
1365: of type SQLT_NTY. This parameter is optional, and may be passed as NULL
1366: if it is not being used.
1367: pgvpp (IN/OUT) - points to a pointer to a program variable buffer. For an
1368: array, pgvpp points to an array of pointers. Memory for the fetched named data
1369: type instance(s) is dynamically allocated in the object cache. At the end of the
1370: fetch when all the values have been received, pgvpp points to the pointer(s) to
1371: these newly allocated named data type instance(s). The application must call
1372: OCIObjectMarkDel() to deallocate the named data type instance(s) when they
1373: are no longer needed.
1374: pvszsp (IN/OUT) - points to the size of the program variable. For an array, it
1375: is an array of ub4s. On return points to the size(s) of unpickled fetched
1376: values.
1377: indpp (IN/OUT) - points to a pointer to the program variable buffer
1378: containing the parallel indicator structure. For an array, points to an array
1379: of pointers. Memory is allocated to store the indicator structures in the
1380: object cache. At the end of the fetch when all values have been received,
1381: indpp points to the pointer(s) to these newly allocated indicator structure(s).
1382: indszp (IN/OUT) - points to the size(s) of the indicator structure program
1383: variable. For an array, it is an array of ub4s. On return points to the size(s)
1384: of the unpickled fetched indicator values.
1385: Related Functions
1386: OCIAttrGet()
1387:
1388:
1389:
1390: OCIDescAlloc()
1391: Name
1392: OCI Get DESCriptor or lob locator
1393: Purpose
1394: Allocates storage to hold certain data types. The descriptors can be used as
1395: bind or define variables.
1396: Syntax
1397: sword OCIDescAlloc ( CONST dvoid *parenth,
1398: dvoid **descpp,
1399: ub4 type,
1400: size_t xtramem_sz,
1401: dvoid **usrmempp);
1402: Comments
1403: Returns a pointer to an allocated and initialized structure, corresponding to
1404: the type specified in type. A non-NULL descriptor or LOB locator is returned
1405: on success. No diagnostics are available on error.
1406: This call returns OCI_SUCCESS if successful, or OCI_INVALID_HANDLE if
1407: an out-of-memory error occurs.
1408: Parameters
1409: parenth (IN) - an environment handle.
1410: descpp (OUT) - returns a descriptor or LOB locator of desired type.
1411: type (IN) - specifies the type of descriptor or LOB locator to be allocated.
1412: The specific types are:
1413: OCI_DTYPE_SNAP - specifies generation of snapshot descriptor of C
1414: type - OCISnapshot
1415: OCI_DTYPE_LOB - specifies generation of a LOB data type locator of C
1416: type - OCILobLocator
1417: OCI_DTYPE_RSET - specifies generation of a descriptor of C type
1418: OCIResult that references a result set (a number of rows as a result of a
1419: query). This descriptor is bound to a bind variable of data type
1420: SQLT_RSET (result set). The descriptor has to be converted into a
1421: statement handle using a function - OCIResultSetToStmt() - which can
1422: then be passed to OCIDefineByPos() and OCIStmtFetch() to retrieve the
1423: rows of the result set.
1424: OCI_DTYPE_ROWID - specifies generation of a ROWID descriptor of C
1425: type OCIRowid.
1426: OCI_DTYPE_COMPLEXOBJECTCOMP - specifies generation of a
1427: complex object retrieval descriptor of C type
1428: OCIComplexObjectComp.
1429: xtramemsz (IN) - specifies an amount of user memory to be allocated for use
1430: by the application.
1431: usrmempp (OUT) - returns a pointer to the user memory of size xtramemsz
1432: allocated by the call for the user.
1433: Related Functions
1434: OCIDescFree()
1435:
1436:
1437:
1438:
1439: OCIDescFree()
1440: Name
1441: OCI Free DESCriptor
1442: Purpose
1443: Deallocates a previously allocated descriptor.
1444: Syntax
1445: sword OCIDescFree ( dvoid *descp,
1446: ub4 type);
1447: Comments
1448: This call frees up storage associated with the descriptor, corresponding to the
1449: type specified in type. Returns OCI_SUCCESS or OCI_INVALID_HANDLE.
1450: All descriptors must be explicitly deallocated. OCI will not deallocate a
1451: descriptor if the environment handle is deallocated.
1452: Parameters
1453: descp (IN) - an allocated descriptor.
1454: type (IN) - specifies the type of storage to be freed. The specific types are:
1455: OCI_DTYPE_SNAP - snapshot descriptor
1456: OCI_DTYPE_LOB - a LOB data type descriptor
1457: OCI_DTYPE_RSET - a descriptor that references a result set (a number
1458: of rows as a result of a query).
1459: OCI_DTYPE_ROWID - a ROWID descriptor
1460: OCI_DTYPE_COMPLEXOBJECTCOMP - a complex object retrieval
1461: descriptor
1462: Related Functions
1463: OCIDescAlloc()
1464:
1465:
1466:
1467: OCIDescribeAny()
1468: Name
1469: OCI DeSCribe Any
1470: Purpose
1471: Describes existing schema objects.
1472: Syntax
1473: sword OCIDescribeAny ( OCISvcCtx *svchp,
1474: OCIError *errhp,
1475: dvoid *objptr,
1476: ub4 objnm_len,
1477: ub1 objptr_typ,
1478: ub1 info_level,
1479: ub1 objtype,
1480: OCIDesc *dschp );
1481: Comments
1482: This is a generic describe call that describes existing schema objects: tables,
1483: views, synonyms, procedures, functions, packages, sequences, and types. As a
1484: result of this call, the describe handle is populated with the object-specific
1485: attributes which can be obtained through an OCIAttrGet() call.
1486: An OCIParamGet() on the describe handle returns a parameter descriptor for a
1487: specified position. Parameter positions begin with 1. Calling OCIAttrGet() on
1488: the parameter descriptor returns the specific attributes of a stored procedure
1489: or function parameter or a table column descriptor as the case may be.
1490: These subsequent calls do not need an extra round trip to the server because
1491: the entire schema object description cached on the client side by
1492: OCIDescribeAny(). Calling OCIAttrGet() on the describe handle can also return
1493: the total number of positions.
1494: See the section "Describing" on page 2-33 for more information about describe
1495: operations.
1496: Parameters
1497: TO BE UPDATED
1498: svchp (IN/OUT) - a service context handle.
1499: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
1500: diagnostic information in the event of an error.
1501: objptr (IN) - the name of the object (a null-terminated string) to be
1502: described. Only procedure or function names are valid when connected to an
1503: Oracle7 Server.
1504: objptr_len (IN) - the length of the string. Must be non-zero.
1505: objptr_typ (IN) - Must be OCI_OTYPE_NAME, OCI_OTYPE_REF, or OCI_OTYPE_PTR.
1506: info_level (IN) - reserved for future extensions. Pass OCI_DEFAULT.
1507: objtype (IN/OUT) - object type.
1508: dschp (IN/OUT) - a describe handle that is populated with describe
1509: information about the object after the call.
1510: Related Functions
1511: OCIAttrGet()
1512:
1513:
1514:
1515: OCIEnvCreate()
1516: Name
1517: OCI ENVironment CREATE
1518: Purpose
1519: This function creates and initializes an environment for the rest of
1520: the OCI functions to work under. This call is a replacement for both
1521: the OCIInitialize and OCIEnvInit calls.
1522: Syntax
1523: sword OCIEnvCreate ( OCIEnv **envhpp,
1524: ub4 mode,
1525: CONST dvoid *ctxp,
1526: CONST dvoid *(*malocfp)
1527: (dvoid *ctxp,
1528: size_t size),
1529: CONST dvoid *(*ralocfp)
1530: (dvoid *ctxp,
1531: dvoid *memptr,
1532: size_t newsize),
1533: CONST void (*mfreefp)
1534: ( dvoid *ctxp,
1535: dvoid *memptr))
1536: size_t xtramemsz,
1537: dvoid **usrmempp );
1538:
1539: Comments
1540: This call creates an environment for all the OCI calls using the modes
1541: specified by the user. This call can be used instead of the two calls
1542: OCIInitialize and OCIEnvInit. This function returns an environment handle
1543: which is then used by the remaining OCI functions. There can be multiple
1544: environments in OCI each with its own environment modes. This function
1545: also performs any process level initialization if required by any mode.
1546: For example if the user wants to initialize an environment as OCI_THREADED,
1547: then all libraries that are used by OCI are also initialized in the
1548: threaded mode.
1549:
1550: This call should be invoked before anny other OCI call and should be used
1551: instead of the OCIInitialize and OCIEnvInit calls. This is the recommended
1552: call, although OCIInitialize and OCIEnvInit calls will still be supported
1553: for backward compatibility.
1554:
1555: envpp (OUT) - a pointer to a handle to the environment.
1556: mode (IN) - specifies initialization of the mode. The valid modes are:
1557: OCI_DEFAULT - default mode.
1558: OCI_THREADED - threaded environment. In this mode, internal data
1559: structures are protected from concurrent accesses by multiple threads.
1560: OCI_OBJECT - will use navigational object interface.
1561: ctxp (IN) - user defined context for the memory call back routines.
1562: malocfp (IN) - user-defined memory allocation function. If mode is
1563: OCI_THREADED, this memory allocation routine must be thread safe.
1564: ctxp - context pointer for the user-defined memory allocation function.
1565: size - size of memory to be allocated by the user-defined memory
1566: allocation function
1567: ralocfp (IN) - user-defined memory re-allocation function. If mode is
1568: OCI_THREADED, this memory allocation routine must be thread safe.
1569: ctxp - context pointer for the user-defined memory reallocation
1570: function.
1571: memp - pointer to memory block
1572: newsize - new size of memory to be allocated
1573: mfreefp (IN) - user-defined memory free function. If mode is
1574: OCI_THREADED, this memory free routine must be thread safe.
1575: ctxp - context pointer for the user-defined memory free function.
1576: memptr - pointer to memory to be freed
1577: xtramemsz (IN) - specifies the amount of user memory to be allocated.
1578: usrmempp (OUT) - returns a pointer to the user memory of size xtramemsz
1579: allocated by the call for the user.
1580:
1581: Example
1582:
1583: Related Functions
1584: OCIInitialize, OCIEnvInit
1585:
1586: OCIEnvInit()
1587: Name
1588: OCI INITialize environment
1589: Purpose
1590: This call initializes the OCI environment handle.
1591: Syntax
1592: sword OCIEnvInit ( OCIEnv **envp,
1593: ub4 mode,
1594: size_t xtramemsz,
1595: dvoid **usrmempp );
1596: Comments
1597: Initializes the OCI environment handle. No changes are done on an initialized
1598: handle. If OCI_ERROR or OCI_SUCCESS_WITH_INFO is returned, the
1599: environment handle can be used to obtain ORACLE specific errors and
1600: diagnostics.
1601: This call is processed locally, without a server round-trip.
1602: Parameters
1603: envpp (OUT) - a pointer to a handle to the environment.
1604: mode (IN) - specifies initialization of an environment mode. The only valid
1605: mode is OCI_DEFAULT for default mode
1606: xtramemsz (IN) - specifies the amount of user memory to be allocated.
1607: usrmempp (OUT) - returns a pointer to the user memory of size xtramemsz
1608: allocated by the call for the user.
1609: Example
1610: See the description of OCISessionBegin() on page 13-84 for an example showing
1611: the use of OCIEnvInit().
1612: Related Functions
1613:
1614:
1615:
1616:
1617: OCIErrorGet()
1618: Name
1619: OCI Get Diagnostic Record
1620: Purpose
1621: Returns an error message in the buffer provided and an ORACLE error.
1622: Syntax
1623: sword OCIErrorGet ( dvoid *hndlp,
1624: ub4 recordno,
1625: OraText *sqlstate,
1626: ub4 *errcodep,
1627: OraText *bufp,
1628: ub4 bufsiz,
1629: ub4 type );
1630: Comments
1631: Returns an error message in the buffer provided and an ORACLE error.
1632: Currently does not support SQL state. This call can be called a multiple
1633: number of times if there are more than one diagnostic record for an error.
1634: The error handle is originally allocated with a call to OCIHandleAlloc().
1635: Parameters
1636: hndlp (IN) - the error handle, in most cases, or the environment handle (for
1637: errors on OCIEnvInit(), OCIHandleAlloc()).
1638: recordno (IN) - indicates the status record from which the application seeks
1639: info. Starts from 1.
1640: sqlstate (OUT) - Not supported in Version 8.0.
1641: errcodep (OUT) - an ORACLE Error is returned.
1642: bufp (OUT) - the error message text is returned.
1643: bufsiz (IN) - the size of the buffer provide to get the error message.
1644: type (IN) - the type of the handle.
1645: Related Functions
1646: OCIHandleAlloc()
1647:
1648: OCIExtractInit
1649: Name
1650: OCI Extract Initialize
1651: Purpose
1652: This function initializes the parameter manager.
1653: Syntax
1654: sword OCIExtractInit(dvoid *hndl, OCIError *err);
1655: Comments
1656: It must be called before calling any other parameter manager routine. The NLS
1657: information is stored inside the parameter manager context and used in
1658: subsequent calls to OCIExtract routines.
1659: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
1660: Parameters
1661: hndl (IN/OUT) - The OCI environment or session handle.
1662: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1663: err and this function returns OCI_ERROR. Diagnostic information
1664: can be obtained by calling OCIErrorGet().
1665: Related Functions
1666: OCIExtractTerm()
1667:
1668: OCIExtractTerm
1669: Name
1670: OCI Extract Terminate
1671: Purpose
1672: This function releases all dynamically allocated storage and may perform
1673: other internal bookkeeping functions.
1674: Syntax
1675: sword OCIExtractTerm(dvoid *hndl, OCIError *err);
1676: Comments
1677: It must be called when the parameter manager is no longer being used.
1678: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
1679: Parameters
1680: hndl (IN/OUT) - The OCI environment or session handle.
1681: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1682: err and this function returns OCI_ERROR. Diagnostic information
1683: can be obtained by calling OCIErrorGet().
1684: Related Functions
1685: OCIExtractInit()
1686:
1687: OCIExtractReset
1688: Name
1689: OCI Extract Reset
1690: Purpose
1691: The memory currently used for parameter storage, key definition storage, and
1692: parameter value lists is freed and the structure is reinitialized.
1693: Syntax
1694: sword OCIExtractReset(dvoid *hndl, OCIError *err);
1695: Comments
1696: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
1697: Parameters
1698: hndl (IN/OUT) - The OCI environment or session handle.
1699: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1700: err and this function returns OCI_ERROR. Diagnostic information
1701: can be obtained by calling OCIErrorGet().
1702: Related Functions
1703:
1704: OCIExtractSetNumKeys
1705: Name
1706: OCI Extract Set Number of Keys
1707: Purpose
1708: Informs the parameter manager of the number of keys that will be registered.
1709: Syntax
1710: sword OCIExtractSetNumKeys(dvoid *hndl, OCIError *err, uword numkeys);
1711: Comments
1712: This routine must be called prior to the first call of OCIExtractSetKey().
1713: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
1714: Parameters
1715: hndl (IN/OUT) - The OCI environment or session handle.
1716: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1717: err and this function returns OCI_ERROR. Diagnostic information
1718: can be obtained by calling OCIErrorGet().
1719: numkeys (IN) - The number of keys that will be registered with
1720: OCIExtractSetKey().
1721: Related Functions
1722: OCIExtractSetKey()
1723:
1724: OCIExtractSetKey
1725: Name
1726: OCI Extract Set Key definition
1727: Purpose
1728: Registers information about a key with the parameter manager.
1729: Syntax
1730: sword OCIExtractSetKey(dvoid *hndl, OCIError *err, CONST OraText *name,
1731: ub1 type, ub4 flag, CONST dvoid *defval,
1732: CONST sb4 *intrange, CONST OraText *CONST *strlist);
1733: Comments
1734: This routine must be called after calling OCIExtractSetKey() and before
1735: calling OCIExtractFromFile() or OCIExtractFromStr().
1736: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
1737: Parameters
1738: hndl (IN/OUT) - The OCI environment or session handle.
1739: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1740: err and this function returns OCI_ERROR. Diagnostic information
1741: can be obtained by calling OCIErrorGet().
1742: name (IN) - The name of the key.
1743: type (IN) - The type of the key (OCI_EXTRACT_TYPE_INTEGER,
1744: OCI_EXTRACT_TYPE_OCINUM, OCI_EXTRACT_TYPE_STRING, or
1745: OCI_EXTRACT_TYPE_BOOLEAN).
1746: flag (IN) - Set to OCI_EXTRACT_MULTIPLE if the key can take multiple values
1747: or 0 otherwise.
1748: defval (IN) - Set to the default value for the key. May be NULL if there is
1749: no default. A string default must be a (text*) type, an
1750: integer default must be an (sb4*) type, and a boolean default
1751: must be a (ub1*) type.
1752: intrange (IN) - Starting and ending values for the allowable range of integer
1753: values. May be NULL if the key is not an integer type or if
1754: all integer values are acceptable.
1755: strlist (IN) - List of all acceptable text strings for the key. May be NULL
1756: if the key is not a string type or if all text values are
1757: acceptable.
1758: Related Functions
1759: OCIExtractSetNumKeys()
1760:
1761: OCIExtractFromFile
1762: Name
1763: OCI Extract parameters From File
1764: Purpose
1765: The keys and their values in the given file are processed.
1766: Syntax
1767: sword OCIExtractFromFile(dvoid *hndl, OCIError *err, ub4 flag,
1768: OraText *filename);
1769: Comments
1770: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
1771: Parameters
1772: hndl (IN/OUT) - The OCI environment or session handle.
1773: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1774: err and this function returns OCI_ERROR. Diagnostic information
1775: can be obtained by calling OCIErrorGet().
1776: flag (IN) - Zero or has one or more of the following bits set:
1777: OCI_EXTRACT_CASE_SENSITIVE, OCI_EXTRACT_UNIQUE_ABBREVS, or
1778: OCI_EXTRACT_APPEND_VALUES.
1779: filename (IN) - Null-terminated filename string.
1780: Related Functions
1781:
1782: OCIExtractFromStr
1783: Name
1784: OCI Extract parameters From String
1785: Purpose
1786: The keys and their values in the given string are processed.
1787: Syntax
1788: sword OCIExtractFromStr(dvoid *hndl, OCIError *err, ub4 flag, OraText *input);
1789: Comments
1790: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
1791: Parameters
1792: hndl (IN/OUT) - The OCI environment or session handle.
1793: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1794: err and this function returns OCI_ERROR. Diagnostic information
1795: can be obtained by calling OCIErrorGet().
1796: flag (IN) - Zero or has one or more of the following bits set:
1797: OCI_EXTRACT_CASE_SENSITIVE, OCI_EXTRACT_UNIQUE_ABBREVS, or
1798: OCI_EXTRACT_APPEND_VALUES.
1799: input (IN) - Null-terminated input string.
1800: Related Functions
1801:
1802: OCIExtractToInt
1803: Name
1804: OCI Extract To Integer
1805: Purpose
1806: Gets the integer value for the specified key.
1807: Syntax
1808: sword OCIExtractToInt(dvoid *hndl, OCIError *err, OraText *keyname, uword valno,
1809: sb4 *retval);
1810: Comments
1811: The valno'th value (starting with 0) is returned.
1812: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR.
1813: OCI_NO_DATA means that there is no valno'th value for this key.
1814: Parameters
1815: hndl (IN) - The OCI environment or session handle.
1816: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1817: err and this function returns OCI_ERROR. Diagnostic information
1818: can be obtained by calling OCIErrorGet().
1819: keyname (IN) - Key name.
1820: valno (IN) - Which value to get for this key.
1821: retval (OUT) - The actual integer value.
1822: Related Functions
1823:
1824: OCIExtractToBool
1825: Name
1826: OCI Extract To Boolean
1827: Purpose
1828: Gets the boolean value for the specified key.
1829: Syntax
1830: sword OCIExtractToBool(dvoid *hndl, OCIError *err, OraText *keyname,
1831: uword valno, ub1 *retval);
1832: Comments
1833: The valno'th value (starting with 0) is returned.
1834: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR.
1835: OCI_NO_DATA means that there is no valno'th value for this key.
1836: Parameters
1837: hndl (IN) - The OCI environment or session handle.
1838: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1839: err and this function returns OCI_ERROR. Diagnostic information
1840: can be obtained by calling OCIErrorGet().
1841: keyname (IN) - Key name.
1842: valno (IN) - Which value to get for this key.
1843: retval (OUT) - The actual boolean value.
1844: Related Functions
1845:
1846: OCIExtractToStr
1847: Name
1848: OCI Extract To String
1849: Purpose
1850: Gets the string value for the specified key.
1851: Syntax
1852: sword OCIExtractToStr(dvoid *hndl, OCIError *err, OraText *keyname, uword valno,
1853: OraText *retval, uword buflen);
1854: Comments
1855: The valno'th value (starting with 0) is returned.
1856: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR.
1857: OCI_NO_DATA means that there is no valno'th value for this key.
1858: Parameters
1859: hndl (IN) - The OCI environment or session handle.
1860: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1861: err and this function returns OCI_ERROR. Diagnostic information
1862: can be obtained by calling OCIErrorGet().
1863: keyname (IN) - Key name.
1864: valno (IN) - Which value to get for this key.
1865: retval (OUT) - The actual null-terminated string value.
1866: buflen (IN) - The length of the buffer for retval.
1867: Related Functions
1868:
1869: Note: The following OCIExtract functions are unavailable in this release
1870:
1871: OCIExtractToOCINum
1872: Name
1873: OCI Extract To OCI Number
1874: Purpose
1875: Gets the OCINumber value for the specified key.
1876: Syntax
1877: sword OCIExtractToOCINum(dvoid *hndl, OCIError *err, OraText *keyname,
1878: uword valno, OCINumber *retval);
1879: Comments
1880: The valno'th value (starting with 0) is returned.
1881: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR.
1882: OCI_NO_DATA means that there is no valno'th value for this key.
1883: Parameters
1884: hndl (IN) - The OCI environment or session handle.
1885: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1886: err and this function returns OCI_ERROR. Diagnostic information
1887: can be obtained by calling OCIErrorGet().
1888: keyname (IN) - Key name.
1889: valno (IN) - Which value to get for this key.
1890: retval (OUT) - The actual OCINumber value.
1891: Related Functions
1892:
1893: OCIExtractToList
1894: Name
1895: OCI Extract To parameter List
1896: Purpose
1897: Generates a list of parameters from the parameter structures that are stored
1898: in memory.
1899: Syntax
1900: sword OCIExtractToList(dvoid *hndl, OCIError *err, uword *numkeys);
1901: Comments
1902: Must be called before OCIExtractValues() is called.
1903: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
1904: Parameters
1905: hndl (IN) - The OCI environment or session handle.
1906: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1907: err and this function returns OCI_ERROR. Diagnostic information
1908: can be obtained by calling OCIErrorGet().
1909: numkeys (OUT) - Number of distinct keys stored in memory.
1910: Related Functions
1911: OCIExtractFromList()
1912:
1913: OCIExtractFromList
1914: Name
1915: OCI Extract From parameter List
1916: Purpose
1917: Generates a list of values for the a parameter in the parameter list.
1918: Syntax
1919: sword OCIExtractFromList(dvoid *hndl, OCIError *err, uword index, OraText *name,
1920: ub1 *type, uword *numvals, dvoid ***values);
1921: Comments
1922: Parameters are specified by an index. OCIExtractToList() must be called prior
1923: to calling this routine to generate the parameter list from the parameter
1924: structures that are stored in memory.
1925: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
1926: Parameters
1927: hndl (IN) - The OCI environment or session handle.
1928: err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
1929: err and this function returns OCI_ERROR. Diagnostic information
1930: can be obtained by calling OCIErrorGet().
1931: name (OUT) - Name of the key for the current parameter.
1932: type (OUT) - Type of the current parameter (OCI_EXTRACT_TYPE_STRING,
1933: OCI_EXTRACT_TYPE_INTEGER, OCI_EXTRACT_TYPE_OCINUM, or
1934: OCI_EXTRACT_TYPE_BOOLEAN)
1935: numvals (OUT) - Number of values for this parameter.
1936: values (OUT) - The values for this parameter.
1937: Related Functions
1938: OCIExtractToList()
1939:
1940:
1941: ************************ OCIFileClose() ***********************************
1942:
1943: Name
1944: OCIFileClose - Oracle Call Interface FILE i/o CLOSE
1945:
1946: Purpose
1947: Close a previously opened file.
1948:
1949: Syntax
1950: sword OCIFileClose ( dvoid *hndl,
1951: OCIError *err,
1952: OCIFileObject *filep )
1953:
1954: Comments
1955: This function will close a previously opened file. If the function succeeds
1956: then OCI_SUCCESS will be returned, else OCI_ERROR.
1957:
1958: Parameters
1959: hndl (IN) - the OCI environment or session handle.
1960: err (OUT) - the OCI error handle
1961: filep (IN) - the OCIFile file object
1962:
1963: Related Functions
1964: OCIFileOpen.
1965:
1966:
1967:
1968: ********************* OCIFileExists() **************************************
1969:
1970: Name
1971: OCIFileExists - Oracle Call Interface FILE i/o EXIST
1972:
1973: Purpose
1974: Check to see if the file exists.
1975:
1976: Syntax
1977: sword OCIFileExists ( dvoid *hndl,
1978: OCIError *err,
1979: OraText *filename,
1980: OraText *path,
1981: ub1 *flag )
1982:
1983: Comments
1984: This function will set the flag to TRUE if the file exists else it will
1985: be set to FALSE.
1986: The function will return OCI_ERROR if any error is encountered, else
1987: it will return OCI_ERROR.
1988:
1989: Parameters
1990: hndl(IN) - OCI environment or session handle
1991: err(OUT) - OCI error handle
1992: filename(IN) - filename
1993: path(IN) - path of the file
1994: flag(OUT) - whether the file exists or not
1995:
1996: Related Functions.
1997: None.
1998:
1999:
2000: **************************** OCIFileFlush() ******************************
2001:
2002:
2003: Name
2004: OCIFileFlush - Oracle Call Interface File i/o FLUSH
2005:
2006: Purpose
2007: Flush the buffers associated with the file to the disk.
2008:
2009: Syntax
2010: sword OCIFileFlush ( dvoid *hndl,
2011: OCIError *err,
2012: OCIFileObject *filep )
2013:
2014: Comments
2015: The function will return OCI_ERROR if any error is encountered, else
2016: it will return OCI_ERROR.
2017:
2018: Parameters
2019: hndl (IN) - the OCI environment or session handle.
2020: err (OUT) - the OCI error handle
2021: filep (IN) - the OCIFile file object
2022:
2023: Related Functions
2024: OCIFileOpen, OCIFileWrite
2025:
2026:
2027:
2028: *************************** OCIFileGetLength() ****************************
2029:
2030: Name
2031: OCIFileGetLength - Oracle Call Interface FILE i/o GET file LENGTH
2032:
2033: Purpose
2034: Get the length of a file.
2035:
2036: Syntax
2037: OCIFileGetLength(dvoid *hndl,
2038: OCIError *err,
2039: OraText *filename,
2040: OraText *path,
2041: ubig_ora *lenp )
2042:
2043: Comments
2044: The length of the file will be returned in lenp.
2045: The function will return OCI_ERROR if any error is encountered, else
2046: it will return OCI_ERROR.
2047:
2048: Parameters
2049: hndl (IN) - the OCI environment or session handle.
2050: err (OUT) - the OCI error handle. If there is an error, it is recorded
2051: in err and this function returns OCI_ERROR. Diagnostic information can be
2052: obtained by calling OCIErrorGet().
2053: filename (IN) - file name.
2054: path (IN) - path of the file.
2055: lenp (OUT) - On output, it is the length of the file in bytes.
2056: is the number of bytes in the file.
2057:
2058: Related Functions
2059: None.
2060:
2061:
2062:
2063: ******************************** OCIFileInit() *****************************
2064:
2065: Name
2066: OCIFileInit - Oracle Call Interface FILE i/o INITialize
2067:
2068: Purpose
2069: Initialize the OCI File I/O package and create the OCIFile context.
2070:
2071: Syntax
2072: sword OCIFileInit ( dvoid *hndl,
2073: OCIError *err)
2074:
2075: Comments
2076: This function should be called before any of the OCIFile functions are
2077: used.
2078: The function will return OCI_ERROR if any error is encountered, else
2079: it will return OCI_ERROR.
2080:
2081: Parameters
2082: hndl(IN) - OCI environment or session handle.
2083: err(OUT) - OCI error structure.
2084:
2085: Related Functions
2086: OCIFileTerm
2087:
2088:
2089:
2090: ********************************* OCIFileOpen() *****************************
2091:
2092: Name
2093: OCIFileOpen - Oracle Call Interface File i/o OPEN
2094:
2095: Purpose
2096: Open a file.
2097:
2098: Syntax
2099: sword OCIFileOpen ( dvoid *hndl,
2100: OCIError *err,
2101: OCIFileObject **filep,
2102: OraText *filename,
2103: OraText *path,
2104: ub4 mode,
2105: ub4 create,
2106: ub4 type )
2107:
2108: Comments
2109: OCIFileOpen returns a handle to the open file in filep if the file is
2110: successfully opened.
2111: If one wants to use the standard file objects (stdin, stdout & stderr)
2112: then OCIFileOpen whould be called with the type filed containing the
2113: appropriate type (see the parameter type). If any of the standard files
2114: are specified then filename, path, mode and create are ignored.
2115: The function will return OCI_ERROR if any error is encountered, else
2116: it will return OCI_ERROR.
2117:
2118: Parameters
2119: hndl (OUT) - the OCI environment or session handle.
2120: err (OUT) - the OCI error handle. If there is an error, it is recorded
2121: in err and this function returns OCI_ERROR. Diagnostic information can be
2122: obtained by calling OCIErrorGet().
2123: filep (OUT) - the file object to be returned.
2124: filename (IN) - file name (NULL terminated string).
2125: path (IN) - path of the file (NULL terminated string).
2126: mode - mode in which to open the file (valid modes are OCI_FILE_READONLY,
2127: OCI_FILE_WRITEONLY, OCI_FILE_READ_WRITE).
2128: create - should the file be created if it does not exist. Valid values
2129: are:
2130: OCI_FILE_TRUNCATE - create a file regardless of whether or not it exists.
2131: If the file already exists overwrite it.
2132: OCI_FILE_EXIST - open it if it exists, else fail.
2133: OCI_FILE_EXCL - fail if the file exists, else create.
2134: OCI_FILE_CREATE - open the file if it exists, and create it if it doesn't.
2135: OCI_FILE_APPEND - set the file pointer to the end of the file prior to
2136: writing(this flag can be OR'ed with OCI_FILE_EXIST or
2137: OCI_FILE_CREATE).
2138: type - file type. Valid values are OCI_FILE_TEXT, OCI_FILE_BIN,
2139: OCI_FILE_STDIN, OCI_FILE_STDOUT and OCI_FILE_STDERR.
2140: If any of the standard files are specified then filename, path, mode
2141: and create are ignored.
2142:
2143: Related Functions.
2144: OCIFileClose
2145:
2146:
2147:
2148: ************************** OCIFileRead() ************************************
2149:
2150: Name
2151: OCIFileRead - Oracle Call Interface FILE i/o READ
2152:
2153: Purpose
2154: Read from a file into a buffer.
2155:
2156: Syntax
2157: sword OCIFileRead ( dvoid *hndl,
2158: OCIError *err,
2159: OCIFileObject *filep,
2160: dvoid *bufp,
2161: ub4 bufl,
2162: ub4 *bytesread )
2163:
2164: Comments
2165: Upto bufl bytes from the file will be read into bufp. The user should
2166: allocate memory for the buffer.
2167: The number of bytes read would be in bytesread.
2168: The function will return OCI_ERROR if any error is encountered, else
2169: it will return OCI_ERROR.
2170:
2171: Parameters
2172: hndl (IN) - the OCI environment or session handle.
2173: err (OUT) - the OCI error handle. If there is an error, it is recorded
2174: in err and this function returns OCI_ERROR. Diagnostic information can be
2175: obtained by calling OCIErrorGet().
2176: filep (IN/OUT) - a File Object that uniquely references the file.
2177: bufp (IN) - the pointer to a buffer into which the data will be read. The
2178: length of the allocated memory is assumed to be bufl.
2179: bufl - the length of the buffer in bytes.
2180: bytesread (OUT) - the number of bytes read.
2181:
2182: Related Functions
2183: OCIFileOpen, OCIFileSeek, OCIFileWrite
2184:
2185:
2186:
2187: ****************************** OCIFileSeek() ******************************
2188:
2189: Name
2190: OCIFileSeek - Oracle Call Interface FILE i/o SEEK
2191:
2192: Purpose
2193: Perfom a seek to a byte position.
2194:
2195: Syntax
2196: sword OCIFileSeek ( dvoid *hndl,
2197: OCIError *err,
2198: OCIFileObject *filep,
2199: uword origin,
2200: ubig_ora offset,
2201: sb1 dir)
2202:
2203: Comments
2204: The function will return OCI_ERROR if any error is encountered, else
2205: it will return OCI_ERROR.
2206:
2207: Parameters
2208: hndl (IN) - the OCI environment or session handle.
2209: err (OUT) - the OCI error handle. If there is an error, it is recorded
2210: in err and this function returns OCI_ERROR. Diagnostic information can be
2211: obtained by calling OCIErrorGet().
2212: filep (IN/OUT) - a file handle that uniquely references the file.
2213: origin - The starting point we want to seek from. NOTE: The starting
2214: point may be OCI_FILE_SEEK_BEGINNING (beginning), OCI_FILE_SEEK_CURRENT
2215: (current position), or OCI_FILE_SEEK_END (end of file).
2216: offset - The number of bytes from the origin we want to start reading from.
2217: dir - The direction we want to go from the origin. NOTE: The direction
2218: can be either OCI_FILE_FORWARD or OCI_FILE_BACKWARD.
2219:
2220: Related Function
2221: OCIFileOpen, OCIFileRead, OCIFileWrite
2222:
2223:
2224:
2225: *************************** OCIFileTerm() **********************************
2226:
2227: Name
2228: OCIFileTerm - Oracle Call Interface FILE i/o TERMinate
2229:
2230: Purpose
2231: Terminate the OCI File I/O package and destroy the OCI File context.
2232:
2233: Syntax
2234: sword OCIFileTerm ( dvoid *hndl,
2235: OCIError *err )
2236:
2237: Comments
2238: After this function has been called no OCIFile function should be used.
2239: The function will return OCI_ERROR if any error is encountered, else
2240: it will return OCI_ERROR.
2241:
2242: Parameters
2243: hndl(IN) - OCI environment or session handle.
2244: err(OUT) - OCI error structure.
2245:
2246: Related Functions
2247: OCIFileInit
2248:
2249:
2250: ********************************* OCIFileWrite() ****************************
2251:
2252: Name
2253: OCIFileWrite - Oracle Call Interface FILE i/o WRITE
2254:
2255: Purpose
2256: Write data from buffer into a file.
2257:
2258: Syntax
2259: sword OCIFileWrite ( dvoid *hndl,
2260: OCIError *err,
2261: OCIFileObject *filep,
2262: dvoid *bufp,
2263: ub4 buflen
2264: ub4 *byteswritten )
2265:
2266: Comments
2267: The number of bytes written will be in *byteswritten.
2268: The function will return OCI_ERROR if any error is encountered, else
2269: it will return OCI_ERROR.
2270:
2271: Parameters
2272: hndl (IN) - the OCI environment or session handle.
2273: err (OUT) - the OCI error handle. If there is an error, it is recorded
2274: in err and this function returns OCI_ERROR. Diagnostic information can be
2275: obtained by calling OCIErrorGet().
2276: filep (IN/OUT) - a file handle that uniquely references the file.
2277: bufp (IN) - the pointer to a buffer from which the data will be written.
2278: The length of the allocated memory is assumed to be the value passed
2279: in bufl.
2280: bufl - the length of the buffer in bytes.
2281: byteswritten (OUT) - the number of bytes written.
2282:
2283: Related Functions
2284: OCIFileOpen, OCIFileSeek, OCIFileRead
2285:
2286:
2287:
2288:
2289:
2290: OCIHandleAlloc()
2291: Name
2292: OCI Get HaNDLe
2293: Purpose
2294: This call returns a pointer to an allocated and initialized handle.
2295: Syntax
2296: sword OCIHandleAlloc ( CONST dvoid *parenth,
2297: dvoid **hndlpp,
2298: ub4 type,
2299: size_t xtramem_sz,
2300: dvoid **usrmempp);
2301: Comments
2302: Returns a pointer to an allocated and initialized structure, corresponding to
2303: the type specified in type. A non-NULL handle is returned on success. Bind
2304: handle and define handles are allocated with respect to a statement handle. All
2305: other handles are allocated with respect to an environment handle which is
2306: passed in as a parent handle.
2307: No diagnostics are available on error. This call returns OCI_SUCCESS if
2308: successful, or OCI_INVALID_HANDLE if an out-of-memory error occurs.
2309: Handles must be allocated using OCIHandleAlloc() before they can be passed
2310: into an OCI call.
2311: Parameters
2312: parenth (IN) - an environment or a statement handle.
2313: hndlpp (OUT) - returns a handle to a handle type.
2314: type (IN) - specifies the type of handle to be allocated. The specific types
2315: are:
2316: OCI_HTYPE_ERROR - specifies generation of an error report handle of
2317: C type OCIError
2318: OCI_HTYPE_SVCCTX - specifies generation of a service context handle
2319: of C type OCISvcCtx
2320: OCI_HTYPE_STMT - specifies generation of a statement (application
2321: request) handle of C type OCIStmt
2322: OCI_HTYPE_BIND - specifies generation of a bind information handle
2323: of C type OCIBind
2324: OCI_HTYPE_DEFINE - specifies generation of a column definition
2325: handle of C type OCIDefine
2326: OCI_HTYPE_DESCRIBE - specifies generation of a select list
2327: description handle of C type OCIDesc
2328: OCI_HTYPE_SERVER - specifies generation of a server context handle
2329: of C type OCIServer
2330: OCI_HTYPE_SESSION - specifies generation of an authentication
2331: context handle of C type OCISession
2332: OCI_HTYPE_TRANS - specifies generation of a transaction context
2333: handle of C type OCITrans
2334: OCI_HTYPE_COMPLEXOBJECT - specifies generation of a complex
2335: object retrieval handle of C type OCIComplexObject
2336: OCI_HTYPE_SECURITY - specifies generation of a security handle of C
2337: type OCISecurity
2338: xtramem_sz (IN) - specifies an amount of user memory to be allocated.
2339: usrmempp (OUT) - returns a pointer to the user memory of size xtramemsz
2340: allocated by the call for the user.
2341: Related Functions
2342: OCIHandleFree()
2343:
2344:
2345:
2346: OCIHandleFree()
2347: Name
2348: OCI Free HaNDLe
2349: Purpose
2350: This call explicitly deallocates a handle.
2351: Syntax
2352: sword OCIHandleFree ( dvoid *hndlp,
2353: ub4 type);
2354: Comments
2355: This call frees up storage associated with a handle, corresponding to the type
2356: specified in the type parameter.
2357: This call returns either OCI_SUCCESS or OCI_INVALID_HANDLE.
2358: All handles must be explicitly deallocated. OCI will not deallocate a child
2359: handle if the parent is deallocated.
2360: Parameters
2361: hndlp (IN) - an opaque pointer to some storage.
2362: type (IN) - specifies the type of storage to be allocated. The specific types are:
2363: OCI_HTYPE_ENV - an environment handle
2364: OCI_HTYPE_ERROR - an error report handle
2365: OCI_HTYPE_SVCCTX - a service context handle
2366: OCI_HTYPE_STMT - a statement (application request) handle
2367: OCI_HTYPE_BIND - a bind information handle
2368: OCI_HTYPE_DEFINE - a column definition handle
2369: OCI_HTYPE_DESCRIBE - a select list description handle
2370: OCI_HTYPE_SERVER - a server handle
2371: OCI_HTYPE_SESSION - a user authentication handle
2372: OCI_HTYPE_TRANS - a transaction handle
2373: OCI_HTYPE_COMPLEXOBJECT - a complex object retrieval handle
2374: OCI_HTYPE_SECURITY - a security handle
2375: Related Functions
2376: OCIHandleAlloc()
2377:
2378:
2379:
2380:
2381: OCIInitialize()
2382: Name
2383: OCI Process Initialize
2384: Purpose
2385: Initializes the OCI process environment.
2386: Syntax
2387: sword OCIInitialize ( ub4 mode,
2388: CONST dvoid *ctxp,
2389: CONST dvoid *(*malocfp)
2390: ( dvoid *ctxp,
2391: size_t size ),
2392: CONST dvoid *(*ralocfp)
2393: ( dvoid *ctxp,
2394: dvoid *memp,
2395: size_t newsize ),
2396: CONST void (*mfreefp)
2397: ( dvoid *ctxp,
2398: dvoid *memptr ));
2399: Comments
2400: This call initializes the OCI process environment.
2401: OCIInitialize() must be invoked before any other OCI call.
2402: Parameters
2403: mode (IN) - specifies initialization of the mode. The valid modes are:
2404: OCI_DEFAULT - default mode.
2405: OCI_THREADED - threaded environment. In this mode, internal data
2406: structures are protected from concurrent accesses by multiple threads.
2407: OCI_OBJECT - will use navigational object interface.
2408: ctxp (IN) - user defined context for the memory call back routines.
2409: malocfp (IN) - user-defined memory allocation function. If mode is
2410: OCI_THREADED, this memory allocation routine must be thread safe.
2411: ctxp - context pointer for the user-defined memory allocation function.
2412: size - size of memory to be allocated by the user-defined memory
2413: allocation function
2414: ralocfp (IN) - user-defined memory re-allocation function. If mode is
2415: OCI_THREADED, this memory allocation routine must be thread safe.
2416: ctxp - context pointer for the user-defined memory reallocation
2417: function.
2418: memp - pointer to memory block
2419: newsize - new size of memory to be allocated
2420: mfreefp (IN) - user-defined memory free function. If mode is
2421: OCI_THREADED, this memory free routine must be thread safe.
2422: ctxp - context pointer for the user-defined memory free function.
2423: memptr - pointer to memory to be freed
2424: Example
2425: See the description of OCIStmtPrepare() on page 13-96 for an example showing
2426: the use of OCIInitialize().
2427: Related Functions
2428:
2429: --------------------------------OCITerminate------------------------------------
2430:
2431: OCITerminate()
2432: Name
2433: OCI process Terminate
2434: Purpose
2435: Do cleanup before process termination
2436: Syntax
2437: sword OCITerminate (ub4 mode);
2438:
2439: Comments
2440: This call performs OCI related clean up before the OCI process terminates.
2441: If the process is running in shared mode then the OCI process is disconnected
2442: from the shared memory subsystem.
2443:
2444: OCITerminate() should be the last OCI call in any process.
2445:
2446: Parameters
2447: mode (IN) - specifies different termination modes.
2448:
2449: OCI_DEFAULT - default mode.
2450:
2451: Example
2452:
2453: Related Functions
2454: OCIInitialize()
2455:
2456: ---------------------- OCIIntervalAssign ---------------------------------
2457: sword OCIIntervalAssign(dvoid *hndl, OCIError *err,
2458: CONST OCIInterval *inpinter, OCIInterval *outinter );
2459:
2460: DESCRIPTION
2461: Copies one interval to another to create a replica
2462: PARAMETERS
2463: hndl (IN) - Session/Env handle.
2464: err (IN/OUT) - error handle. If there is an error, it is
2465: recorded in 'err' and this function returns OCI_ERROR.
2466: The error recorded in 'err' can be retrieved by calling
2467: OCIErrorGet().
2468: (IN) inpinter - Input Interval
2469: (OUT) outinter - Output Interval
2470: RETURNS
2471: OCI_INVALID_HANDLE if 'err' is NULL.
2472: OCI_SUCCESS otherwise
2473:
2474: ---------------------- OCIIntervalCheck ------------------------------------
2475: sword OCIIntervalCheck(dvoid *hndl, OCIError *err, CONST OCIInterval *interval,
2476: ub4 *valid );
2477:
2478: DESCRIPTION
2479: Checks the validity of an interval
2480: PARAMETERS
2481: hndl (IN) - Session/Env handle.
2482: err (IN/OUT) - error handle. If there is an error, it is
2483: recorded in 'err' and this function returns OCI_ERROR.
2484: The error recorded in 'err' can be retrieved by calling
2485: OCIErrorGet().
2486: (IN) interval - Interval to be checked
2487: (OUT) valid - Zero if the interval is valid, else returns an Ored
2488: combination of the following codes.
2489:
2490: Macro name Bit number Error
2491: ---------- ---------- -----
2492: OCI_INTER_INVALID_DAY 0x1 Bad day
2493: OCI_INTER_DAY_BELOW_VALID 0x2 Bad DAy Low/high bit (1=low)
2494: OCI_INTER_INVALID_MONTH 0x4 Bad MOnth
2495: OCI_INTER_MONTH_BELOW_VALID 0x8 Bad MOnth Low/high bit (1=low)
2496: OCI_INTER_INVALID_YEAR 0x10 Bad YeaR
2497: OCI_INTER_YEAR_BELOW_VALID 0x20 Bad YeaR Low/high bit (1=low)
2498: OCI_INTER_INVALID_HOUR 0x40 Bad HouR
2499: OCI_INTER_HOUR_BELOW_VALID 0x80 Bad HouR Low/high bit (1=low)
2500: OCI_INTER_INVALID_MINUTE 0x100 Bad MiNute
2501: OCI_INTER_MINUTE_BELOW_VALID 0x200 Bad MiNute Low/high bit(1=low)
2502: OCI_INTER_INVALID_SECOND 0x400 Bad SeCond
2503: OCI_INTER_SECOND_BELOW_VALID 0x800 bad second Low/high bit(1=low)
2504: OCI_INTER_INVALID_FRACSEC 0x1000 Bad Fractional second
2505: OCI_INTER_FRACSEC_BELOW_VALID 0x2000 Bad fractional second Low/High
2506:
2507:
2508: RETURNS
2509: OCI_SUCCESS if interval is okay
2510: OCI_INVALID_HANDLE if 'err' is NULL.
2511:
2512: ---------------------- OCIIntervalCompare -----------------------------------
2513: sword OCIIntervalCompare(dvoid *hndl, OCIError *err, OCIInterval *inter1,
2514: OCIInterval *inter2, sword *result );
2515:
2516: DESCRIPTION
2517: Compares two intervals, returns 0 if equal, -1 if inter1 < inter2,
2518: 1 if inter1 > inter2
2519: PARAMETERS
2520: hndl (IN) - Session/Env handle.
2521: err (IN/OUT) - error handle. If there is an error, it is
2522: recorded in 'err' and this function returns OCI_ERROR.
2523: The error recorded in 'err' can be retrieved by calling
2524: OCIErrorGet().
2525: inter1 (IN) - Interval to be compared
2526: inter2 (IN) - Interval to be compared
2527: result (OUT) - comparison result, 0 if equal, -1 if inter1 < inter2,
2528: 1 if inter1 > inter2
2529:
2530: RETURNS
2531: OCI_SUCCESS on success
2532: OCI_INVALID_HANDLE if 'err' is NULL.
2533: OCI_ERROR if
2534: the two input datetimes are not mutually comparable.
2535:
2536: ---------------------- OCIIntervalDivide ------------------------------------
2537: sword OCIIntervalDivide(dvoid *hndl, OCIError *err, OCIInterval *dividend,
2538: OCINumber *divisor, OCIInterval *result );
2539:
2540: DESCRIPTION
2541: Divides an interval by an Oracle Number to produce an interval
2542: PARAMETERS
2543: hndl (IN) - Session/Env handle.
2544: err (IN/OUT) - error handle. If there is an error, it is
2545: recorded in 'err' and this function returns OCI_ERROR.
2546: The error recorded in 'err' can be retrieved by calling
2547: OCIErrorGet().
2548: dividend (IN) - Interval to be divided
2549: divisor (IN) - Oracle Number dividing `dividend'
2550: result (OUT) - resulting interval (dividend / divisor)
2551: RETURNS
2552: OCI_SUCCESS on success
2553: OCI_INVALID_HANDLE if 'err' is NULL.
2554:
2555: ---------------------- OCIIntervalFromNumber --------------------
2556: sword OCIIntervalFromNumber(dvoid *hndl, OCIError *err,
2557: OCIInterval *inter, OCINumber *number);
2558: DESCRIPTION
2559: Converts an interval to an Oracle Number
2560: PARAMETERS
2561: hndl (IN) - Session/Env handle.
2562: err (IN/OUT) - error handle. If there is an error, it is
2563: recorded in 'err' and this function returns OCI_ERROR.
2564: The error recorded in 'err' can be retrieved by calling
2565: OCIErrorGet().
2566: (OUT) interval - Interval to be converted
2567: (IN) number - Oracle number result (in years for YEARMONTH interval
2568: and in days for DAYSECOND)
2569: RETURNS
2570: OCI_SUCCESS on success
2571: OCI_INVALID_HANDLE if 'err' is NULL.
2572: OCI_ERROR on error.
2573: NOTES
2574: Fractional portions of the date (for instance, minutes and seconds if
2575: the unit chosen is hours) will be included in the Oracle number produced.
2576: Excess precision will be truncated.
2577:
2578: ---------------------- OCIIntervalFromText ---------------------------------
2579: sword OCIIntervalFromText( dvoid *hndl, OCIError *err, CONST OraText *inpstr,
2580: size_t str_len, OCIInterval *result );
2581:
2582: DESCRIPTION
2583: Given an interval string produce the interval represented by the string.
2584: The type of the interval is the type of the 'result' descriptor.
2585: PARAMETERS
2586:
2587: hndl (IN) - Session/Env handle.
2588: err (IN/OUT) - error handle. If there is an error, it is
2589: recorded in 'err' and this function returns OCI_ERROR.
2590: The error recorded in 'err' can be retrieved by calling
2591: OCIErrorGet().
2592: (IN) inpstr - Input string
2593: (IN) str_len - Length of input string
2594: (OUT) result - Resultant interval
2595: RETURNS
2596: OCI_SUCCESS on success
2597: OCI_INVALID_HANDLE if 'err' is NULL.
2598: OCI_ERROR if
2599: there are too many fields in the literal string
2600: the year is out of range (-4713 to 9999)
2601: if the month is out of range (1 to 12)
2602: if the day of month is out of range (1 to 28...31)
2603: if hour is not in range (0 to 23)
2604: if hour is not in range (0 to 11)
2605: if minute is not in range (0 to 59)
2606: if seconds in minute not in range (0 to 59)
2607: if seconds in day not in range (0 to 86399)
2608: if the interval is invalid
2609:
2610:
2611: ---------------------- OCIIntervalGetDaySecond --------------------
2612:
2613: DESCRIPTION
2614: Gets values of day second interval
2615: PARAMETERS
2616: hndl (IN) - Session/Env handle.
2617: err (IN/OUT) - error handle. If there is an error, it is
2618: recorded in 'err' and this function returns OCI_ERROR.
2619: The error recorded in 'err' can be retrieved by calling
2620: OCIErrorGet().
2621: day (OUT) - number of days
2622: hour (OUT) - number of hours
2623: min (OUT) - number of mins
2624: sec (OUT) - number of secs
2625: fsec (OUT) - number of fractional seconds
2626: result (IN) - resulting interval
2627: RETURNS
2628: OCI_SUCCESS on success
2629: OCI_INVALID_HANDLE if 'err' is NULL.
2630:
2631:
2632: ---------------------- OCIIntervalGetYearMonth --------------------
2633:
2634: DESCRIPTION
2635: Gets year month from an interval
2636: PARAMETERS
2637: hndl (IN) - Session/Env handle.
2638: err (IN/OUT) - error handle. If there is an error, it is
2639: recorded in 'err' and this function returns OCI_ERROR.
2640: The error recorded in 'err' can be retrieved by calling
2641: OCIErrorGet().
2642: year (OUT) - year value
2643: month (OUT) - month value
2644: result (IN) - resulting interval
2645: RETURNS
2646: OCI_SUCCESS on success
2647: OCI_INVALID_HANDLE if 'err' is NULL.
2648:
2649:
2650:
2651: -------------------------- OCIIntervalAdd ------------------------------
2652: sword OCIIntervalAdd(dvoid *hndl, OCIError *err, OCIInterval *addend1,
2653: OCIInterval *addend2, OCIInterval *result );
2654: NAME OCIIntervalAdd - Adds two intervals
2655: PARAMETERS
2656: hndl (IN) - Session/Env handle.
2657: err (IN/OUT) - error handle. If there is an error, it is
2658: recorded in 'err' and this function returns OCI_ERROR.
2659: The error recorded in 'err' can be retrieved by calling
2660: OCIErrorGet().
2661: addend1 (IN) - Interval to be added
2662: addend2 (IN) - Interval to be added
2663: result (OUT) - resulting interval (addend1 + addend2)
2664: DESCRIPTION
2665: Adds two intervals to produce a resulting interval
2666: RETURNS
2667: OCI_SUCCESS on success
2668: OCI_ERROR if:
2669: the two input intervals are not mutually comparable.
2670: the resulting year would go above SB4MAXVAL
2671: the resulting year would go below SB4MINVAL
2672: OCI_INVALID_HANDLE if 'err' is NULL.
2673: NOTES
2674: The two input intervals must be mutually comparable
2675:
2676: ---------------------- OCIIntervalSubtract -------------------------------
2677: sword OCIIntervalSubtract(dvoid *hndl, OCIError *err, OCIInterval *minuend,
2678: OCIInterval *subtrahend, OCIInterval *result );
2679: NAME - OCIIntervalSubtract - subtracts two intervals
2680: PARAMETERS
2681: hndl (IN) - Session/Env handle.
2682: err (IN/OUT) - error handle. If there is an error, it is
2683: recorded in 'err' and this function returns OCI_ERROR.
2684: The error recorded in 'err' can be retrieved by calling
2685: OCIErrorGet().
2686: minuend (IN) - interval to be subtracted from
2687: subtrahend (IN) - interval subtracted from minuend
2688: result (OUT) - resulting interval (minuend - subtrahend)
2689: DESCRIPTION
2690: Subtracts two intervals and stores the result in an interval
2691: RETURNS
2692: OCI_SUCCESS on success
2693: OCI_INVALID_HANDLE if 'err' is NULL.
2694: OCI_ERROR if:
2695: the two input intervals are not mutually comparable.
2696: the resulting leading field would go below SB4MINVAL
2697: the resulting leading field would go above SB4MAXVAL
2698:
2699: ---------------------- OCIIntervalMultiply ---------------------------------
2700: sword OCIIntervalMultiply(dvoid *hndl, OCIError *err, CONST OCIInterval *inter,
2701: OCINumber *nfactor, OCIInterval *result );
2702:
2703: DESCRIPTION
2704: Multiplies an interval by an Oracle Number to produce an interval
2705: PARAMETERS
2706: hndl (IN) - Session/Env handle.
2707: err (IN/OUT) - error handle. If there is an error, it is
2708: recorded in 'err' and this function returns OCI_ERROR.
2709: The error recorded in 'err' can be retrieved by calling
2710: OCIErrorGet().
2711: inter (IN) - Interval to be multiplied
2712: nfactor (IN) - Oracle Number to be multiplied
2713: result (OUT) - resulting interval (ifactor * nfactor)
2714: RETURNS
2715: OCI_SUCCESS on success
2716: OCI_INVALID_HANDLE if 'err' is NULL.
2717: OCI_ERROR if:
2718: the resulting year would go above SB4MAXVAL
2719: the resulting year would go below SB4MINVAL
2720:
2721:
2722: ---------------------- OCIIntervalSetDaySecond --------------------
2723:
2724: DESCRIPTION
2725: Sets day second interval
2726: PARAMETERS
2727: hndl (IN) - Session/Env handle.
2728: err (IN/OUT) - error handle. If there is an error, it is
2729: recorded in 'err' and this function returns OCI_ERROR.
2730: The error recorded in 'err' can be retrieved by calling
2731: OCIErrorGet().
2732: day (IN) - number of days
2733: hour (IN) - number of hours
2734: min (IN) - number of mins
2735: sec (IN) - number of secs
2736: fsec (IN) - number of fractional seconds
2737: result (OUT) - resulting interval
2738: RETURNS
2739: OCI_SUCCESS on success
2740: OCI_INVALID_HANDLE if 'err' is NULL.
2741:
2742:
2743: ---------------------- OCIIntervalSetYearMonth --------------------
2744:
2745: DESCRIPTION
2746: Sets year month interval
2747: PARAMETERS
2748: hndl (IN) - Session/Env handle.
2749: err (IN/OUT) - error handle. If there is an error, it is
2750: recorded in 'err' and this function returns OCI_ERROR.
2751: The error recorded in 'err' can be retrieved by calling
2752: OCIErrorGet().
2753: year (IN) - year value
2754: month (IN) - month value
2755: result (OUT) - resulting interval
2756: RETURNS
2757: OCI_SUCCESS on success
2758: OCI_INVALID_HANDLE if 'err' is NULL.
2759:
2760:
2761: ----------------------- OCIIntervalToNumber ---------------------------------
2762: sword OCIIntervalToNumber(dvoid *hndl, OCIError *err, CONST OCIInterval *inter,
2763: OCINumber *number);
2764:
2765: DESCRIPTION
2766: Converts an interval to an Oracle Number
2767: PARAMETERS
2768: hndl (IN) - Session/Env handle.
2769: err (IN/OUT) - error handle. If there is an error, it is
2770: recorded in 'err' and this function returns OCI_ERROR.
2771: The error recorded in 'err' can be retrieved by calling
2772: OCIErrorGet().
2773: (IN) inter - Interval to be converted
2774: (OUT) number - Oracle number result (in years for YEARMONTH interval
2775: and in days for DAYSECOND)
2776: RETURNS
2777: OCI_INVALID_HANDLE if 'err' is NULL.
2778: OCI_SUCCESS on success
2779: NOTES
2780: Fractional portions of the date (for instance, minutes and seconds if
2781: the unit chosen is hours) will be included in the Oracle number produced.
2782: Excess precision will be truncated.
2783:
2784: ------------------------------- OCIIntervalToText -------------------------
2785: sword OCIIntervalToText( dvoid *hndl, OCIError *err, CONST OCIInterval *inter,
2786: ub1 lfprec, ub1 fsprec, OraText *buffer,
2787: size_t buflen, size_t *resultlen );
2788:
2789: DESCRIPTION
2790: Given an interval, produces a string representing the interval.
2791: PARAMETERS
2792: hndl (IN) - Session/Env handle.
2793: err (IN/OUT) - error handle. If there is an error, it is
2794: recorded in 'err' and this function returns OCI_ERROR.
2795: The error recorded in 'err' can be retrieved by calling
2796: OCIErrorGet().
2797: (IN) inter - Interval to be converted
2798: (IN) lfprec - Leading field precision. Number of digits used to
2799: represent the leading field.
2800: (IN) fsprec - Fractional second precision of the interval. Number of
2801: digits used to represent the fractional seconds.
2802: (OUT) buffer - buffer to hold result
2803: (IN) buflen - length of above buffer
2804: (OUT) resultlen - length of result placed into buffer
2805:
2806: RETURNS
2807: OCI_SUCCESS on success
2808: OCI_INVALID_HANDLE if 'err' is NULL.
2809: OCI_ERROR
2810: if the buffer is not large enough to hold the result
2811: NOTES
2812: The interval literal will be output as `year' or `[year-]month' for
2813: YEAR-MONTH intervals and as `seconds' or `minutes[:seconds]' or
2814: `hours[:minutes[:seconds]]' or `days[ hours[:minutes[:seconds]]]' for
2815: DAY-TIME intervals (where optional fields are surrounded by brackets).
2816:
2817:
2818: OCILdaToSvcCtx()
2819: Name
2820: OCI toggle version 7 Lda_Def to SerVice context handle
2821: Purpose
2822: Converts a V7 Lda_Def to a V8 service context handle.
2823: Syntax
2824: sword OCILdaToSvcCtx ( OCISvcCtx **svchpp,
2825: OCIError *errhp,
2826: Lda_Def *ldap );
2827: Comments
2828: Converts a V7 Lda_Def to a V8 service context handle. The action of this call
2829: can be reversed by passing the resulting service context handle to the
2830: OCISvcCtxToLda() function.
2831: Parameters
2832: svchpp (IN/OUT) - the service context handle.
2833: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
2834: diagnostic information in the event of an error.
2835: ldap (IN/OUT) - the V7 logon data area returned by OCISvcCtxToLda() from
2836: this service context.
2837: Related Functions
2838: OCISvcCtxToLda()
2839:
2840:
2841:
2842:
2843: OCILobAppend()
2844:
2845: Name
2846: OCI Lob APpend
2847:
2848: Purpose
2849: Appends a LOB value at the end of another LOB.
2850:
2851: Syntax
2852: sword OCILobAppend ( OCISvcCtx *svchp,
2853: OCIError *errhp,
2854: OCILobLocator *dst_locp,
2855: OCILobLocator *src_locp );
2856: Comments
2857: Appends a LOB value at the end of LOB. The data is
2858: copied from the source to the destination at the end of the destination. The
2859: source and the destination must already exist. The destination LOB is
2860: extended to accommodate the newly written data.
2861:
2862: It is an error to extend the destination LOB beyond the maximum length
2863: allowed or to try to copy from a NULL LOB.
2864:
2865: Parameters
2866: svchp (IN) - the service context handle.
2867: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
2868: diagnostic information in the event of an error.
2869: dst_locp (IN/OUT) - a locator uniquely referencing the destination LOB.
2870: src_locp (IN/OUT) - a locator uniquely referencing the source LOB.
2871:
2872: Related Functions
2873: OCILobTrim()
2874: OCIErrorGet()
2875: OCILobWrite()
2876: OCILobCopy()
2877:
2878:
2879:
2880: OCILobAssign()
2881:
2882: Name
2883: OCI Lob ASsiGn
2884:
2885: Purpose
2886: Assigns one LOB/FILE locator to another.
2887:
2888: Syntax
2889: sword OCILobAssign ( OCIEnv *envhp,
2890: OCIError *errhp,
2891: CONST OCILobLocator *src_locp,
2892: OCILobLocator **dst_locpp );
2893:
2894: Comments
2895: Assign source locator to destination locator. After the assignment, both
2896: locators refer to the same LOB data. For internal LOBs, the source locator's
2897: LOB data gets copied to the destination locator's LOB data only when the
2898: destination locator gets stored in the table. Therefore, issuing a flush of
2899: the object containing the destination locator will copy the LOB data. For
2900: FILEs only the locator that refers to the OS file is copied to the table. The
2901: OS file is not copied.
2902: Note: The only difference between this and OCILobLocatorAssign is that this
2903: takes an environment handle whereas OCILobLocatorAssign takes an OCI service
2904: handle
2905:
2906: Parameters
2907: envhp (IN/OUT) - OCI environment handle initialized in object mode.
2908: errhp (IN/OUT) - The OCI error handle. If there is an error, it is recorded
2909: in errhp and this function returns OCI_ERROR. Diagnostic information can be
2910: obtained by calling OCIErrorGet().
2911: src_locp (IN) - LOB locator to copy from.
2912: dst_locpp (IN/OUT) - LOB locator to copy to. The caller must allocate space
2913: for the OCILobLocator by calling OCIDescriptorAlloc().
2914:
2915: See also
2916: OCIErrorGet()
2917: OCILobIsEqual()
2918: OCILobLocatorIsInit()
2919: OCILobLocatorAssign()
2920:
2921:
2922: OCILobCharSetForm()
2923:
2924: Name
2925: OCI Lob Get Character Set Form
2926:
2927: Purpose
2928: Gets the LOB locator's character set fpr,, if any.
2929:
2930: Syntax
2931: sword OCILobCharSetForm ( OCIEnv *envhp,
2932: OCIError *errhp,
2933: CONST OCILobLocator *locp,
2934: ub1 *csfrm );
2935:
2936: Comments
2937: Returns the character set form of the input LOB locator in the csfrm output
2938: parameter.
2939:
2940: Parameters
2941: envhp (IN/OUT) - OCI environment handle initialized in object mode.
2942: errhp (IN/OUT) - error handle. The OCI error handle. If there is an error, it
2943: is recorded in err and this function returns OCI_ERROR. Diagnostic
2944: information can be obtained by calling OCIErrorGet().
2945: locp (IN) - LOB locator for which to get the character set form.
2946: csfrm(OUT) - character set form of the input LOB locator. If the input
2947: locator is for a BLOB or a BFILE, csfrm is set to 0 since there is no concept
2948: of a character set for binary LOBs/FILEs. The caller must allocate space for
2949: the csfrm (ub1) and not write into the space.
2950: See also
2951: OCIErrorGet(), OCILobCharSetId(), OCILobLocatorIsInit
2952:
2953:
2954:
2955: OCILobCharSetId()
2956:
2957: Name
2958: OCI Lob get Character Set IDentifier
2959:
2960: Purpose
2961: Gets the LOB locator's character set ID, if any.
2962:
2963: Syntax
2964: sword OCILobCharSetId ( OCIEnv *envhp,
2965: OCIError *errhp,
2966: CONST OCILobLocator *locp,
2967: ub2 *csid );
2968:
2969: Comments
2970: Returns the character set ID of the input LOB locator in the cid output
2971: parameter.
2972:
2973: Parameters
2974: envhp (IN/OUT) - OCI environment handle initialized in object mode.
2975: errhp (IN/OUT) - error handle. The OCI error handle. If there is an error, it
2976: is recorded in err and this function returns OCI_ERROR. Diagnostic
2977: information can be obtained by calling OCIErrorGet().
2978: locp (IN) - LOB locator for which to get the character set ID.
2979: csid (OUT) - character set ID of the input LOB locator. If the input locator
2980: is for a BLOB or a BFILE, csid is set to 0 since there is no concept of a
2981: character set for binary LOBs/FILEs. The caller must allocate space for the
2982: character set id of type ub2 and not write into the space.
2983:
2984: See also
2985: OCIErrorGet(), OCILobCharSetForm(), OCILobLocatorIsInit()
2986:
2987:
2988:
2989: OCILobCopy()
2990:
2991: Name
2992: OCI Lob Copy
2993:
2994: Purpose
2995: Copies a portion of a LOB value into another LOB value.
2996:
2997: Syntax
2998: sword OCILobCopy ( OCISvcCtx *svchp,
2999: OCIError *errhp,
3000: OCILobLocator *dst_locp,
3001: OCILobLocator *src_locp,
3002: ub4 amount,
3003: ub4 dst_offset,
3004: ub4 src_offset );
3005:
3006: Comments
3007: Copies a portion of a LOB value into another LOB as specified. The data
3008: is copied from the source to the destination. The source (src_locp) and the
3009: destination (dlopb) LOBs must already exist.
3010: If the data already exists at the destination's start position, it is
3011: overwritten with the source data. If the destination's start position is
3012: beyond the end of the current data, a hole is created from the end of the data
3013: to the beginning of the newly written data from the source. The destination
3014: LOB is extended to accommodate the newly written data if it extends
3015: beyond the current length of the destination LOB.
3016: It is an error to extend the destination LOB beyond the maximum length
3017: allowed or to try to copy from a NULL LOB.
3018: Parameters
3019: svchp (IN) - the service context handle.
3020: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3021: diagnostic information in the event of an error.
3022: dst_locp (IN/OUT) - a locator uniquely referencing the destination LOB.
3023: src_locp (IN/OUT) - a locator uniquely referencing the source LOB.
3024: amount (IN) - the number of character or bytes, as appropriate, to be copied.
3025: dst_offset (IN) - this is the absolute offset for the destination LOB.
3026: For character LOBs it is the number of characters from the beginning of the
3027: LOB at which to begin writing. For binary LOBs it is the number of bytes from
3028: the beginning of the lob from which to begin reading. The offset starts at 1.
3029: src_offset (IN) - this is the absolute offset for the source LOB.
3030: For character LOBs it is the number of characters from the beginning of the
3031: LOB, for binary LOBs it is the number of bytes. Starts at 1.
3032:
3033: See Also
3034: OCIErrorGet(), OCILobAppend(), OCILobWrite(), OCILobTrim()
3035:
3036: OCILobCreateTemporary()
3037:
3038: Name
3039: OCI Lob Create Temporary
3040:
3041: Purpose
3042: Create a Temporary Lob
3043:
3044: Syntax
3045: sword OCILobCreateTemporary(OCISvcCtx *svchp,
3046: OCIError *errhp,
3047: OCILobLocator *locp,
3048: ub2 csid,
3049: ub1 csfrm,
3050: ub1 lobtype,
3051: boolean cache,
3052: OCIDuration duration);
3053:
3054:
3055: Comments
3056: svchp (IN) - the service context handle.
3057: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3058: diagnostic information in the event of an error.
3059: locp (IN/OUT) - a locator which points to the temporary Lob
3060: csid (IN) - the character set id
3061: csfrm(IN) - the character set form
3062: lobtype (IN) - the lob type - one of the three constants OCI_TEMP_BLOB,
3063: OCI_TEMP_CLOB and OCI_TEMP_NCLOB
3064: cache(IN)- TRUE if the temporary LOB goes through the cache; FALSE, if not.
3065: duration(IN)- duration of the temporary LOB; Can be a valid duration id or one
3066: of the values: OCI_DURATION_SESSION, OCI_DURATION_CALL
3067: Note: OCI_DURATION_TRANSACTION is NOT supported in 8.1
3068: Related functions
3069: OCILobFreeTemporary()
3070: OCILobIsTemporary()
3071:
3072: OCILobDisableBuffering()
3073:
3074: Name
3075: OCI Lob Disable Buffering
3076:
3077: Purpose
3078: Disable lob buffering for the input locator.
3079:
3080:
3081: Syntax
3082: sword OCILobDisableBuffering ( OCISvcCtx *svchp,
3083: OCIError *errhp,
3084: OCILobLocator *locp);
3085:
3086: Comments
3087:
3088: Disable lob buffering for the input locator. The next time data is
3089: read/written from/to the lob through the input locator, the lob
3090: buffering subsystem is *not* used. Note that this call does *not*
3091: implicitly flush the changes made in the buffering subsystem. The
3092: user must explicitly call OCILobFlushBuffer() to do this.
3093:
3094: Parameters
3095: svchp (IN) - the service context handle.
3096: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3097: diagnostic information in the event of an error.
3098: locp (IN/OUT) - a locator uniquely referencing the LOB.
3099:
3100: Related Functions
3101: OCILobEnableBuffering()
3102: OCIErrorGet()
3103: OCILobFlushBuffer()
3104:
3105:
3106:
3107:
3108: OCILobEnableBuffering()
3109:
3110: Name
3111: OCI Lob Enable Buffering
3112:
3113: Purpose
3114: Enable lob buffering for the input locator.
3115:
3116:
3117: Syntax
3118: sword OCILobEnableBuffering ( OCISvcCtx *svchp,
3119: OCIError *errhp,
3120: OCILobLocator *locp);
3121:
3122: Comments
3123:
3124: Enable lob buffering for the input locator. The next time data is
3125: read/written from/to the lob through the input locator, the lob
3126: buffering subsystem is used.
3127:
3128: Once lob buffering is enabled for a locator, if that locator is passed to
3129: one of the following routines, an error is returned:
3130: OCILobCopy, OCILobAppend, OCILobErase, OCILobGetLength, OCILobTrim
3131:
3132: Parameters
3133: svchp (IN) - the service context handle.
3134: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3135: diagnostic information in the event of an error.
3136: locp (IN/OUT) - a locator uniquely referencing the LOB.
3137:
3138: Related Functions
3139: OCILobDisableBuffering()
3140: OCIErrorGet()
3141: OCILobWrite()
3142: OCILobRead()
3143: OCILobFlushBuffer()
3144:
3145:
3146:
3147:
3148: OCILobErase()
3149:
3150: Name
3151: OCI Lob ERase
3152:
3153: Purpose
3154: Erases a specified portion of the LOB data starting at a specified offset.
3155:
3156: Syntax
3157: sword OCILobErase ( OCISvcCtx *svchp,
3158: OCIError *errhp,
3159: OCILobLocator *locp,
3160: ub4 *amount,
3161: ub4 offset );
3162:
3163: Comments
3164: Erases a specified portion of the LOB data starting at a specified offset.
3165: The actual number of characters/bytes erased is returned. The actual number
3166: of characters/bytes and the requested number of characters/bytes will differ
3167: if the end of the LOB data is reached before erasing the requested number of
3168: characters/bytes.
3169: If a section of data from the middle of the LOB data is erased, a hole is
3170: created. When data from that hole is read, 0's are returned. If the LOB is
3171: NULL, this routine will indicate that 0 characters/bytes were erased.
3172:
3173: Parameters
3174: svchp (IN) - the service context handle.
3175: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3176: diagnostic information in the event of an error.
3177: locp (IN/OUT) - the LOB for which to erase a section of data.
3178: amount (IN/OUT) - On IN, the number of characters/bytes to erase. On OUT,
3179: the actual number of characters/bytes erased.
3180: offset (IN) - absolute offset from the beginning of the LOB data from which
3181: to start erasing data. Starts at 1.
3182:
3183: See Also
3184: OCIErrorGet(), OCILobRead(), OCILobWrite()
3185:
3186: OCILobOpen()
3187:
3188: Name
3189: OCI Lob Open
3190:
3191: Purpose
3192: Opens an internal or external Lob.
3193:
3194: Syntax
3195: sword OCILobOpen( OCISvcCtx *svchp,
3196: OCIError *errhp,
3197: OCILobLocator *locp,
3198: ub1 mode );
3199:
3200: Comments
3201: It is an error if the same lob is opened more than once in
3202: the same transaction. Lobs are opened implicitly if they are
3203: not opened before using them. A LOB has to be closed before
3204: the transaction commits else the transaction is rolled back.
3205: Open locators are closed if the transaction aborts. Multiple
3206: users can open the same lob on different locators.
3207: Parameters
3208: svchp (IN) - the service context handle.
3209: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3210: diagnostic information in the event of an error.
3211: locp (IN/OUT) - locator points to the LOB to be opened
3212: mode (IN) - mode in which to open the lob. The valid modes are
3213: read-only - OCI_FILE_READONLY, read-write - OCI_FILE_READWRITE
3214:
3215: OCILobClose()
3216:
3217: Name
3218: OCI Lob Close
3219:
3220: Purpose
3221: Closes an open internal or external Lob.
3222:
3223: Syntax
3224: sword OCILobClose( OCISvcCtx *svchp,
3225: OCIError *errhp,
3226: OCILobLocator *locp );
3227:
3228:
3229: Comments
3230: It is an error if the lob is not open at this time. All LOBs
3231: that have been opened in a transaction have to be closed
3232: before the transaction commits, else the transaction gets
3233: rolled back.
3234:
3235: Parameters
3236: svchp (IN) - the service context handle.
3237: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3238: diagnostic information in the event of an error.
3239: locp (IN) - A locator that was opened using OCILobOpen()
3240:
3241:
3242: OCILobFileClose()
3243:
3244: Name
3245: OCI Lob File CLoSe
3246:
3247: Purpose
3248: Closes a previously opened FILE.
3249:
3250: Syntax
3251: sword OCILobFileClose ( OCISvcCtx *svchp,
3252: OCIError *errhp,
3253: OCILobLocator *filep );
3254:
3255: Comments
3256: Closes a previously opened FILE. It is an error if this function is called for
3257: an internal LOB. No error is returned if the FILE exists but is not opened.
3258: Parameters
3259: svchp (IN) - the service context handle.
3260: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3261: diagnostic information in the event of an error.
3262: filep (IN/OUT) - a pointer to a FILE locator to be closed.
3263:
3264: See Also
3265: OCIErrorGet(), OCILobFileOpen(), OCILobFileCloseAll(), OCILobFileIsOpen(),
3266: OCILobFileExists(), CREATE DIRECTORY DDL
3267:
3268:
3269:
3270:
3271: OCILobFileCloseAll()
3272:
3273: Name
3274: OCI LOB FILE Close All
3275:
3276: Purpose
3277: Closes all open FILEs on a given service context.
3278:
3279: Syntax
3280: sword OCILobFileCLoseAll ( OCISvcCtx *svchp,
3281: OCIError *errhp );
3282:
3283: Comments
3284: Closes all open FILEs on a given service context.
3285:
3286: Parameters
3287: svchp (IN) - the service context handle.
3288: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3289: diagnostic information in the event of an error.
3290:
3291: See also
3292: OCILobFileClose(),
3293: OCIErrorGet(), OCILobFileOpen(), OCILobFileIsOpen(),
3294: OCILobFileExists(), CREATE DIRECTORY DDL
3295:
3296:
3297:
3298:
3299: OCILobFileExists()
3300:
3301: Name
3302: OCI LOB FILE exists
3303:
3304: Purpose
3305: Tests to see if the FILE exists on the server
3306:
3307: Syntax
3308: sword OCILobFileExists ( OCISvcCtx *svchp,
3309: OCIError *errhp,
3310: OCILobLocator *filep,
3311: boolean *flag );
3312:
3313: Comments
3314: Checks to see if a FILE exists for on the server.
3315:
3316: Parameters
3317: svchp (IN) - the OCI service context handle.
3318: errhp (IN/OUT) - error handle. The OCI error handle. If there is an error,
3319: it is recorded in err and this function returns OCI_ERROR. Diagnostic
3320: information can be obtained by calling OCIErrorGet().
3321: filep (IN) - pointer to the FILE locator that refers to the file.
3322: flag (OUT) - returns TRUE if the FILE exists; FALSE if it does not.
3323:
3324: See also
3325: OCIErrorGet, CREATE DIRECTORY (DDL)
3326:
3327:
3328:
3329:
3330: OCILobFileGetName()
3331:
3332: Name
3333: OCI LOB FILE Get file Name
3334:
3335: Purpose
3336: Gets the FILE locator's directory alias and file name.
3337:
3338: Syntax
3339: sword OCILobFileGetName ( OCIEnv *envhp,
3340: OCIError *errhp,
3341: CONST OCILobLocator *filep,
3342: OraText *dir_alias,
3343: ub2 *d_length,
3344: OraText *filename,
3345: ub2 *f_length );
3346:
3347: Comments
3348: Returns the directory alias and file name associated with this file locator.
3349:
3350: Parameters
3351: envhp (IN/OUT) - OCI environment handle initialized in object mode.
3352: errhp (IN/OUT) -The OCI error handle. If there is an error, it is recorded in
3353: errhp and this function returns OCI_ERROR. Diagnostic information can be
3354: obtained by calling OCIErrorGet().
3355: filep (IN) - FILE locator for which to get the directory alias and file name.
3356: dir_alias (OUT) - buffer into which the directory alias name is placed. The
3357: caller must allocate enough space for the directory alias name and must not
3358: write into the space.
3359: d_length (IN/OUT)
3360: - IN: length of the input dir_alias string;
3361: - OUT: length of the returned dir_alias string.
3362: filename (OUT) - buffer into which the file name is placed. The caller must
3363: allocate enough space for the file name and must not write into the space.
3364: f_length (IN/OUT)
3365: - IN: length of the input filename string;
3366: - OUT: lenght of the returned filename string.
3367:
3368: See also
3369: OCILobFileSetName(), OCIErrorGet()
3370:
3371:
3372:
3373:
3374: OCILobFileIsOpen()
3375:
3376: Name
3377: OCI LOB FILE Is Open?
3378:
3379: Purpose
3380: Tests to see if the FILE is open
3381:
3382: Syntax
3383: sword OCILobFileIsOpen ( OCISvcCtx *svchp,
3384: OCIError *errhp,
3385: OCILobLocator *filep,
3386: boolean *flag );
3387:
3388: Comments
3389: Checks to see if the FILE on the server is open for a given LobLocator.
3390:
3391: Parameters
3392: svchp (IN) - the OCI service context handle.
3393: errhp (IN/OUT) - error handle. The OCI error handle. If there is an error, it
3394: is recorded in err and this function returns OCI_ERROR. Diagnostic
3395: information can be obtained by calling OCIErrorGet().
3396: filep (IN) - pointer to the FILE locator being examined. If the input file
3397: locator was never passed to OCILobFileOpen(), the file is considered not to
3398: be opened by this locator. However, a different locator may have opened the
3399: file. More than one file opens can be performed on the same file using
3400: different locators.
3401: flag (OUT) - returns TRUE if the FILE is opened using this locator; FALSE if
3402: it is not.
3403:
3404: See also
3405: OCIErrorGet, OCILobFileOpen, OCILobFileClose, OCILobFileCloseAll, CREATE
3406: DIRECTORY SQL command
3407:
3408:
3409: OCILobFileOpen()
3410:
3411: Name
3412: OCI LOB FILE open
3413:
3414: Purpose
3415: Opens a FILE for read-only access
3416:
3417: Syntax
3418: sword OCILobFileOpen ( OCISvcCtx *svchp,
3419: OCIError *errhp,
3420: OCILobLocator *filep,
3421: ub1 mode );
3422:
3423: Comments
3424: Opens a FILE. The FILE can be opened for read-only access only. FILEs may not
3425: be written to throough ORACLE.
3426:
3427: Parameters
3428: svchp (IN) - the service context handle.
3429: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3430: diagnostic information in the event of an error.
3431: filep (IN/OUT) - the FILE to open. Error if the locator does not refer to a
3432: FILE.
3433: mode (IN) - mode in which to open the file. The only valid mode is
3434: read-only - OCI_FILE_READONLY.
3435:
3436: See Also
3437: OCILobFileClose, OCIErrorGet, OCILobFileCloseAll, OCILobFileIsOpen,
3438: OCILobFileSetName, CREATE DIRECTORY
3439:
3440:
3441:
3442:
3443: OCILobFileSetName()
3444:
3445: Name
3446: OCI Lob File Set NaMe
3447:
3448: Purpose
3449: Sets directory alias and file name in the FILE locator.
3450:
3451: Syntax
3452: sword OCILobFileSetName ( OCIEnv *envhp,
3453: OCIError *errhp,
3454: OCILobLocator **filepp,
3455: OraText *dir_alias,
3456: ub2 d_length,
3457: OraText *filename,
3458: ub2 f_length );
3459: Comments
3460: Sets the directory alias and file name in the LOB file locator.
3461: Parameters
3462: envhp (IN/OUT) - OCI environment handle initialized in object mode.
3463: errhp (IN/OUT) - The OCI error handle. If there is an error, it is recorded
3464: in errhp and this function returns OCI_ERROR. Diagnostic information can be
3465: obtained by calling OCIErrorGet().
3466: filepp (IN/OUT) - FILE locator for which to set the directory alias name.
3467: The caller must have already allocated space for the locator by calling
3468: OCIDescriptorAlloc().
3469: dir_alias (IN) - buffer that contains the directory alias name to set in the
3470: locator.
3471: d_length (IN) - length of the input dir_alias parameter.
3472: filename (IN) - buffer that contains the file name is placed.
3473: f_length (IN) - length of the input filename parameter.
3474: See also
3475: OCILobFileGetName, OCIErrorGet, CREATE DIRECTORY
3476:
3477:
3478:
3479:
3480: OCILobFlushBuffer()
3481:
3482: Name
3483: OCI Lob Flush all Buffers for this lob.
3484:
3485: Purpose
3486: Flush/write all buffers for this lob to the server.
3487:
3488:
3489: Syntax
3490: sword OCILobFlushBuffer ( OCISvcCtx *svchp,
3491: OCIError *errhp,
3492: OCILobLocator *locp,
3493: ub4 flag);
3494:
3495: Comments
3496:
3497: Flushes to the server, changes made to the buffering subsystem that
3498: are associated with the lob referenced by the input locator. This
3499: routine will actually write the data in the buffer to the lob in
3500: the database. Lob buffering must have already been enabled for the
3501: input lob locator.
3502:
3503: This routine, by default, does not free the buffer resources for
3504: reallocation to another buffered LOB operation. However, if you
3505: want to free the buffer explicitly, you can set the flag parameter
3506: to OCI_LOB_BUFFER_FREE.
3507:
3508: Parameters
3509: svchp (IN/OUT) - the service context handle.
3510: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3511: diagnostic information in the event of an error.
3512: locp (IN/OUT) - a locator uniquely referencing the LOB.
3513: flag (IN) - to indicate if the buffer resources need to be freed
3514: after a flush. Default value is OCI_LOB_BUFFER_NOFREE.
3515: Set it to OCI_LOB_BUFFER_FREE if you want the buffer
3516: resources to be freed.
3517: Related Functions
3518: OCILobEnableBuffering()
3519: OCILobDisableBuffering()
3520: OCIErrorGet()
3521: OCILobWrite()
3522: OCILobRead()
3523:
3524:
3525: OCILobFreeTemporary()
3526:
3527: Name
3528: OCI Lob Free Temporary
3529:
3530: Purpose
3531: Free a temporary LOB
3532:
3533: Syntax
3534: sword OCILobFreeTemporary(OCISvcCtx *svchp,
3535: OCIError *errhp,
3536: OCILobLocator *locp);
3537:
3538: Comments
3539: Frees the contents of the temporary Lob this locator is pointing to. Note
3540: that the locator itself is not freed until a OCIDescriptorFree is done.
3541:
3542: Parameters
3543: svchp (IN/OUT) - the service context handle.
3544: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3545: diagnostic information in the event of an error.
3546: locp (IN/OUT) - a locator uniquely referencing the LOB
3547:
3548: Related functions
3549: OCILobCreateTemporary()
3550: OCILobIsTemporary()
3551:
3552:
3553: Name
3554: OCI Lob/File Get Chunk Size
3555:
3556: Purpose
3557: When creating the table, the user can specify the chunking factor, which can
3558: be a multiple of Oracle blocks. This corresponds to the chunk size used by the
3559: LOB data layer when accessing/modifying the LOB value. Part of the chunk is
3560: used to store system-related information and the rest stores the LOB value.
3561: This function returns the amount of space used in the LOB chunk to store
3562: the LOB value.
3563:
3564: Syntax
3565: sword OCILobGetChunkSize ( OCISvcCtx *svchp,
3566: OCIError *errhp,
3567: OCILobLocator *locp,
3568: ub4 *chunksizep );
3569:
3570: Comments
3571: Performance will be improved if the user issues read/write
3572: requests using a multiple of this chunk size. For writes, there is an added
3573: benefit since LOB chunks are versioned and, if all writes are done on chunk
3574: basis, no extra/excess versioning is done nor duplicated. Users could batch
3575: up the write until they have enough for a chunk instead of issuing several
3576: write calls for the same chunk.
3577:
3578: Parameters
3579: svchp (IN) - the service context handle.
3580: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3581: diagnostic information in the event of an error.
3582: locp (IN/OUT) - a LOB locator that uniquely references the LOB. For internal
3583: LOBs, this locator must be a locator that was obtained from the server
3584: specified by svchp. For FILEs, this locator can be initialized by a Select or
3585: OCILobFileSetName.
3586: chunksizep (OUT) - On output, it is the length of the LOB if not NULL - for
3587: character LOBs it is the number of characters, for binary LOBs it is the
3588: number of bytes in the LOB.
3589:
3590: Related Functions
3591:
3592: OCILobGetLength()
3593:
3594: Name
3595: OCI Lob/File Length
3596:
3597: Purpose
3598: Gets the length of a LOB/FILE.
3599:
3600: Syntax
3601: sword OCILobGetLength ( OCISvcCtx *svchp,
3602: OCIError *errhp,
3603: OCILobLocator *locp,
3604: ub4 *lenp );
3605:
3606: Comments
3607: Gets the length of a LOB/FILE. If the LOB/FILE is NULL, the length is
3608: undefined.
3609:
3610: Parameters
3611: svchp (IN) - the service context handle.
3612: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3613: diagnostic information in the event of an error.
3614: locp (IN/OUT) - a LOB locator that uniquely references the LOB. For internal
3615: LOBs, this locator must be a locator that was obtained from the server
3616: specified by svchp. For FILEs, this locator can be initialized by a Select or
3617: OCILobFileSetName.
3618: lenp (OUT) - On output, it is the length of the LOB if not NULL - for
3619: character LOBs it is the number of characters, for binary LOBs it is the
3620: number of bytes in the LOB.
3621:
3622: Related Functions
3623: OCIErrorGet, OCIFileSetName
3624:
3625:
3626:
3627: OCILobIsEqual()
3628:
3629: Name
3630:
3631: OCI Lob Is Equal
3632:
3633: Purpose
3634: Compares two LOB locators for equality.
3635:
3636: Syntax
3637: sword OCILobIsEqual ( OCIEnv *envhp,
3638: CONST OCILobLocator *x,
3639: CONST OCILobLocator *y,
3640: boolean *is_equal );
3641:
3642: Comments
3643: Compares the given LOB locators for equality. Two LOB locators are equal if
3644: and only if they both refer to the same LOB data.
3645: Two NULL locators are considered not equal by this function.
3646: Parameters
3647: envhp (IN) - the OCI environment handle.
3648: x (IN) - LOB locator to compare.
3649: y (IN) - LOB locator to compare.
3650: is_equal (OUT) - TRUE, if the LOB locators are equal; FALSE if they are not.
3651:
3652: See also
3653: OCILobAssign, OCILobLocatorIsInit
3654: OCILobLocatorAssign,
3655: OCILobIsOpen()
3656:
3657: Name
3658:
3659: OCI Lob Is Open
3660: sword OCILobIsOpen(svchp, errhp, locp, flag)
3661: OCISvcCtx *svchp;
3662: OCIError *errhp;
3663: OCILobLocator *locp;
3664: boolean *flag;
3665:
3666: Comments
3667: Checks if the LOB locator was opened before. flag is set to TRUE
3668: if opened; FALSE otherwise
3669:
3670:
3671: Parameters
3672: svchp (IN) - the service context handle.
3673: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3674: diagnostic information in the event of an error.
3675: locp (IN) - the locator to test for temporary LOB
3676: flag(OUT) - TRUE, if the LOB locator points to is open
3677: FALSE, if not.
3678:
3679: OCILobIsTemporary()
3680:
3681: Name
3682:
3683: OCI Lob Is Temporary
3684:
3685: Purpose
3686: Tests if this locator points to a temporary LOB
3687:
3688: Syntax
3689: sword OCILobIsTemporary(OCIEnv *envhp,
3690: OCIError *errhp,
3691: OCILobLocator *locp,
3692: boolean *is_temporary);
3693:
3694: Comments
3695: Tests the locator to determine if it points to a temporary LOB.
3696: If so, is_temporary is set to TRUE. If not, is_temporary is set
3697: to FALSE.
3698:
3699: Parameters
3700: svchp (IN) - the service context handle.
3701: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3702: diagnostic information in the event of an error.
3703: locp (IN) - the locator to test for temporary LOB
3704: is_temporary(OUT) - TRUE, if the LOB locator points to a temporary LOB;
3705: FALSE, if not.
3706:
3707: See Also
3708: OCILobCreateTemporary, OCILobFreeTemporary
3709:
3710:
3711: OCILobLoadFromFile()
3712:
3713: Name
3714: OCI Lob Load From File
3715:
3716: Purpose
3717: Load/copy all or a portion of the file into an internal LOB.
3718:
3719: Syntax
3720: sword OCILobLoadFromFile ( OCISvcCtx *svchp,
3721: OCIError *errhp,
3722: OCILobLocator *dst_locp,
3723: OCILobLocator *src_filep,
3724: ub4 amount,
3725: ub4 dst_offset,
3726: ub4 src_offset );
3727:
3728: Comments
3729: Loads/copies a portion or all of a file value into an internal LOB as
3730: specified. The data is copied from the source file to the destination
3731: internal LOB (BLOB/CLOB). No character set conversions are performed
3732: when copying the bfile data to a clob/nclob. The bfile data must already
3733: be in the same character set as the clob/nclob in the database. No
3734: error checking is performed to verify this.
3735: The source (src_filep) and the destination (dst_locp) LOBs must already exist.
3736: If the data already exists at the destination's start position, it is
3737: overwritten with the source data. If the destination's start position is
3738: beyond the end of the current data, a hole is created from the end of the data
3739: to the beginning of the newly written data from the source. The destination
3740: LOB is extended to accommodate the newly written data if it extends
3741: beyond the current length of the destination LOB.
3742: It is an error to extend the destination LOB beyond the maximum length
3743: allowed or to try to copy from a NULL LOB.
3744: Parameters
3745: svchp (IN) - the service context handle.
3746: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3747: diagnostic information in the event of an error.
3748: dst_locp (IN/OUT) - a locator uniquely referencing the destination internal
3749: LOB which may be of type blob, clob, or nclob.
3750: src_filep (IN/OUT) - a locator uniquely referencing the source BFILE.
3751: amount (IN) - the number of bytes to be copied.
3752: dst_offset (IN) - this is the absolute offset for the destination LOB.
3753: For character LOBs it is the number of characters from the beginning of the
3754: LOB at which to begin writing. For binary LOBs it is the number of bytes from
3755: the beginning of the lob from which to begin reading. The offset starts at 1.
3756: src_offset (IN) - this is the absolute offset for the source BFILE. It is
3757: the number of bytes from the beginning of the LOB. The offset starts at 1.
3758:
3759: See Also
3760: OCIErrorGet(), OCILobAppend(), OCILobWrite(), OCILobTrim(), OCILobCopy()
3761:
3762: OCILobLocatorAssign()
3763:
3764: Name
3765: OCI Lob LOCATOR ASsiGn
3766:
3767: Purpose
3768: Assigns one LOB/FILE locator to another.
3769:
3770: Syntax
3771: sword OCILobLocatorAssign ( OCISvcCtx *svchp,
3772: OCIError *errhp,
3773: CONST OCILobLocator *src_locp,
3774: OCILobLocator **dst_locpp );
3775:
3776: Comments
3777: Assign source locator to destination locator. After the assignment, both
3778: locators refer to the same LOB data. For internal LOBs, the source locator's
3779: LOB data gets copied to the destination locator's LOB data only when the
3780: destination locator gets stored in the table. Therefore, issuing a flush of
3781: the object containing the destination locator will copy the LOB data. For
3782: FILEs only the locator that refers to the OS file is copied to the table. The
3783: OS file is not copied.
3784: Note : the only difference between this and OCILobAssign is that this takes
3785: a OCI service handle pointer instead of a OCI environment handle pointer
3786:
3787: Parameters
3788: svchp (IN/OUT) - OCI service handle initialized in object mode.
3789: errhp (IN/OUT) - The OCI error handle. If there is an error, it is recorded
3790: in errhp and this function returns OCI_ERROR. Diagnostic information can be
3791: obtained by calling OCIErrorGet().
3792: src_locp (IN) - LOB locator to copy from.
3793: dst_locpp (IN/OUT) - LOB locator to copy to. The caller must allocate space
3794: for the OCILobLocator by calling OCIDescriptorAlloc().
3795:
3796: See also
3797: OCIErrorGet()
3798: OCILobIsEqual()
3799: OCILobLocatorIsInit()
3800: OCILobAssign()
3801:
3802:
3803:
3804:
3805: OCILobLocatorIsInit()
3806:
3807: Name
3808: OCI LOB locator is initialized?
3809:
3810: Purpose
3811: Tests to see if a given LOB locator is initialized.
3812:
3813: Syntax
3814: sword OCILobLocatorIsInit ( OCIEnv *envhp,
3815: OCIError *errhp,
3816: CONST OCILobLocator *locp,
3817: boolean *is_initialized );
3818:
3819: Comments
3820: Tests to see if a given LOB locator is initialized.
3821:
3822: Parameters
3823: envhp (IN/OUT) - OCI environment handle initialized in object mode.
3824: errhp (IN/OUT) - error handle. The OCI error handle. If there is an error, it
3825: is recorded in err and this function returns OCI_ERROR. Diagnostic
3826: information can be obtained by calling OCIErrorGet().
3827: locp (IN) - the LOB locator being tested
3828: is_initialized (OUT) - returns TRUE if the given LOB locator is initialized;
3829: FALSE if it is not.
3830:
3831: See also
3832: OCIErrorGet, OCILobIsEqual
3833:
3834:
3835:
3836:
3837: OCILobRead()
3838:
3839: Name
3840: OCI Lob/File ReaD
3841:
3842: Purpose
3843: Reads a portion of a LOB/FILE as specified by the call into a buffer.
3844:
3845: Syntax
3846: sword OCILobRead ( OCISvcCtx *svchp,
3847: OCIError *errhp,
3848: OCILobLocator *locp,
3849: ub4 offset,
3850: ub4 *amtp,
3851: dvoid *bufp,
3852: ub4 bufl,
3853: dvoid *ctxp,
3854: OCICallbackLobRead (cbfp)
3855: (
3856: dvoid *ctxp,
3857: CONST dvoid *bufp,
3858: ub4 len,
3859: ub1 piece )
3860: ub2 csid,
3861: ub1 csfrm );
3862:
3863: Comments
3864: Reads a portion of a LOB/FILE as specified by the call into a buffer. Data
3865: read from a hole is returned as 0s. It is an error to try to read from a NULL
3866: LOB/FILE. The OS FILE must already exist on the server and must have been
3867: opened using the input locator. Oracle must hav epermission to read the OS
3868: file and user must have read permission on the directory object.
3869:
3870: Parameters
3871: svchp (IN/OUT) - the service context handle.
3872: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3873: diagnostic information in the event of an error.
3874: locp (IN/OUT) - a LOB locator that uniquely references a LOB.
3875: offset (IN) - On input, it is the absolute offset, for character LOBs in the
3876: number of characters from the beginning of the LOB, for binary LOBs it is the
3877: number of bytes. Starts from 1.
3878: amtp (IN/OUT) - On input, the number of character or bytes to be read. On
3879: output, the actual number of bytes or characters read.
3880: If the amount of bytes to be read is larger than the buffer length it is
3881: assumed that the LOB is being read in a streamed mode. On input if this value
3882: is 0, then the data shall be read in streamed mode from the LOB until the end
3883: of LOB. If the data is read in pieces, *amtp always contains the length of
3884: the last piece read. If a callback function is defined, then this callback
3885: function will be invoked each time bufl bytes are read off the pipe. Each
3886: piece will be written into bufp.
3887: If the callback function is not defined, then OCI_NEED_DATA error code will
3888: be returned. The application must invoke the LOB read over and over again to
3889: read more pieces of the LOB until the OCI_NEED_DATA error code is not
3890: returned. The buffer pointer and the length can be different in each call
3891: if the pieces are being read into different sizes and location.
3892: bufp (IN) - the pointer to a buffer into which the piece will be read. The
3893: length of the allocated memory is assumed to be bufl.
3894: bufl (IN) - the length of the buffer in octets.
3895: ctxp (IN) - the context for the call back function. Can be NULL.
3896: cbfp (IN) - a callback that may be registered to be called for each piece. If
3897: this is NULL, then OCI_NEED_DATA will be returned for each piece.
3898: The callback function must return OCI_CONTINUE for the read to continue.
3899: If any other error code is returned, the LOB read is aborted.
3900: ctxp (IN) - the context for the call back function. Can be NULL.
3901: bufp (IN) - a buffer pointer for the piece.
3902: len (IN) - the length of length of current piece in bufp.
3903: piece (IN) - which piece - OCI_FIRST_PIECE, OCI_NEXT_PIECE or
3904: OCI_LAST_PIECE.
3905: csid - the character set ID of the buffer data
3906: csfrm - the character set form of the buffer data
3907:
3908: Related Functions
3909: OCIErrorGet, OCILobWrite, OCILobFileOpen, OCILobFileSetName, CREATE DIRECTORY
3910:
3911:
3912:
3913:
3914: OCILobTrim()
3915:
3916: Name
3917:
3918: OCI Lob Trim
3919:
3920: Purpose
3921: Trims the lob value to a shorter length
3922:
3923: Syntax
3924: sword OCILobTrim ( OCISvcCtx *svchp,
3925: OCIError *errhp,
3926: OCILobLocator *locp,
3927: ub4 newlen );
3928:
3929: Comments
3930: Truncates LOB data to a specified shorter length.
3931:
3932: Parameters
3933: svchp (IN) - the service context handle.
3934: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3935: diagnostic information in the event of an error.
3936: locp (IN/OUT) - a LOB locator that uniquely references the LOB. This locator
3937: must be a locator that was obtained from the server specified by svchp.
3938: newlen (IN) - the new length of the LOB data, which must be less than or equal
3939: to the current length.
3940:
3941: Related Functions
3942: OCIErrorGet, OCILobWrite, OCiLobErase, OCILobAppend, OCILobCopy
3943:
3944:
3945:
3946:
3947:
3948: OCILobWrite()
3949:
3950: Name
3951: OCI Lob Write
3952:
3953: Purpose
3954: Writes a buffer into a LOB
3955:
3956: Syntax
3957: sword OCILobWrite ( OCISvcCtx *svchp,
3958: OCIError *errhp,
3959: OCILobLocator *locp,
3960: ub4 offset,
3961: ub4 *amtp,
3962: dvoid *bufp,
3963: ub4 buflen,
3964: ub1 piece,
3965: dvoid *ctxp,
3966: OCICallbackLobWrite (cbfp)
3967: (
3968: dvoid *ctxp,
3969: dvoid *bufp,
3970: ub4 *lenp,
3971: ub1 *piecep )
3972: ub2 csid
3973: ub1 csfrm );
3974:
3975:
3976: Comments
3977: Writes a buffer into a LOB as specified. If LOB data already exists
3978: it is overwritten with the data stored in the buffer.
3979: The buffer can be written to the LOB in a single piece with this call, or
3980: it can be provided piecewise using callbacks or a standard polling method.
3981: If this value of the piece parameter is OCI_FIRST_PIECE, data must be
3982: provided through callbacks or polling.
3983: If a callback function is defined in the cbfp parameter, then this callback
3984: function will be invoked to get the next piece after a piece is written to
3985: the pipe. Each piece will be written from bufp.
3986: If no callback function is defined, then OCILobWrite() returns the
3987: OCI_NEED_DATA error code. The application must all OCILobWrite() again
3988: to write more pieces of the LOB. In this mode, the buffer pointer and the
3989: length can be different in each call if the pieces are of different sizes and
3990: from different locations. A piece value of OCI_LAST_PIECE terminates the
3991: piecewise write.
3992:
3993: Parameters
3994: svchp (IN/OUT) - the service context handle.
3995: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
3996: diagnostic information in the event of an error.
3997: locp (IN/OUT) - a LOB locator that uniquely references a LOB.
3998: offset (IN) - On input, it is the absolute offset, for character LOBs in
3999: the number of characters from the beginning of the LOB, for binary LOBs it
4000: is the number of bytes. Starts at 1.
4001: bufp (IN) - the pointer to a buffer from which the piece will be written. The
4002: length of the allocated memory is assumed to be the value passed in bufl.
4003: Even if the data is being written in pieces, bufp must contain the first
4004: piece of the LOB when this call is invoked.
4005: bufl (IN) - the length of the buffer in bytes.
4006: Note: This parameter assumes an 8-bit byte. If your platform uses a
4007: longer byte, the value of bufl must be adjusted accordingly.
4008: piece (IN) - which piece of the buffer is being written. The default value for
4009: this parameter is OCI_ONE_PIECE, indicating the buffer will be written in a
4010: single piece.
4011: The following other values are also possible for piecewise or callback mode:
4012: OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.
4013: amtp (IN/OUT) - On input, takes the number of character or bytes to be
4014: written. On output, returns the actual number of bytes or characters written.
4015: If the data is written in pieces, *amtp will contain the total length of the
4016: pieces written at the end of the call (last piece written) and is undefined in
4017: between.
4018: (Note it is different from the piecewise read case)
4019: ctxp (IN) - the context for the call back function. Can be NULL.
4020: cbfp (IN) - a callback that may be registered to be called for each piece in
4021: a piecewise write. If this is NULL, the standard polling method will be used.
4022: The callback function must return OCI_CONTINUE for the write to continue.
4023: If any other error code is returned, the LOB write is aborted. The
4024: callback takes the following parameters:
4025: ctxp (IN) - the context for the call back function. Can be NULL.
4026: bufp (IN/OUT) - a buffer pointer for the piece.
4027: lenp (IN/OUT) - the length of the buffer (in octets) and the length of
4028: current piece in bufp (out octets).
4029: piecep (OUT) - which piece - OCI_NEXT_PIECE or OCI_LAST_PIECE.
4030: csid - the character set ID of the buffer data
4031: csfrm - the character set form of the buffer data
4032: Related Functions
4033:
4034: OCILobWriteAppend()
4035:
4036: Name
4037: OCI Lob Write Append
4038:
4039: Purpose
4040: Writes data to the end of a LOB value. This call provides the ability
4041: to get the length of the data and append it to the end of the LOB in
4042: a single round trip to the server.
4043:
4044: Syntax
4045: sword OCILobWriteAppend ( OCISvcCtx *svchp,
4046: OCIError *errhp,
4047: OCILobLocator *locp,
4048: ub4 *amtp,
4049: dvoid *bufp,
4050: ub4 buflen,
4051: ub1 piece,
4052: dvoid *ctxp,
4053: OCICallbackLobWrite (cbfp)
4054: (
4055: dvoid *ctxp,
4056: dvoid *bufp,
4057: ub4 *lenp,
4058: ub1 *piecep )
4059: ub2 csid
4060: ub1 csfrm );
4061:
4062:
4063: Comments
4064: Writes a buffer to the end of a LOB as specified. If LOB data already exists
4065: it is overwritten with the data stored in the buffer.
4066: The buffer can be written to the LOB in a single piece with this call, or
4067: it can be provided piecewise using callbacks or a standard polling method.
4068: If this value of the piece parameter is OCI_FIRST_PIECE, data must be
4069: provided through callbacks or polling.
4070: If a callback function is defined in the cbfp parameter, then this callback
4071: function will be invoked to get the next piece after a piece is written to the
4072: pipe. Each piece will be written from bufp.
4073: If no callback function is defined, then OCILobWriteAppend() returns the
4074: OCI_NEED_DATA error code. The application must all OCILobWriteAppend() again
4075: to write more pieces of the LOB. In this mode, the buffer pointer and the
4076: length can be different in each call if the pieces are of different sizes and
4077: from different locations. A piece value of OCI_LAST_PIECE terminates the
4078: piecewise write.
4079:
4080: Parameters
4081: svchp (IN/OUT) - the service context handle.
4082: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
4083: diagnostic information in the event of an error.
4084: locp (IN/OUT) - a LOB locator that uniquely references a LOB.
4085: bufp (IN) - the pointer to a buffer from which the piece will be written. The
4086: length of the allocated memory is assumed to be the value passed in bufl. Even
4087: if the data is being written in pieces, bufp must contain the first piece of
4088: the LOB when this call is invoked.
4089: bufl (IN) - the length of the buffer in bytes.
4090: Note: This parameter assumes an 8-bit byte. If your platform uses a
4091: longer byte, the value of bufl must be adjusted accordingly.
4092: piece (IN) - which piece of the buffer is being written. The default value for
4093: this parameter is OCI_ONE_PIECE, indicating the buffer will be written in a
4094: single piece.
4095: The following other values are also possible for piecewise or callback mode:
4096: OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.
4097: amtp (IN/OUT) - On input, takes the number of character or bytes to be
4098: written. On output, returns the actual number of bytes or characters written.
4099: If the data is written in pieces, *amtp will contain the total length of the
4100: pieces written at the end of the call (last piece written) and is undefined in
4101: between.
4102: (Note it is different from the piecewise read case)
4103: ctxp (IN) - the context for the call back function. Can be NULL.
4104: cbfp (IN) - a callback that may be registered to be called for each piece in a
4105: piecewise write. If this is NULL, the standard polling method will be used.
4106: The callback function must return OCI_CONTINUE for the write to continue.
4107: If any other error code is returned, the LOB write is aborted. The
4108: callback takes the following parameters:
4109: ctxp (IN) - the context for the call back function. Can be NULL.
4110: bufp (IN/OUT) - a buffer pointer for the piece.
4111: lenp (IN/OUT) - the length of the buffer (in octets) and the length of
4112: current piece in bufp (out octets).
4113: piecep (OUT) - which piece - OCI_NEXT_PIECE or OCI_LAST_PIECE.
4114: csid - the character set ID of the buffer data
4115: csfrm - the character set form of the buffer data
4116: Related Functions
4117:
4118:
4119:
4120: OCILogoff()
4121: Name
4122: OCI simplified Logoff
4123: Purpose
4124: This function is used to terminate a session created with OCILogon().
4125: Syntax
4126: sword OCILogoff ( OCISvcCtx *svchp
4127: OCIError *errhp );
4128: Comments
4129: This call is used to terminate a session which was created with OCILogon().
4130: This call implicitly deallocates the server, authentication, and service
4131: context handles.
4132: Note: For more information on logging on and off in an application,
4133: refer to the section "Application Initialization, Connection, and
4134: Authorization" on page 2-16.
4135: Parameters
4136: svchp (IN) - the service context handle which was used in the call to
4137: OCILogon().
4138: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
4139: diagnostic information in the event of an error.
4140: See Also
4141: OCILogon()
4142:
4143:
4144:
4145:
4146:
4147:
4148: OCILogon()
4149: Name
4150: OCI Service Context Logon
4151: Purpose
4152: This function is used to create a simple logon session.
4153: Syntax
4154: sword OCILogon ( OCIEnv *envhp,
4155: OCIError *errhp,
4156: OCISvcCtx *svchp,
4157: CONST OraText *username,
4158: ub4 uname_len,
4159: CONST OraText *password,
4160: ub4 passwd_len,
4161: CONST OraText *dbname,
4162: ub4 dbname_len );
4163: Comments
4164: This function is used to create a simple logon session for an application.
4165: Note: Users requiring more complex session (e.g., TP monitor
4166: applications) should refer to the section "Application Initialization,
4167: Connection, and Authorization" on page 2-16.
4168: This call allocates the error and service context handles which are passed to
4169: it. This call also implicitly allocates server and authentication handles
4170: associated with the session. These handles can be retrieved by calling
4171: OCIAttrGet() on the service context handle.
4172: Parameters
4173: envhp (IN) - the OCI environment handle.
4174: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
4175: diagnostic information in the event of an error.
4176: svchp (OUT) - the service context pointer.
4177: username (IN) - the username.
4178: uname_len (IN) - the length of username.
4179: password (IN) - the user's password.
4180: passwd_len (IN) - the length of password.
4181: dbname (IN) - the name of the database to connect to.
4182: dbname_len (IN) - the length of dbname.
4183: See Also
4184: OCILogoff()
4185:
4186:
4187:
4188:
4189:
4190: OCIMemoryFree()
4191: Name
4192: OCI FREE Memory
4193: Purpose
4194: Frees up storage associated with the pointer.
4195: Syntax
4196: void OCIMemoryFree ( CONST OCIStmt *stmhp,
4197: dvoid *memptr);
4198: Comments
4199: Frees up dynamically allocated data pointers associated with the pointer using
4200: either the default memory free function or the registered memory free
4201: function, as the case may be.
4202: A user-defined memory free function can be registered during the initial call
4203: to OCIInitialize().
4204: This call is always successful.
4205: Parameters
4206: stmhp (IN) - statement handle which returned this data buffer.
4207: memptr (IN) - pointer to data allocated by the client library.
4208: Related Functions
4209: OCIInitialize()
4210:
4211:
4212:
4213:
4214:
4215: OCIParamGet()
4216: Name
4217: OCI Get PARaMeter
4218: Purpose
4219: Returns a descriptor of a parameter specified by position in the describe
4220: handle or statement handle.
4221: Syntax
4222: sword OCIParamGet ( CONST dvoid *hndlp,
4223: ub4 htype,
4224: OCIError *errhp,
4225: dvoid **parmdpp,
4226: ub4 pos );
4227: Comments
4228: This call returns a descriptor of a parameter specified by position in the
4229: describe handle or statement handle. Parameter descriptors are always
4230: allocated internally by the OCI library. They are read-only.
4231: OCI_NO_DATA may be returned if there are no parameter descriptors for this
4232: position.
4233: See Appendix B for more detailed information about parameter descriptor
4234: attributes.
4235: Parameters
4236: hndlp (IN) - a statement handle or describe handle. The OCIParamGet()
4237: function will return a parameter descriptor for this handle.
4238: htype (IN) - the type of the handle passed in the handle parameter. Valid
4239: types are OCI_HTYPE_DESCRIBE, for a describe handle OCI_HTYPE_STMT, for a
4240: statement handle
4241: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
4242: diagnostic information in the event of an error.
4243: parmdpp (OUT) - a descriptor of the parameter at the position given in the pos
4244: parameter.
4245: pos (IN) - position number in the statement handle or describe handle. A
4246: parameter descriptor will be returned for this position.
4247: Note: OCI_NO_DATA may be returned if there are no parameter
4248: descriptors for this position.
4249: Related Functions
4250: OCIAttrGet(), OCIAttrSet()
4251:
4252:
4253:
4254:
4255:
4256: OCIParamSet()
4257: Name
4258: OCI Parameter Set in handle
4259: Purpose
4260: Used to set a complex object retrieval descriptor into a complex object
4261: retrieval handle.
4262: Syntax
4263: sword OCIParamGet ( dvoid *hndlp,
4264: ub4 htyp,
4265: OCIError *errhp,
4266: CONST dvoid *dscp,
4267: ub4 dtyp,
4268: ub4 pos );
4269: Comments
4270: This call sets a given complex object retrieval descriptor into a complex
4271: object retrieval handle.
4272: The handle must have been previously allocated using OCIHandleAlloc(), and
4273: the descriptor must have been previously allocated using OCIDescAlloc().
4274: Attributes of the descriptor are set using OCIAttrSet().
4275: Parameters
4276: hndlp (IN/OUT) - handle pointer.
4277: htype (IN) - handle type.
4278: errhp (IN/OUT) - error handle.
4279: dscp (IN) - complex object retrieval descriptor pointer.
4280: dtyp (IN) -
4281: pos (IN) - position number.
4282: See Also
4283:
4284:
4285:
4286:
4287:
4288: OCIPasswordChange()
4289: Name
4290: OCI Change PassWord
4291: Purpose
4292: This call allows the password of an account to be changed.
4293: Syntax
4294: sword OCIPasswordChange ( OCISvcCtx *svchp,
4295: OCIError *errhp,
4296: CONST OraText *user_name,
4297: ub4 usernm_len,
4298: CONST OraText *opasswd,
4299: ub4 opasswd_len,
4300: CONST OraText *npasswd,
4301: sb4 npasswd_len,
4302: ub4 mode);
4303: Comments
4304: This call allows the password of an account to be changed. This call is
4305: similar to OCISessionBegin() with the following differences:
4306: If the user authentication is already established, it authenticates
4307: the account using the old password and then changes the
4308: password to the new password
4309: If the user authentication is not established, it establishes a user
4310: authentication and authenticates the account using the old
4311: password, then changes the password to the new password.
4312: This call is useful when the password of an account is expired and
4313: OCISessionBegin() returns an error or warning which indicates that the
4314: password has expired.
4315: Parameters
4316: svchp (IN/OUT) - a handle to a service context. The service context handle
4317: must be initialized and have a server context handle associated with it.
4318: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
4319: diagnostic information in the event of an error.
4320: user_name (IN) - specifies the user name. It points to a character string,
4321: whose length is specified in usernm_len. This parameter must be NULL if the
4322: service context has been initialized with an authentication handle.
4323: usernm_len (IN) - the length of the user name string specified in user_name.
4324: For a valid user name string, usernm_len must be non-zero.
4325: opasswd (IN) - specifies the user's old password. It points to a character
4326: string, whose length is specified in opasswd_len .
4327: opasswd_len (IN) - the length of the old password string specified in opasswd.
4328: For a valid password string, opasswd_len must be non-zero.
4329: npasswd (IN) - specifies the user's new password. It points to a character
4330: string, whose length is specified in npasswd_len which must be non-zero for a
4331: valid password string. If the password complexity verification routine is
4332: specified in the user's profile to verify the new password's complexity, the
4333: new password must meet the complexity requirements of the verification
4334: function.
4335: npasswd_len (IN) - then length of the new password string specified in
4336: npasswd. For a valid password string, npasswd_len must be non-zero.
4337: mode - pass as OCI_DEFAULT.
4338: Related Functions
4339: OCISessionBegin()
4340:
4341:
4342: ----------------------------------OCIReset------------------------------------
4343:
4344:
4345: OCIReset()
4346: Name
4347: OCI Reset
4348: Purpose
4349: Resets the interrupted asynchronous operation and protocol. Must be called
4350: if a OCIBreak call had been issued while a non-blocking operation was in
4351: progress.
4352: Syntax
4353: sword OCIReset ( dvoid *hndlp,
4354: OCIError *errhp);
4355: Comments
4356: This call is called in non-blocking mode ONLY. Resets the interrupted
4357: asynchronous operation and protocol. Must be called if a OCIBreak call
4358: had been issued while a non-blocking operation was in progress.
4359: Parameters
4360: hndlp (IN) - the service context handle or the server context handle.
4361: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
4362: diagnostic information in the event of an error.
4363: Related Functions
4364:
4365:
4366: OCIResultSetToStmt()
4367: Name
4368: OCI convert Result Set to Statement Handle
4369: Purpose
4370: Converts a descriptor to statement handle for fetching rows.
4371: Syntax
4372: sword OCIResultSetToStmt ( OCIResult *rsetdp,
4373: OCIError *errhp );
4374: Comments
4375: Converts a descriptor to statement handle for fetching rows.
4376: A result set descriptor can be allocated with a call to OCIDescAlloc().
4377: Parameters
4378: rsetdp (IN/OUT) - a result set descriptor pointer.
4379: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
4380: diagnostic information in the event of an error.
4381: Related Functions
4382: OCIDescAlloc()
4383:
4384:
4385:
4386:
4387: OCIServerAttach()
4388: Name
4389: OCI ATtaCH to server
4390: Purpose
4391: Creates an access path to a data source for OCI operations.
4392: Syntax
4393: sword OCIServerAttach ( OCIServer *srvhp,
4394: OCIError *errhp,
4395: CONST OraText *dblink,
4396: sb4 dblink_len,
4397: ub4 mode);
4398: Comments
4399: This call is used to create an association between an OCI application and a
4400: particular server.
4401: This call initializes a server context handle, which must have been previously
4402: allocated with a call to OCIHandleAlloc().
4403: The server context handle initialized by this call can be associated with a
4404: service context through a call to OCIAttrSet(). Once that association has been
4405: made, OCI operations can be performed against the server.
4406: If an application is operating against multiple servers, multiple server
4407: context handles can be maintained. OCI operations are performed against
4408: whichever server context is currently associated with the service context.
4409: Parameters
4410: srvhp (IN/OUT) - an uninitialized server context handle, which gets
4411: initialized by this call. Passing in an initialized server handle causes an
4412: error.
4413: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
4414: diagnostic information in the event of an error.
4415: dblink (IN) - specifies the database (server) to use. This parameter points to
4416: a character string which specifies a connect string or a service point. If the
4417: connect string is NULL, then this call attaches to the default host. The length
4418: of connstr is specified in connstr_len. The connstr pointer may be freed by the
4419: caller on return.
4420: dblink_len (IN) - the length of the string pointed to by connstr. For a valid
4421: connect string name or alias, connstr_len must be non-zero.
4422: mode (IN) - specifies the various modes of operation. For release 8.0, pass as
4423: OCI_DEFAULT - in this mode, calls made to the server on this server context
4424: are made in blocking mode.
4425: Example
4426: See the description of OCIStmtPrepare() on page 13-96 for an example showing
4427: the use of OCIServerAttach().
4428: Related Functions
4429: OCIServerDetach()
4430:
4431:
4432:
4433: OCIServerDetach()
4434: Name
4435: OCI DeTaCH server
4436: Purpose
4437: Deletes an access to a data source for OCI operations.
4438: Syntax
4439: sword OCIServerDetach ( OCIServer *svrhp,
4440: OCIError *errhp,
4441: ub4 mode);
4442: Comments
4443: This call deletes an access to data source for OCI operations, which was
4444: established by a call to OCIServerAttach().
4445: Parameters
4446: srvhp (IN) - a handle to an initialized server context, which gets reset to
4447: uninitialized state. The handle is not de-allocated.
4448: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
4449: diagnostic information in the event of an error.
4450: mode (IN) - specifies the various modes of operation. The only valid mode is
4451: OCI_DEFAULT for the default mode.
4452: Related Functions
4453: OCIServerAttach()
4454:
4455:
4456:
4457: OCIServerVersion()
4458: Name
4459: OCI VERSion
4460: Purpose
4461: Returns the version string of the Oracle server.
4462: Syntax
4463: sword OCIServerVersion ( dvoid *hndlp,
4464: OCIError *errhp,
4465: OraText *bufp,
4466: ub4 bufsz
4467: ub1 hndltype );
4468: Comments
4469: This call returns the version string of the Oracle server.
4470: For example, the following might be returned as the version string if your
4471: application is running against a 7.3.2 server:
4472: Oracle7 Server Release 7.3.2.0.0 - Production Release
4473: PL/SQL Release 2.3.2.0.0 - Production
4474: CORE Version 3.5.2.0.0 - Production
4475: TNS for SEQUENT DYNIX/ptx: Version 2.3.2.0.0 - Production
4476: NLSRTL Version 3.2.2.0.0 - Production
4477:
4478: Parameters
4479: hndlp (IN) - the service context handle or the server context handle.
4480: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
4481: diagnostic information in the event of an error.
4482: bufp (IN) - the buffer in which the version information is returned.
4483: bufsz (IN) - the length of the buffer.
4484: hndltype (IN) - the type of handle passed to the function.
4485: Related Functions
4486:
4487:
4488:
4489:
4490:
4491: OCISessionBegin()
4492: Name
4493: OCI Session Begin and authenticate user
4494: Purpose
4495: Creates a user authentication and begins a user session for a given server.
4496: Syntax
4497: sword OCISessionBegin ( OCISvcCtx *svchp,
4498: OCIError *errhp,
4499: OCISession *usrhp,
4500: ub4 credt,
4501: ub4 mode);
4502:
4503: Comments
4504: For Oracle8, OCISessionBegin() must be called for any given server handle
4505: before requests can be made against it. Also, OCISessionBegin() only supports
4506: authenticating the user for access to the Oracle server specified by the
4507: server handle in the service context. In other words, after OCIServerAttach()
4508: is called to initialize a server handle, OCISessionBegin() must be called to
4509: authenticate the user for that given server.
4510: When OCISessionBegin() is called for the first time for the given server
4511: handle, the initialized authentication handle is called a primary
4512: authentication context. A primary authentication context may not be created
4513: with the OCI_MIGRATE mode. Also, only one primary authentication context can
4514: be created for a given server handle and the primary authentication context c
4515: an only ever be used with that server handle. If the primary authentication
4516: context is set in a service handle with a different server handle, then an
4517: error will result.
4518: After OCISessionBegin() has been called for the server handle, and the primary
4519: authentication context is set in the service handle, OCISessionBegin() may be
4520: called again to initialize another authentication handle with different (or
4521: the same) credentials. When OCISessionBegin() is called with a service handle
4522: set with a primary authentication context, the returned authentication context
4523: in authp is called a user authentication context. As many user authentication
4524: contexts may be initialized as desired.
4525: User authentication contexts may be created with the OCI_MIGRATE mode.
4526: If the OCI_MIGRATE mode is not specified, then the user authentication
4527: context can only ever be used with the same server handle set in svchp. If
4528: OCI_MIGRATE mode is specified, then the user authentication may be set
4529: with different server handles. However, the user authentication context is
4530: restricted to use with only server handles which resolve to the same database
4531: instance and that have equivalent primary authentication contexts. Equivalent
4532: authentication contexts are those which were authenticated as the same
4533: database user.
4534: OCI_SYSDBA, OCI_SYSOPER, and OCI_PRELIM_AUTH may only be used
4535: with a primary authentication context.
4536: To provide credentials for a call to OCISessionBegin(), one of two methods are
4537: supported. The first is to provide a valid username and password pair for
4538: database authentication in the user authentication handle passed to
4539: OCISessionBegin(). This involves using OCIAttrSet() to set the
4540: OCI_ATTR_USERNAME and OCI_ATTR_PASSWORD attributes on the
4541: authentication handle. Then OCISessionBegin() is called with
4542: OCI_CRED_RDBMS.
4543: Note: When the authentication handle is terminated using
4544: OCISessionEnd(), the username and password attributes remain
4545: unchanged and thus can be re-used in a future call to OCISessionBegin().
4546: Otherwise, they must be reset to new values before the next
4547: OCISessionBegin() call.
4548: The second type of credentials supported are external credentials. No
4549: attributes need to be set on the authentication handle before calling
4550: OCISessionBegin(). The credential type is OCI_CRED_EXT. This is equivalent
4551: to the Oracle7 `connect /' syntax. If values have been set for
4552: OCI_ATTR_USERNAME and OCI_ATTR_PASSWORD, then these are
4553: ignored if OCI_CRED_EXT is used.
4554: Parameters
4555: svchp (IN) - a handle to a service context. There must be a valid server
4556: handle set in svchp.
4557: errhp (IN) - an error handle to the retrieve diagnostic information.
4558: usrhp (IN/OUT) - a handle to an authentication context, which is initialized
4559: by this call.
4560: credt (IN) - specifies the type of credentials to use for authentication.
4561: Valid values for credt are:
4562: OCI_CRED_RDBMS - authenticate using a database username and
4563: password pair as credentials. The attributes OCI_ATTR_USERNAME
4564: and OCI_ATTR_PASSWORD should be set on the authentication
4565: context before this call.
4566: OCI_CRED_EXT - authenticate using external credentials. No username
4567: or password is provided.
4568: mode (IN) - specifies the various modes of operation. Valid modes are:
4569: OCI_DEFAULT - in this mode, the authentication context returned may
4570: only ever be set with the same server context specified in svchp. This
4571: establishes the primary authentication context.
4572: OCI_MIGRATE - in this mode, the new authentication context may be
4573: set in a service handle with a different server handle. This mode
4574: establishes the user authentication context.
4575: OCI_SYSDBA - in this mode, the user is authenticated for SYSDBA
4576: access.
4577: OCI_SYSOPER - in this mode, the user is authenticated for SYSOPER
4578: access.
4579: OCI_PRELIM_AUTH - this mode may only be used with OCI_SYSDBA
4580: or OCI_SYSOPER to authenticate for certain administration tasks.
4581: Related Functions
4582: OCISessionEnd()
4583:
4584:
4585:
4586:
4587:
4588:
4589: OCISessionEnd()
4590: Name
4591: OCI Terminate user Authentication Context
4592: Purpose
4593: Terminates a user authentication context created by OCISessionBegin()
4594: Syntax
4595: sword OCISessionEnd ( OCISvcCtx *svchp,
4596: OCIError *errhp,
4597: OCISession *usrhp,
4598: ub4 mode);
4599:
4600: Comments
4601: The user security context associated with the service context is invalidated
4602: by this call. Storage for the authentication context is not freed. The
4603: transaction specified by the service context is implicitly committed. The
4604: transaction handle, if explicitly allocated, may be freed if not being used.
4605: Resources allocated on the server for this user are freed.
4606: The authentication handle may be reused in a new call to OCISessionBegin().
4607: Parameters
4608: svchp (IN/OUT) - the service context handle. There must be a valid server
4609: handle and user authentication handle associated with svchp.
4610: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
4611: diagnostic information in the event of an error.
4612: usrhp (IN) - de-authenticate this user. If this parameter is passed as NULL, the
4613: user in the service context handle is de-authenticated.
4614: mode (IN) - the only valid mode is OCI_DEFAULT.
4615: Example
4616: In this example, an authentication context is destroyed.
4617: Related Functions
4618: OCISessionBegin()
4619:
4620:
4621:
4622:
4623: OCIStmtExecute()
4624: Name
4625: OCI EXECute
4626: Purpose
4627: This call associates an application request with a server.
4628: Syntax
4629: sword OCIStmtExecute ( OCISvcCtx *svchp,
4630: OCIStmt *stmtp,
4631: OCIError *errhp,
4632: ub4 iters,
4633: ub4 rowoff,
4634: CONST OCISnapshot *snap_in,
4635: OCISnapshot *snap_out,
4636: ub4 mode );
4637: Comments
4638: This function is used to execute a prepared SQL statement.
4639: Using an execute call, the application associates a request with a server. On
4640: success, OCI_SUCCESS is returned.
4641: If a SELECT statement is executed, the description of the select list follows
4642: implicitly as a response. This description is buffered on the client side for
4643: describes, fetches and define type conversions. Hence it is optimal to
4644: describe a select list only after an execute.
4645: Also for SELECT statements, some results are available implicitly. Rows will
4646: be received and buffered at the end of the execute. For queries with small row
4647: count, a prefetch causes memory to be released in the server if the end of
4648: fetch is reached, an optimization that may result in memory usage reduction.
4649: Set attribute call has been defined to set the number of rows to be prefetched
4650: per result set.
4651: For SELECT statements, at the end of the execute, the statement handle
4652: implicitly maintains a reference to the service context on which it is
4653: executed. It is the user's responsibility to maintain the integrity of the
4654: service context. If the attributes of a service context is changed for
4655: executing some operations on this service context, the service context must
4656: be restored to have the same attributes, that a statement was executed with,
4657: prior to a fetch on the statement handle. The implicit reference is maintained
4658: until the statement handle is freed or the fetch is cancelled or an end of
4659: fetch condition is reached.
4660: Note: If output variables are defined for a SELECT statement before a
4661: call to OCIStmtExecute(), the number of rows specified by iters will be
4662: fetched directly into the defined output buffers and additional rows
4663: equivalent to the prefetch count will be prefetched. If there are no
4664: additional rows, then the fetch is complete without calling
4665: OCIStmtFetch().
4666: The execute call will return errors if the statement has bind data types that
4667: are not supported in an Oracle7 server.
4668: Parameters
4669: svchp (IN/OUT) - service context handle.
4670: stmtp (IN/OUT) - an statement handle - defines the statement and the
4671: associated data to be executed at the server. It is invalid to pass in a
4672: statement handle that has bind of data types only supported in release 8.0
4673: when srvchp points to an Oracle7 server.
4674: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
4675: diagnostic information in the event of an error. If the statement is being
4676: batched and it is successful, then this handle will contain this particular
4677: statement execution specific errors returned from the server when the batch is
4678: flushed.
4679: iters (IN) - the number of times this statement is executed for non-Select
4680: statements. For Select statements, if iters is non-zero, then defines must
4681: have been done for the statement handle. The execution fetches iters rows into
4682: these predefined buffers and prefetches more rows depending upon the prefetch
4683: row count. This function returns an error if iters=0 for non-SELECT
4684: statements.
4685: rowoff (IN) - the index from which the data in an array bind is relevant for
4686: this multiple row execution.
4687: snap_in (IN) - this parameter is optional. if supplied, must point to a
4688: snapshot descriptor of type OCI_DTYPE_SNAP. The contents of this descriptor
4689: must be obtained from the snap_out parameter of a previous call. The
4690: descriptor is ignored if the SQL is not a SELECT. This facility allows
4691: multiple service contexts to ORACLE to see the same consistent snapshot of the
4692: database's committed data. However, uncommitted data in one context is not
4693: visible to another context even using the same snapshot.
4694: snap_out (OUT) - this parameter optional. if supplied, must point to a
4695: descriptor of type OCI_DTYPE_SNAP. This descriptor is filled in with an
4696: opaque representation which is the current ORACLE "system change
4697: number" suitable as a snap_in input to a subsequent call to OCIStmtExecute().
4698: This descriptor should not be used any longer than necessary in order to avoid
4699: "snapshot too old" errors.
4700: mode (IN) - The modes are:
4701: If OCI_DEFAULT_MODE, the default mode, is selected, the request is
4702: immediately executed. Error handle contains diagnostics on error if any.
4703: OCI_EXACT_FETCH - if the statement is a SQL SELECT, this mode is
4704: only valid if the application has set the prefetch row count prior to this
4705: call. In this mode, the OCI library will get up to the number of rows
4706: specified (i.e., prefetch row count plus iters). If the number of rows
4707: returned by the query is greater than this value, OCI_ERROR will be
4708: returned with ORA-01422 as the implementation specific error in a
4709: diagnostic record. If the number of rows returned by the query is
4710: smaller than the prefetch row count, OCI_SUCCESS_WITH_INFO will
4711: be returned with ORA-01403 as the implementation specific error. The
4712: prefetch buffer size is ignored and the OCI library tries to allocate all the
4713: space required to contain the prefetched rows. The exact fetch semantics
4714: apply to only the top level rows. No more rows can be fetched for this
4715: query at the end of the call.
4716: OCI_KEEP_FETCH_STATE - the result set rows (not yet fetched) of this
4717: statement executed in this transaction will be maintained when the
4718: transaction is detached for migration. By default, a query is cancelled
4719: when a transaction is detached for migration. This mode is the default
4720: mode when connected to a V7 server.
4721: Related Functions
4722: OCIStmtPrepare()
4723:
4724:
4725:
4726:
4727:
4728: OCIStmtFetch()
4729: Name
4730: OCI FetCH
4731: Purpose
4732: Fetches rows from a query.
4733: Syntax
4734: sword OCIStmtFetch ( OCIStmt *stmtp,
4735: OCIError *errhp,
4736: ub4 nrows,
4737: ub2 orientation,
4738: ub4 mode);
4739: Comments
4740: The fetch call is a local call, if prefetched rows suffice. However, this is
4741: transparent to the application. If LOB columns are being read, LOB locators
4742: are fetched for subsequent LOB operations to be performed on these locators.
4743: Prefetching is turned off if LONG columns are involved.
4744: A fetch with nrows set to 0 rows effectively cancels the fetch for this
4745: statement.
4746: Parameters
4747: stmtp (IN) - a statement (application request) handle.
4748: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
4749: diagnostic information in the event of an error.
4750: nrows (IN) - number of rows to be fetched from the current position.
4751: orientation (IN) - for release 8.0, the only acceptable value is
4752: OCI_FETCH_NEXT, which is also the default value.
4753: mode (IN) - for release 8.0, beta-1, the following mode is defined.
4754: OCI_DEFAULT - default mode
4755: OCI_EOF_FETCH - indicates that it is the last fetch from the result set.
4756: If nrows is non-zero, setting this mode effectively cancels fetching after
4757: retrieving nrows, otherwise it cancels fetching immediately.
4758: Related Functions
4759: OCIAttrGet()
4760:
4761:
4762:
4763:
4764:
4765: OCIStmtGetBindInfo()
4766: Name
4767: OCI Get Bind Parameters
4768: Purpose
4769: Gets the bind and indicator variable names.
4770: Syntax
4771: sword OCIStmtGetBindInfo ( OCIStmt *stmtp,
4772: OCIError *errhp,
4773: ub4 size,
4774: ub4 startloc,
4775: sb4 *found,
4776: OraText *bvnp[],
4777: ub1 bvnl[],
4778: OraText *invp[],
4779: ub1 inpl[],
4780: ub1 dupl[],
4781: OCIBind *hndl[] );
4782:
4783: Comments
4784: Gets the bind and indicator variable names. It returns the information for all
4785: the bind variables (even the duplicate ones) and sets the found parameter to
4786: the total number of bind variables and not just the number of distinct bind
4787: variables.
4788: The statement must have been prepared with a call to OCIStmtPrepare() prior
4789: to this call.
4790: This call is processed locally.
4791: Parameters
4792: stmtp (IN) - the statement handle.
4793: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
4794: diagnostic information in the event of an error.
4795: size (IN) - the number of elements in each array.
4796: startloc (IN) - position of the bind variable at which to start getting bind
4797: information.
4798: found (IN) - abs(found) gives the total number of bind variables in the
4799: statement irrespective of the start position. Positive value if the number of
4800: bind variables returned is less than the size provided, otherwise negative.
4801: bvnp (OUT) - array of pointers to hold bind variable names.
4802: bvnl (OUT) - array to hold the length of the each bvnp element.
4803: invp (OUT) - array of pointers to hold indicator variable names.
4804: inpl (OUT) - array of pointers to hold the length of the each invp element.
4805: dupl (OUT) - an array whose element value is 0 or 1 depending on whether the
4806: bind position is duplicate of another.
4807: hndl (OUT) - an array which returns the bind handle if binds have been done
4808: for the bind position. No handle is returned for duplicates.
4809: Related Functions
4810: OCIStmtPrepare()
4811:
4812:
4813:
4814: OCIStmtGetPieceInfo()
4815: Name
4816: OCI Get Piece Information
4817: Purpose
4818: Returns piece information for a piecewise operation.
4819: Syntax
4820: sword OCIStmtGetPieceInfo( CONST OCIStmt *stmtp,
4821: OCIError *errhp,
4822: dvoid **hndlpp,
4823: ub4 *typep,
4824: ub1 *in_outp,
4825: ub4 *iterp,
4826: ub4 *idxp,
4827: ub1 *piecep );
4828:
4829: Comments
4830: When an execute/fetch call returns OCI_NEED_DATA to get/return a
4831: dynamic bind/define value or piece, OCIStmtGetPieceInfo() returns the
4832: relevant information: bind/define handle, iteration or index number and
4833: which piece.
4834: See the section "Runtime Data Allocation and Piecewise Operations" on page
4835: 5-16 for more information about using OCIStmtGetPieceInfo().
4836: Parameters
4837: stmtp (IN) - the statement when executed returned OCI_NEED_DATA.
4838: errhp (OUT) - an error handle which can be passed to OCIErrorGet() for
4839: diagnostic information in the event of an error.
4840: hndlpp (OUT) - returns a pointer to the bind or define handle of the bind or
4841: define whose runtime data is required or is being provided.
4842: typep (OUT) - the type of the handle pointed to by hndlpp: OCI_HTYPE_BIND
4843: (for a bind handle) or OCI_HTYPE_DEFINE (for a define handle).
4844: in_outp (OUT) - returns OCI_PARAM_IN if the data is required for an IN bind
4845: value. Returns OCI_PARAM_OUT if the data is available as an OUT bind
4846: variable or a define position value.
4847: iterp (OUT) - returns the row number of a multiple row operation.
4848: idxp (OUT) - the index of an array element of a PL/SQL array bind operation.
4849: piecep (OUT) - returns one of the following defined values -
4850: OCI_ONE_PIECE, OCI_FIRST_PIECE, OCI_NEXT_PIECE and
4851: OCI_LAST_PIECE. The default value is always OCI_ONE_PIECE.
4852: Related Functions
4853: OCIAttrGet(), OCIAttrGet(), OCIStmtExecute(), OCIStmtFetch(),
4854: OCIStmtSetPieceInfo()
4855:
4856:
4857:
4858:
4859: OCIStmtPrepare()
4860: Name
4861: OCI Statement REQuest
4862: Purpose
4863: This call defines the SQL/PLSQL statement to be executed.
4864: Syntax
4865: sword OCIStmtPrepare ( OCIStmt *stmtp,
4866: OCIError *errhp,
4867: CONST OraText *stmt,
4868: ub4 stmt_len,
4869: ub4 language,
4870: ub4 mode);
4871: Comments
4872: This call is used to prepare a SQL or PL/SQL statement for execution. The
4873: OCIStmtPrepare() call defines an application request.
4874: This is a purely local call. Data values for this statement initialized in
4875: subsequent bind calls will be stored in a bind handle which will hang off this
4876: statement handle.
4877: This call does not create an association between this statement handle and any
4878: particular server.
4879: See the section "Preparing Statements" on page 2-21 for more information
4880: about using this call.
4881: Parameters
4882: stmtp (IN) - a statement handle.
4883: errhp (IN) - an error handle to retrieve diagnostic information.
4884: stmt (IN) - SQL or PL/SQL statement to be executed. Must be a null-
4885: terminated string. The pointer to the OraText of the statement must be available
4886: as long as the statement is executed.
4887: stmt_len (IN) - length of the statement. Must not be zero.
4888: language (IN) - V7, V8, or native syntax. Possible values are:
4889: OCI_V7_SYNTAX - V7 ORACLE parsing syntax
4890: OCI_V8_SYNTAX - V8 ORACLE parsing syntax
4891: OCI_NTV_SYNTAX - syntax depending upon the version of the server.
4892: mode (IN) - the only defined mode is OCI_DEFAULT for default mode.
4893: Example
4894: This example demonstrates the use of OCIStmtPrepare(), as well as the OCI
4895: application initialization calls.
4896: Related Functions
4897: OCIAttrGet(), OCIStmtExecute()
4898:
4899:
4900: OCIStmtSetPieceInfo()
4901: Name
4902: OCI Set Piece Information
4903: Purpose
4904: Sets piece information for a piecewise operation.
4905: Syntax
4906: sword OCIStmtSetPieceInfo ( dvoid *hndlp,
4907: ub4 type,
4908: OCIError *errhp,
4909: CONST dvoid *bufp,
4910: ub4 *alenp,
4911: ub1 piece,
4912: CONST dvoid *indp,
4913: ub2 *rcodep );
4914: Comments
4915: When an execute call returns OCI_NEED_DATA to get a dynamic IN/OUT
4916: bind value or piece, OCIStmtSetPieceInfo() sets the piece information: the
4917: buffer, the length, the indicator and which piece is currently being processed.
4918: For more information about using OCIStmtSetPieceInfo() see the section
4919: "Runtime Data Allocation and Piecewise Operations" on page 5-16.
4920: Parameters
4921: hndlp (IN/OUT) - the bind/define handle.
4922: type (IN) - type of the handle.
4923: errhp (OUT) - an error handle which can be passed to OCIErrorGet() for
4924: diagnostic information in the event of an error.
4925: bufp (IN/OUT) - bufp is a pointer to a storage containing the data value or
4926: the piece when it is an IN bind variable, otherwise bufp is a pointer to
4927: storage for getting a piece or a value for OUT binds and define variables. For
4928: named data types or REFs, a pointer to the object or REF is returned.
4929: alenp (IN/OUT) - the length of the piece or the value.
4930: piece (IN) - the piece parameter. The following are valid values:
4931: OCI_ONE_PIECE, OCI_FIRST_PIECE, OCI_NEXT_PIECE, or
4932: OCI_LAST_PIECE.
4933: The default value is OCI_ONE_PIECE. This parameter is used for IN bind
4934: variables only.
4935: indp (IN/OUT) - indicator. A pointer to a sb2 value or pointer to an indicator
4936: structure for named data types (SQLT_NTY) and REFs (SQLT_REF), i.e., *indp
4937: is either an sb2 or a dvoid * depending upon the data type.
4938: rcodep (IN/OUT) - return code.
4939: Related Functions
4940: OCIAttrGet(), OCIAttrGet(), OCIStmtExecute(), OCIStmtFetch(),
4941: OCIStmtGetPieceInfo()
4942:
4943:
4944: OCIFormatInit
4945: Name
4946: OCIFormat Package Initialize
4947: Purpose
4948: Initializes the OCIFormat package.
4949: Syntax
4950: sword OCIFormatInit(dvoid *hndl, OCIError *err);
4951: Comments
4952: This routine must be called before calling any other OCIFormat routine.
4953: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
4954: Parameters
4955: hndl (IN/OUT) - OCI environment or session handle
4956: err (IN/OUT) - OCI error handle
4957: Related Functions
4958: OCIFormatTerm()
4959:
4960:
4961: OCIFormatString
4962: Name
4963: OCIFormat Package Format String
4964: Purpose
4965: Writes a text string into the supplied text buffer using the argument
4966: list submitted to it and in accordance with the format string given.
4967: Syntax
4968: sword OCIFormatString(dvoid *hndl, OCIError *err, OraText *buffer,
4969: sbig_ora bufferLength, sbig_ora *returnLength,
4970: CONST OraText *formatString, ...);
4971: Comments
4972: The first call to this routine must be preceded by a call to the
4973: OCIFormatInit routine that initializes the OCIFormat package
4974: for use. When this routine is no longer needed then terminate
4975: the OCIFormat package by a call to the OCIFormatTerm routine.
4976: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
4977: Parameters
4978: hndl (IN/OUT) - OCI environment or session handle
4979: err (IN/OUT) - OCI error handle
4980: buffer (OUT) - text buffer for the string
4981: bufferLength (IN) - length of the text buffer
4982: returnLength (OUT) - length of the formatted string
4983: formatString (IN) - format specification string
4984: ... (IN) - variable argument list
4985: Related Functions
4986:
4987:
4988: OCIFormatTerm
4989: Name
4990: OCIFormat Package Terminate
4991: Purpose
4992: Terminates the OCIFormat package.
4993: Syntax
4994: sword OCIFormatTerm(dvoid *hndl, OCIError *err);
4995: Comments
4996: It must be called after the OCIFormat package is no longer being used.
4997: Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
4998: Parameters
4999: hndl (IN/OUT) - OCI environment or session handle
5000: err (IN/OUT) - OCI error handle
5001: Related Functions
5002: OCIFormatInit()
5003:
5004:
5005: OCIFormatTUb1
5006: Name
5007: OCIFormat Package ub1 Type
5008: Purpose
5009: Return the type value for the ub1 type.
5010: Syntax
5011: sword OCIFormatTUb1(void);
5012: Comments
5013: None
5014: Parameters
5015: None
5016: Related Functions
5017: None
5018:
5019:
5020: OCIFormatTUb2
5021: Name
5022: OCIFormat Package ub2 Type
5023: Purpose
5024: Return the type value for the ub2 type.
5025: Syntax
5026: sword OCIFormatTUb2(void);
5027: Comments
5028: None
5029: Parameters
5030: None
5031: Related Functions
5032: None
5033:
5034:
5035: OCIFormatTUb4
5036: Name
5037: OCIFormat Package ub4 Type
5038: Purpose
5039: Return the type value for the ub4 type.
5040: Syntax
5041: sword OCIFormatTUb4(void);
5042: Comments
5043: None
5044: Parameters
5045: None
5046: Related Functions
5047: None
5048:
5049:
5050: OCIFormatTUword
5051: Name
5052: OCIFormat Package uword Type
5053: Purpose
5054: Return the type value for the uword type.
5055: Syntax
5056: sword OCIFormatTUword(void);
5057: Comments
5058: None
5059: Parameters
5060: None
5061: Related Functions
5062: None
5063:
5064:
5065: OCIFormatTUbig_ora
5066: Name
5067: OCIFormat Package ubig_ora Type
5068: Purpose
5069: Return the type value for the ubig_ora type.
5070: Syntax
5071: sword OCIFormatTUbig_ora(void);
5072: Comments
5073: None
5074: Parameters
5075: None
5076: Related Functions
5077: None
5078:
5079:
5080: OCIFormatTSb1
5081: Name
5082: OCIFormat Package sb1 Type
5083: Purpose
5084: Return the type value for the sb1 type.
5085: Syntax
5086: sword OCIFormatTSb1(void);
5087: Comments
5088: None
5089: Parameters
5090: None
5091: Related Functions
5092: None
5093:
5094:
5095: OCIFormatTSb2
5096: Name
5097: OCIFormat Package sb2 Type
5098: Purpose
5099: Return the type value for the sb2 type.
5100: Syntax
5101: sword OCIFormatTSb2(void);
5102: Comments
5103: None
5104: Parameters
5105: None
5106: Related Functions
5107: None
5108:
5109:
5110: OCIFormatTSb4
5111: Name
5112: OCIFormat Package sb4 Type
5113: Purpose
5114: Return the type value for the sb4 type.
5115: Syntax
5116: sword OCIFormatTSb4(void);
5117: Comments
5118: None
5119: Parameters
5120: None
5121: Related Functions
5122: None
5123:
5124:
5125: OCIFormatTSword
5126: Name
5127: OCIFormat Package sword Type
5128: Purpose
5129: Return the type value for the sword type.
5130: Syntax
5131: sword OCIFormatTSword(void);
5132: Comments
5133: None
5134: Parameters
5135: None
5136: Related Functions
5137: None
5138:
5139:
5140: OCIFormatTSbig_ora
5141: Name
5142: OCIFormat Package sbig_ora Type
5143: Purpose
5144: Return the type value for the sbig_ora type.
5145: Syntax
5146: sword OCIFormatTSbig_ora(void);
5147: Comments
5148: None
5149: Parameters
5150: None
5151: Related Functions
5152: None
5153:
5154:
5155: OCIFormatTEb1
5156: Name
5157: OCIFormat Package eb1 Type
5158: Purpose
5159: Return the type value for the eb1 type.
5160: Syntax
5161: sword OCIFormatTEb1(void);
5162: Comments
5163: None
5164: Parameters
5165: None
5166: Related Functions
5167: None
5168:
5169:
5170: OCIFormatTEb2
5171: Name
5172: OCIFormat Package eb2 Type
5173: Purpose
5174: Return the type value for the eb2 type.
5175: Syntax
5176: sword OCIFormatTEb2(void);
5177: Comments
5178: None
5179: Parameters
5180: None
5181: Related Functions
5182: None
5183:
5184:
5185: OCIFormatTEb4
5186: Name
5187: OCIFormat Package eb4 Type
5188: Purpose
5189: Return the type value for the eb4 type.
5190: Syntax
5191: sword OCIFormatTEb4(void);
5192: Comments
5193: None
5194: Parameters
5195: None
5196: Related Functions
5197: None
5198:
5199:
5200: OCIFormatTEword
5201: Name
5202: OCIFormat Package eword Type
5203: Purpose
5204: Return the type value for the eword type.
5205: Syntax
5206: sword OCIFormatTEword(void);
5207: Comments
5208: None
5209: Parameters
5210: None
5211: Related Functions
5212: None
5213:
5214:
5215: OCIFormatTChar
5216: Name
5217: OCIFormat Package text Type
5218: Purpose
5219: Return the type value for the text type.
5220: Syntax
5221: sword OCIFormatTChar(void);
5222: Comments
5223: None
5224: Parameters
5225: None
5226: Related Functions
5227: None
5228:
5229:
5230: OCIFormatTText
5231: Name
5232: OCIFormat Package *text Type
5233: Purpose
5234: Return the type value for the *text type.
5235: Syntax
5236: sword OCIFormatTText(void);
5237: Comments
5238: None
5239: Parameters
5240: None
5241: Related Functions
5242: None
5243:
5244:
5245: OCIFormatTDouble
5246: Name
5247: OCIFormat Package double Type
5248: Purpose
5249: Return the type value for the double type.
5250: Syntax
5251: sword OCIFormatTDouble(void);
5252: Comments
5253: None
5254: Parameters
5255: None
5256: Related Functions
5257: None
5258:
5259:
5260: OCIFormatDvoid
5261: Name
5262: OCIFormat Package dvoid Type
5263: Purpose
5264: Return the type value for the dvoid type.
5265: Syntax
5266: sword OCIFormatTDvoid(void);
5267: Comments
5268: None
5269: Parameters
5270: None
5271: Related Functions
5272: None
5273:
5274:
5275: OCIFormatTEnd
5276: Name
5277: OCIFormat Package end Type
5278: Purpose
5279: Return the list terminator's "type".
5280: Syntax
5281: sword OCIFormatTEnd(void);
5282: Comments
5283: None
5284: Parameters
5285: None
5286: Related Functions
5287: None
5288:
5289:
5290: OCISvcCtxToLda()
5291: Name
5292: OCI toggle SerVice context handle to Version 7 Lda_Def
5293: Purpose
5294: Toggles between a V8 service context handle and a V7 Lda_Def.
5295: Syntax
5296: sword OCISvcCtxToLda ( OCISvcCtx *srvhp,
5297: OCIError *errhp,
5298: Lda_Def *ldap );
5299: Comments
5300: Toggles between an Oracle8 service context handle and an Oracle7 Lda_Def.
5301: This function can only be called after a service context has been properly
5302: initialized.
5303: Once the service context has been translated to an Lda_Def, it can be used in
5304: release 7.x OCI calls (e.g., obindps(), ofen()).
5305: Note: If there are multiple service contexts which share the same server
5306: handle, only one can be in V7 mode at any time.
5307: The action of this call can be reversed by passing the resulting Lda_Def to
5308: the OCILdaToSvcCtx() function.
5309: Parameters
5310: svchp (IN/OUT) - the service context handle.
5311: errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
5312: diagnostic information in the event of an error.
5313: ldap (IN/OUT) - a Logon Data Area for V7-style OCI calls which is initialized
5314: by this call.
5315: Related Functions
5316: OCILdaToSvcCtx()
5317:
5318:
5319:
5320:
5321: OCITransCommit()
5322: Name
5323: OCI TX (transaction) CoMmit
5324: Purpose
5325: Commits the transaction associated with a specified service context.
5326: Syntax
5327: sword OCITransCommit ( OCISvcCtx *srvcp,
5328: OCIError *errhp,
5329: ub4 flags );
5330: Comments
5331: The transaction currently associated with the service context is committed. If
5332: it is a distributed transaction that the server cannot commit, this call
5333: additionally retrieves the state of the transaction from the database to be
5334: returned to the user in the error handle.
5335: If the application has defined multiple transactions, this function operates
5336: on the transaction currently associated with the service context. If the
5337: application is working with only the implicit local transaction created when
5338: database changes are made, that implicit transaction is committed.
5339: If the application is running in the object mode, then the modified or updated
5340: objects in the object cache for this transaction are also committed.
5341: The flags parameter is used for one-phase commit optimization in distributed
5342: transactions. If the transaction is non-distributed, the flags parameter is
5343: ignored, and OCI_DEFAULT can be passed as its value. OCI applications
5344: managing global transactions should pass a value of
5345: OCI_TRANS_TWOPHASE to the flags parameter for a two-phase commit. The
5346: default is one-phase commit.
5347: Under normal circumstances, OCITransCommit() returns with a status
5348: indicating that the transaction has either been committed or rolled back. With
5349: distributed transactions, it is possible that the transaction is now in-doubt
5350: (i.e., neither committed nor aborted). In this case, OCITransCommit()
5351: attempts to retrieve the status of the transaction from the server.
5352: The status is returned.
5353: Parameters
5354: srvcp (IN) - the service context handle.
5355: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
5356: diagnostic information in the event of an error.
5357: flags -see the "Comments" section above.
5358: Related Functions
5359: OCITransRollback()
5360:
5361:
5362:
5363:
5364: OCITransDetach()
5365: Name
5366: OCI TX (transaction) DeTach
5367: Purpose
5368: Detaches a transaction.
5369: Syntax
5370: sword OCITransDetach ( OCISvcCtx *srvcp,
5371: OCIError *errhp,
5372: ub4 flags);
5373: Comments
5374: Detaches a global transaction from the service context handle. The transaction
5375: currently attached to the service context handle becomes inactive at the end
5376: of this call. The transaction may be resumed later by calling OCITransStart(),
5377: specifying a flags value of OCI_TRANS_RESUME.
5378: When a transaction is detached, the value which was specified in the timeout
5379: parameter of OCITransStart() when the transaction was started is used to
5380: determine the amount of time the branch can remain inactive before being
5381: deleted by the server's PMON process.
5382: Note: The transaction can be resumed by a different process than the one
5383: that detached it, provided that the transaction has the same
5384: authorization.
5385: Parameters
5386: srvcp (IN) - the service context handle.
5387: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
5388: diagnostic information in the event of an error.
5389: flags (IN) - you must pass a value of OCI_DEFAULT for this parameter.
5390: Related Functions
5391: OCITransStart()
5392:
5393:
5394:
5395: OCITransForget()
5396: Name
5397: OCI TX (transaction) ForGeT
5398: Purpose
5399: Causes the server to forget a heuristically completed global transaction.
5400: Syntax
5401: sword OCITransForget ( OCISvcCtx *svchp,
5402: OCIError *errhp,
5403: ub4 flags);
5404:
5405: Comments
5406:
5407: Forgets a heuristically completed global transaction. The server deletes the
5408: status of the transaction from the system's pending transaction table.
5409: The XID of the transaction to be forgotten is set as an attribute of the
5410: transaction handle (OCI_ATTR_XID).
5411: Parameters
5412: srvcp (IN) - the service context handle - the transaction is rolled back.
5413: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
5414: diagnostic information in the event of an error.
5415: flags (IN) - you must pass OCI_DEFAULT for this parameter.
5416: Related Functions
5417: OCITransCommit(), OCITransRollback()
5418:
5419:
5420: OCITransMultiPrepare()
5421: Name
5422: OCI Trans(action) Multi-Branch Prepare
5423: Purpose
5424: Prepares a transaction with multiple branches in a single call.
5425: Syntax
5426: sword OCITransMultiPrepare ( OCISvcCtx *svchp,
5427: ub4 numBranches,
5428: OCITrans **txns,
5429: OCIError **errhp);
5430:
5431: Comments
5432:
5433: Prepares the specified global transaction for commit.
5434: This call is valid only for distributed transactions.
5435: This call is an advanced performance feature intended for use only in
5436: situations where the caller is responsible for preparing all the branches
5437: in a transaction.
5438: Parameters
5439: srvcp (IN) - the service context handle.
5440: numBranches (IN) - This is the number of branches expected. It is also the
5441: array size for the next two parameters.
5442: txns (IN) - This is the array of transaction handles for the branches to
5443: prepare. They should all have the OCI_ATTR_XID set. The global transaction
5444: ID should be the same.
5445: errhp (IN) - This is the array of error handles. If OCI_SUCCESS is not
5446: returned, then these will indicate which branches received which errors.
5447: Related Functions
5448: OCITransPrepare()
5449:
5450:
5451: OCITransPrepare()
5452: Name
5453: OCI TX (transaction) PREpare
5454: Purpose
5455: Prepares a transaction for commit.
5456: Syntax
5457: sword OCITransPrepare ( OCISvcCtx *svchp,
5458: OCIError *errhp,
5459: ub4 flags);
5460:
5461: Comments
5462:
5463: Prepares the specified global transaction for commit.
5464: This call is valid only for distributed transactions.
5465: The call returns OCI_SUCCESS_WITH_INFO if the transaction has not made
5466: any changes. The error handle will indicate that the transaction is read-only.
5467: The flag parameter is not currently used.
5468: Parameters
5469: srvcp (IN) - the service context handle.
5470: errhp (IN) - an error handle which can be passed to OCIErrorGet() for
5471: diagnostic information in the event of an error.
5472: flags (IN) - you must pass OCI_DEFAULT for this parameter.
5473: Related Functions
5474: OCITransCommit(), OCITransForget()
5475:
5476:
5477:
5478:
5479: OCITransRollback()
5480: Name
5481: OCI TX (transaction) RoLlback
5482: Purpose
5483: Rolls back the current transaction.
5484: Syntax
5485: sword OCITransRollback ( dvoid *svchp,
5486: OCIError *errhp,
5487: ub4 flags );
5488: Comments
5489: The current transaction- defined as the set of statements executed since the
5490: last OCITransCommit() or since OCISessionBegin()-is rolled back.
5491: If the application is running under object mode then the modified or updated
5492: objects in the object cache for this transaction are also rolled back.
5493: An error is returned if an attempt is made to roll back a global transaction
5494: that is not currently active.
5495: Parameters
5496: svchp (IN) - a service context handle. The transaction currently set in the
5497: service context handle is rolled back.
5498: errhp -(IN) - an error handle which can be passed to OCIErrorGet() for
5499: diagnostic information in the event of an error.
5500: flags - you must pass a value of OCI_DEFAULT for this parameter.
5501: Related Functions
5502: OCITransCommit()
5503:
5504:
5505:
5506:
5507: OCITransStart()
5508: Name
5509: OCI TX (transaction) STart
5510: Purpose
5511: Sets the beginning of a transaction.
5512: Syntax
5513: sword OCITransStart ( OCISvcCtx *svchp,
5514: OCIError *errhp,
5515: uword timeout,
5516: ub4 flags);
5517:
5518: Comments
5519: This function sets the beginning of a global or serializable transaction. The
5520: transaction context currently associated with the service context handle is
5521: initialized at the end of the call if the flags parameter specifies that a new
5522: transaction should be started.
5523: The XID of the transaction is set as an attribute of the transaction handle
5524: (OCI_ATTR_XID)
5525: Parameters
5526: svchp (IN/OUT) - the service context handle. The transaction context in the
5527: service context handle is initialized at the end of the call if the flag
5528: specified a new transaction to be started.
5529: errhp (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
5530: err and this function returns OCI_ERROR. Diagnostic information can be
5531: obtained by calling OCIErrorGet().
5532: timeout (IN) - the time, in seconds, to wait for a transaction to become
5533: available for resumption when OCI_TRANS_RESUME is specified. When
5534: OCI_TRANS_NEW is specified, this value is stored and may be used later by
5535: OCITransDetach().
5536: flags (IN) - specifies whether a new transaction is being started or an
5537: existing transaction is being resumed. Also specifies serializiability or
5538: read-only status. More than a single value can be specified. By default,
5539: a read/write transaction is started. The flag values are:
5540: OCI_TRANS_NEW - starts a new transaction branch. By default starts a
5541: tightly coupled and migratable branch.
5542: OCI_TRANS_TIGHT - explicitly specifies a tightly coupled branch
5543: OCI_TRANS_LOOSE - specifies a loosely coupled branch
5544: OCI_TRANS_RESUME - resumes an existing transaction branch.
5545: OCI_TRANS_READONLY - start a readonly transaction
5546: OCI_TRANS_SERIALIZABLE - start a serializable transaction
5547: Related Functions
5548: OCITransDetach()
5549:
5550:
5551:
5552:
5553:
5554: ******************************************************************************/
5555: /*-----------------------Dynamic Callback Function Pointers------------------*/
5556:
5557:
5558: typedef sb4 (*OCICallbackInBind)(dvoid *ictxp, OCIBind *bindp, ub4 iter,
5559: ub4 index, dvoid **bufpp, ub4 *alenp,
5560: ub1 *piecep, dvoid **indp);
5561:
5562: typedef sb4 (*OCICallbackOutBind)(dvoid *octxp, OCIBind *bindp, ub4 iter,
5563: ub4 index, dvoid **bufpp, ub4 **alenp,
5564: ub1 *piecep, dvoid **indp,
5565: ub2 **rcodep);
5566:
5567: typedef sb4 (*OCICallbackDefine)(dvoid *octxp, OCIDefine *defnp, ub4 iter,
5568: dvoid **bufpp, ub4 **alenp, ub1 *piecep,
5569: dvoid **indp, ub2 **rcodep);
5570:
5571: typedef sword (*OCIUserCallback)(dvoid *ctxp, dvoid *hndlp, ub4 type,
5572: ub4 fcode, ub4 when, sword returnCode,
5573: sb4 *errnop, va_list arglist);
5574:
5575: typedef sword (*OCIEnvCallbackType)(OCIEnv *env, ub4 mode,
5576: size_t xtramem_sz, dvoid *usrmemp,
5577: OCIUcb *ucbDesc);
5578:
5579: typedef sb4 (*OCICallbackLobRead)(dvoid *ctxp, CONST dvoid *bufp,
5580: ub4 len, ub1 piece);
5581:
5582: typedef sb4 (*OCICallbackLobWrite)(dvoid *ctxp, dvoid *bufp,
5583: ub4 *lenp, ub1 *piece);
5584:
5585: /*--------------------------Failover Callback Structure ---------------------*/
5586: typedef sb4 (*OCICallbackFailover)(dvoid *svcctx, dvoid *envctx,
5587: dvoid *fo_ctx, ub4 fo_type,
5588: ub4 fo_event);
5589:
5590: typedef struct
5591: {
5592: OCICallbackFailover callback_function;
5593: dvoid *fo_ctx;
5594: }
5595: OCIFocbkStruct;
5596:
5597: /*****************************************************************************
5598: ACTUAL PROTOTYPE DECLARATIONS
5599: ******************************************************************************/
5600:
5601: sword OCIInitialize (ub4 mode, dvoid *ctxp,
5602: dvoid *(*malocfp)(dvoid *ctxp, size_t size),
5603: dvoid *(*ralocfp)(dvoid *ctxp, dvoid *memptr, size_t newsize),
5604: void (*mfreefp)(dvoid *ctxp, dvoid *memptr) );
5605:
5606: sword OCITerminate( ub4 mode);
5607:
5608: sword OCIEnvCreate (OCIEnv **envp, ub4 mode, dvoid *ctxp,
5609: dvoid *(*malocfp)(dvoid *ctxp, size_t size),
5610: dvoid *(*ralocfp)(dvoid *ctxp, dvoid *memptr, size_t newsize),
5611: void (*mfreefp)(dvoid *ctxp, dvoid *memptr),
5612: size_t xtramem_sz, dvoid **usrmempp);
5613:
5614: sword OCIFEnvCreate (OCIEnv **envp, ub4 mode, dvoid *ctxp,
5615: dvoid *(*malocfp)(dvoid *ctxp, size_t size),
5616: dvoid *(*ralocfp)(dvoid *ctxp, dvoid *memptr, size_t newsize),
5617: void (*mfreefp)(dvoid *ctxp, dvoid *memptr),
5618: size_t xtramem_sz, dvoid **usrmempp, dvoid *fupg);
5619:
5620: sword OCIHandleAlloc(CONST dvoid *parenth, dvoid **hndlpp, CONST ub4 type,
5621: CONST size_t xtramem_sz, dvoid **usrmempp);
5622:
5623: sword OCIHandleFree(dvoid *hndlp, CONST ub4 type);
5624:
5625:
5626: sword OCIDescriptorAlloc(CONST dvoid *parenth, dvoid **descpp,
5627: CONST ub4 type, CONST size_t xtramem_sz,
5628: dvoid **usrmempp);
5629:
5630: sword OCIDescriptorFree(dvoid *descp, CONST ub4 type);
5631:
5632: sword OCIEnvInit (OCIEnv **envp, ub4 mode,
5633: size_t xtramem_sz, dvoid **usrmempp);
5634:
5635: sword OCIServerAttach (OCIServer *srvhp, OCIError *errhp,
5636: CONST OraText *dblink, sb4 dblink_len, ub4 mode);
5637:
5638: sword OCIServerDetach (OCIServer *srvhp, OCIError *errhp, ub4 mode);
5639:
5640: sword OCISessionBegin (OCISvcCtx *svchp, OCIError *errhp, OCISession *usrhp,
5641: ub4 credt, ub4 mode);
5642:
5643: sword OCISessionEnd (OCISvcCtx *svchp, OCIError *errhp, OCISession *usrhp,
5644: ub4 mode);
5645:
5646: sword OCILogon (OCIEnv *envhp, OCIError *errhp, OCISvcCtx **svchp,
5647: CONST OraText *username, ub4 uname_len,
5648: CONST OraText *password, ub4 passwd_len,
5649: CONST OraText *dbname, ub4 dbname_len);
5650:
5651: sword OCILogoff (OCISvcCtx *svchp, OCIError *errhp);
5652:
5653:
5654: sword OCIPasswordChange (OCISvcCtx *svchp, OCIError *errhp,
5655: CONST OraText *user_name, ub4 usernm_len,
5656: CONST OraText *opasswd, ub4 opasswd_len,
5657: CONST OraText *npasswd, ub4 npasswd_len, ub4 mode);
5658:
5659: sword OCIStmtPrepare (OCIStmt *stmtp, OCIError *errhp, CONST OraText *stmt,
5660: ub4 stmt_len, ub4 language, ub4 mode);
5661:
5662: sword OCIBindByPos (OCIStmt *stmtp, OCIBind **bindp, OCIError *errhp,
5663: ub4 position, dvoid *valuep, sb4 value_sz,
5664: ub2 dty, dvoid *indp, ub2 *alenp, ub2 *rcodep,
5665: ub4 maxarr_len, ub4 *curelep, ub4 mode);
5666:
5667: sword OCIBindByName (OCIStmt *stmtp, OCIBind **bindp, OCIError *errhp,
5668: CONST OraText *placeholder, sb4 placeh_len,
5669: dvoid *valuep, sb4 value_sz, ub2 dty,
5670: dvoid *indp, ub2 *alenp, ub2 *rcodep,
5671: ub4 maxarr_len, ub4 *curelep, ub4 mode);
5672:
5673: sword OCIBindObject (OCIBind *bindp, OCIError *errhp, CONST OCIType *type,
5674: dvoid **pgvpp, ub4 *pvszsp, dvoid **indpp,
5675: ub4 *indszp);
5676:
5677: sword OCIBindDynamic (OCIBind *bindp, OCIError *errhp, dvoid *ictxp,
5678: OCICallbackInBind icbfp, dvoid *octxp,
5679: OCICallbackOutBind ocbfp);
5680:
5681: sword OCIBindArrayOfStruct (OCIBind *bindp, OCIError *errhp,
5682: ub4 pvskip, ub4 indskip,
5683: ub4 alskip, ub4 rcskip);
5684:
5685: sword OCIStmtGetPieceInfo (OCIStmt *stmtp, OCIError *errhp,
5686: dvoid **hndlpp, ub4 *typep,
5687: ub1 *in_outp, ub4 *iterp, ub4 *idxp,
5688: ub1 *piecep);
5689:
5690: sword OCIStmtSetPieceInfo (dvoid *hndlp, ub4 type, OCIError *errhp,
5691: CONST dvoid *bufp, ub4 *alenp, ub1 piece,
5692: CONST dvoid *indp, ub2 *rcodep);
5693:
5694: sword OCIStmtExecute (OCISvcCtx *svchp, OCIStmt *stmtp, OCIError *errhp,
5695: ub4 iters, ub4 rowoff, CONST OCISnapshot *snap_in,
5696: OCISnapshot *snap_out, ub4 mode);
5697:
5698: sword OCIDefineByPos (OCIStmt *stmtp, OCIDefine **defnp, OCIError *errhp,
5699: ub4 position, dvoid *valuep, sb4 value_sz, ub2 dty,
5700: dvoid *indp, ub2 *rlenp, ub2 *rcodep, ub4 mode);
5701:
5702: sword OCIDefineObject (OCIDefine *defnp, OCIError *errhp,
5703: CONST OCIType *type, dvoid **pgvpp,
5704: ub4 *pvszsp, dvoid **indpp, ub4 *indszp);
5705:
5706: sword OCIDefineDynamic (OCIDefine *defnp, OCIError *errhp, dvoid *octxp,
5707: OCICallbackDefine ocbfp);
5708:
5709: sword OCIDefineArrayOfStruct (OCIDefine *defnp, OCIError *errhp, ub4 pvskip,
5710: ub4 indskip, ub4 rlskip, ub4 rcskip);
5711:
5712: sword OCIStmtFetch (OCIStmt *stmtp, OCIError *errhp, ub4 nrows,
5713: ub2 orientation, ub4 mode);
5714:
5715: sword OCIStmtGetBindInfo (OCIStmt *stmtp, OCIError *errhp, ub4 size,
5716: ub4 startloc,
5717: sb4 *found, OraText *bvnp[], ub1 bvnl[],
5718: OraText *invp[], ub1 inpl[], ub1 dupl[],
5719: OCIBind *hndl[]);
5720:
5721: sword OCIDescribeAny (OCISvcCtx *svchp, OCIError *errhp,
5722: dvoid *objptr,
5723: ub4 objnm_len, ub1 objptr_typ, ub1 info_level,
5724: ub1 objtyp, OCIDescribe *dschp);
5725:
5726: sword OCIParamGet (CONST dvoid *hndlp, ub4 htype, OCIError *errhp,
5727: dvoid **parmdpp, ub4 pos);
5728:
5729: sword OCIParamSet(dvoid *hdlp, ub4 htyp, OCIError *errhp, CONST dvoid *dscp,
5730: ub4 dtyp, ub4 pos);
5731:
5732: sword OCITransStart (OCISvcCtx *svchp, OCIError *errhp,
5733: uword timeout, ub4 flags );
5734:
5735: sword OCITransDetach (OCISvcCtx *svchp, OCIError *errhp, ub4 flags );
5736:
5737: sword OCITransCommit (OCISvcCtx *svchp, OCIError *errhp, ub4 flags);
5738:
5739: sword OCITransRollback (OCISvcCtx *svchp, OCIError *errhp, ub4 flags);
5740:
5741: sword OCITransPrepare (OCISvcCtx *svchp, OCIError *errhp, ub4 flags);
5742:
5743: sword OCITransMultiPrepare (OCISvcCtx *svchp, ub4 numBranches,
5744: OCITrans **txns, OCIError **errhp);
5745:
5746: sword OCITransForget (OCISvcCtx *svchp, OCIError *errhp, ub4 flags);
5747:
5748: sword OCIErrorGet (dvoid *hndlp, ub4 recordno, OraText *sqlstate,
5749: sb4 *errcodep, OraText *bufp, ub4 bufsiz, ub4 type);
5750:
5751: sword OCILobAppend (OCISvcCtx *svchp, OCIError *errhp,
5752: OCILobLocator *dst_locp,
5753: OCILobLocator *src_locp);
5754:
5755: sword OCILobAssign (OCIEnv *envhp, OCIError *errhp,
5756: CONST OCILobLocator *src_locp,
5757: OCILobLocator **dst_locpp);
5758:
5759: sword OCILobCharSetForm (OCIEnv *envhp, OCIError *errhp,
5760: CONST OCILobLocator *locp, ub1 *csfrm);
5761:
5762: sword OCILobCharSetId (OCIEnv *envhp, OCIError *errhp,
5763: CONST OCILobLocator *locp, ub2 *csid);
5764:
5765: sword OCILobCopy (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *dst_locp,
5766: OCILobLocator *src_locp, ub4 amount, ub4 dst_offset,
5767: ub4 src_offset);
5768:
5769: sword OCILobCreateTemporary(OCISvcCtx *svchp,
5770: OCIError *errhp,
5771: OCILobLocator *locp,
5772: ub2 csid,
5773: ub1 csfrm,
5774: ub1 lobtype,
5775: boolean cache,
5776: OCIDuration duration);
5777:
5778:
5779: sword OCILobClose( OCISvcCtx *svchp,
5780: OCIError *errhp,
5781: OCILobLocator *locp );
5782:
5783:
5784: sword OCILobDisableBuffering (OCISvcCtx *svchp,
5785: OCIError *errhp,
5786: OCILobLocator *locp);
5787:
5788: sword OCILobEnableBuffering (OCISvcCtx *svchp,
5789: OCIError *errhp,
5790: OCILobLocator *locp);
5791:
5792: sword OCILobErase (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
5793: ub4 *amount, ub4 offset);
5794:
5795: sword OCILobFileClose (OCISvcCtx *svchp, OCIError *errhp,
5796: OCILobLocator *filep);
5797:
5798: sword OCILobFileCloseAll (OCISvcCtx *svchp, OCIError *errhp);
5799:
5800: sword OCILobFileExists (OCISvcCtx *svchp, OCIError *errhp,
5801: OCILobLocator *filep,
5802: boolean *flag);
5803:
5804: sword OCILobFileGetName (OCIEnv *envhp, OCIError *errhp,
5805: CONST OCILobLocator *filep,
5806: OraText *dir_alias, ub2 *d_length,
5807: OraText *filename, ub2 *f_length);
5808:
5809: sword OCILobFileIsOpen (OCISvcCtx *svchp, OCIError *errhp,
5810: OCILobLocator *filep,
5811: boolean *flag);
5812:
5813: sword OCILobFileOpen (OCISvcCtx *svchp, OCIError *errhp,
5814: OCILobLocator *filep,
5815: ub1 mode);
5816:
5817: sword OCILobFileSetName (OCIEnv *envhp, OCIError *errhp,
5818: OCILobLocator **filepp,
5819: CONST OraText *dir_alias, ub2 d_length,
5820: CONST OraText *filename, ub2 f_length);
5821:
5822: sword OCILobFlushBuffer (OCISvcCtx *svchp,
5823: OCIError *errhp,
5824: OCILobLocator *locp,
5825: ub4 flag);
5826:
5827: sword OCILobFreeTemporary(OCISvcCtx *svchp,
5828: OCIError *errhp,
5829: OCILobLocator *locp);
5830:
5831: sword OCILobGetChunkSize(OCISvcCtx *svchp,
5832: OCIError *errhp,
5833: OCILobLocator *locp,
5834: ub4 *chunksizep);
5835:
5836: sword OCILobGetLength (OCISvcCtx *svchp, OCIError *errhp,
5837: OCILobLocator *locp,
5838: ub4 *lenp);
5839:
5840: sword OCILobIsEqual (OCIEnv *envhp, CONST OCILobLocator *x,
5841: CONST OCILobLocator *y,
5842: boolean *is_equal);
5843:
5844: sword OCILobIsOpen( OCISvcCtx *svchp,
5845: OCIError *errhp,
5846: OCILobLocator *locp,
5847: boolean *flag);
5848:
5849: sword OCILobIsTemporary(OCIEnv *envp,
5850: OCIError *errhp,
5851: OCILobLocator *locp,
5852: boolean *is_temporary);
5853:
5854: sword OCILobLoadFromFile (OCISvcCtx *svchp, OCIError *errhp,
5855: OCILobLocator *dst_locp,
5856: OCILobLocator *src_filep,
5857: ub4 amount, ub4 dst_offset,
5858: ub4 src_offset);
5859:
5860: sword OCILobLocatorAssign (OCISvcCtx *svchp, OCIError *errhp,
5861: CONST OCILobLocator *src_locp,
5862: OCILobLocator **dst_locpp);
5863:
5864:
5865: sword OCILobLocatorIsInit (OCIEnv *envhp, OCIError *errhp,
5866: CONST OCILobLocator *locp,
5867: boolean *is_initialized);
5868:
5869: sword OCILobOpen( OCISvcCtx *svchp,
5870: OCIError *errhp,
5871: OCILobLocator *locp,
5872: ub1 mode );
5873:
5874: sword OCILobRead (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
5875: ub4 *amtp, ub4 offset, dvoid *bufp, ub4 bufl,
5876: dvoid *ctxp, sb4 (*cbfp)(dvoid *ctxp,
5877: CONST dvoid *bufp,
5878: ub4 len,
5879: ub1 piece),
5880: ub2 csid, ub1 csfrm);
5881:
5882: sword OCILobTrim (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
5883: ub4 newlen);
5884:
5885: sword OCILobWrite (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
5886: ub4 *amtp, ub4 offset, dvoid *bufp, ub4 buflen,
5887: ub1 piece, dvoid *ctxp,
5888: sb4 (*cbfp)(dvoid *ctxp,
5889: dvoid *bufp,
5890: ub4 *len,
5891: ub1 *piece),
5892: ub2 csid, ub1 csfrm);
5893:
5894: sword OCILobWriteAppend(OCISvcCtx *svchp, OCIError *errhp,
5895: OCILobLocator *lobp, ub4 *amtp,
5896: dvoid *bufp, ub4 bufl, ub1 piece, dvoid *ctxp,
5897: sb4 (*cbfp)(dvoid *ctxp, dvoid *bufp, ub4 *len,
5898: ub1 *piece),
5899: ub2 csid, ub1 csfrm);
5900:
5901: sword OCIBreak (dvoid *hndlp, OCIError *errhp);
5902:
5903: sword OCIReset (dvoid *hndlp, OCIError *errhp);
5904:
5905: sword OCIServerVersion (dvoid *hndlp, OCIError *errhp, OraText *bufp,
5906: ub4 bufsz,
5907: ub1 hndltype);
5908:
5909:
5910: sword OCIAttrGet (CONST dvoid *trgthndlp, ub4 trghndltyp,
5911: dvoid *attributep, ub4 *sizep, ub4 attrtype,
5912: OCIError *errhp);
5913:
5914: sword OCIAttrSet (dvoid *trgthndlp, ub4 trghndltyp, dvoid *attributep,
5915: ub4 size, ub4 attrtype, OCIError *errhp);
5916:
5917: sword OCISvcCtxToLda (OCISvcCtx *svchp, OCIError *errhp, Lda_Def *ldap);
5918:
5919: sword OCILdaToSvcCtx (OCISvcCtx **svchpp, OCIError *errhp, Lda_Def *ldap);
5920:
5921: sword OCIResultSetToStmt (OCIResult *rsetdp, OCIError *errhp);
5922:
5923: sword OCIFileClose ( dvoid *hndl, OCIError *err, OCIFileObject *filep );
5924:
5925: sword OCIUserCallbackRegister(dvoid *hndlp, ub4 type, dvoid *ehndlp,
5926: OCIUserCallback callback, dvoid *ctxp,
5927: ub4 fcode, ub4 when, OCIUcb *ucbDesc);
5928:
5929: sword OCIUserCallbackGet(dvoid *hndlp, ub4 type, dvoid *ehndlp,
5930: ub4 fcode, ub4 when, OCIUserCallback *callbackp,
5931: dvoid **ctxpp, OCIUcb *ucbDesc);
5932:
5933: sword OCISharedLibInit(dvoid *metaCtx, dvoid *libCtx, ub4 argfmt, sword argc,
5934: dvoid *argv[], OCIEnvCallbackType envCallback);
5935:
5936: sword OCIFileExists ( dvoid *hndl, OCIError *err, OraText *filename,
5937: OraText *path, ub1 *flag );
5938:
5939: sword OCIFileFlush( dvoid *hndl, OCIError *err, OCIFileObject *filep );
5940:
5941:
5942: sword OCIFileGetLength( dvoid *hndl, OCIError *err, OraText *filename,
5943: OraText *path, ubig_ora *lenp );
5944:
5945: sword OCIFileInit ( dvoid *hndl, OCIError *err );
5946:
5947: sword OCIFileOpen ( dvoid *hndl, OCIError *err, OCIFileObject **filep,
5948: OraText *filename, OraText *path, ub4 mode, ub4 create,
5949: ub4 type );
5950:
5951: sword OCIFileRead ( dvoid *hndl, OCIError *err, OCIFileObject *filep,
5952: dvoid *bufp, ub4 bufl, ub4 *bytesread );
5953:
5954: sword OCIFileSeek ( dvoid *hndl, OCIError *err, OCIFileObject *filep,
5955: uword origin, ubig_ora offset, sb1 dir );
5956:
5957: sword OCIFileTerm ( dvoid *hndl, OCIError *err );
5958:
5959:
5960: sword OCIFileWrite ( dvoid *hndl, OCIError *err, OCIFileObject *filep,
5961: dvoid *bufp, ub4 buflen, ub4 *byteswritten );
5962:
5963:
5964: /*
5965: ** Initialize the security package
5966: */
5967: sword OCISecurityInitialize (OCISecurity *sechandle, OCIError *error_handle);
5968:
5969: sword OCISecurityTerminate (OCISecurity *sechandle, OCIError *error_handle);
5970:
5971: sword OCISecurityOpenWallet(OCISecurity *osshandle,
5972: OCIError *error_handle,
5973: size_t wrllen,
5974: OraText *wallet_resource_locator,
5975: size_t pwdlen,
5976: OraText *password,
5977: nzttWallet *wallet);
5978:
5979: sword OCISecurityCloseWallet(OCISecurity *osshandle,
5980: OCIError *error_handle,
5981: nzttWallet *wallet);
5982:
5983: sword OCISecurityCreateWallet(OCISecurity *osshandle,
5984: OCIError *error_handle,
5985: size_t wrllen,
5986: OraText *wallet_resource_locator,
5987: size_t pwdlen,
5988: OraText *password,
5989: nzttWallet *wallet);
5990:
5991: sword OCISecurityDestroyWallet(OCISecurity *osshandle,
5992: OCIError *error_handle,
5993: size_t wrllen,
5994: OraText *wallet_resource_locator,
5995: size_t pwdlen,
5996: OraText *password);
5997:
5998: sword OCISecurityStorePersona(OCISecurity *osshandle,
5999: OCIError *error_handle,
6000: nzttPersona **persona,
6001: nzttWallet *wallet);
6002:
6003: sword OCISecurityOpenPersona(OCISecurity *osshandle,
6004: OCIError *error_handle,
6005: nzttPersona *persona);
6006:
6007: sword OCISecurityClosePersona(OCISecurity *osshandle,
6008: OCIError *error_handle,
6009: nzttPersona *persona);
6010:
6011: sword OCISecurityRemovePersona(OCISecurity *osshandle,
6012: OCIError *error_handle,
6013: nzttPersona **persona);
6014:
6015: sword OCISecurityCreatePersona(OCISecurity *osshandle,
6016: OCIError *error_handle,
6017: nzttIdentType identity_type,
6018: nzttCipherType cipher_type,
6019: nzttPersonaDesc *desc,
6020: nzttPersona **persona);
6021:
6022: sword OCISecuritySetProtection(OCISecurity *osshandle,
6023: OCIError *error_handle,
6024: nzttPersona *persona,
6025: nzttcef crypto_engine_function,
6026: nztttdufmt data_unit_format,
6027: nzttProtInfo *protection_info);
6028:
6029: sword OCISecurityGetProtection(OCISecurity *osshandle,
6030: OCIError *error_handle,
6031: nzttPersona *persona,
6032: nzttcef crypto_engine_function,
6033: nztttdufmt * data_unit_format_ptr,
6034: nzttProtInfo *protection_info);
6035:
6036: sword OCISecurityRemoveIdentity(OCISecurity *osshandle,
6037: OCIError *error_handle,
6038: nzttIdentity **identity_ptr);
6039:
6040: sword OCISecurityCreateIdentity(OCISecurity *osshandle,
6041: OCIError *error_handle,
6042: nzttIdentType type,
6043: nzttIdentityDesc *desc,
6044: nzttIdentity **identity_ptr);
6045:
6046: sword OCISecurityAbortIdentity(OCISecurity *osshandle,
6047: OCIError *error_handle,
6048: nzttIdentity **identity_ptr);
6049:
6050: sword OCISecurityFreeIdentity(OCISecurity *osshandle,
6051: OCIError *error_handle,
6052: nzttIdentity **identity_ptr);
6053:
6054:
6055: sword OCISecurityStoreTrustedIdentity(OCISecurity *osshandle,
6056: OCIError *error_handle,
6057: nzttIdentity **identity_ptr,
6058: nzttPersona *persona);
6059:
6060: sword OCISecuritySign(OCISecurity *osshandle,
6061: OCIError *error_handle,
6062: nzttPersona *persona,
6063: nzttces signature_state,
6064: size_t input_length,
6065: ub1 *input,
6066: nzttBufferBlock *buffer_block);
6067:
6068: sword OCISecuritySignExpansion(OCISecurity *osshandle,
6069: OCIError *error_handle,
6070: nzttPersona *persona,
6071: size_t inputlen,
6072: size_t *signature_length);
6073:
6074: sword OCISecurityVerify(OCISecurity *osshandle,
6075: OCIError *error_handle,
6076: nzttPersona *persona,
6077: nzttces signature_state,
6078: size_t siglen,
6079: ub1 *signature,
6080: nzttBufferBlock *extracted_message,
6081: boolean *verified,
6082: boolean *validated,
6083: nzttIdentity **signing_party_identity);
6084:
6085: sword OCISecurityValidate(OCISecurity *osshandle,
6086: OCIError *error_handle,
6087: nzttPersona *persona,
6088: nzttIdentity *identity,
6089: boolean *validated);
6090:
6091: sword OCISecuritySignDetached(OCISecurity *osshandle,
6092: OCIError *error_handle,
6093: nzttPersona *persona,
6094: nzttces signature_state,
6095: size_t input_length,
6096: ub1 * input,
6097: nzttBufferBlock *signature);
6098:
6099: sword OCISecuritySignDetExpansion(OCISecurity *osshandle,
6100: OCIError *error_handle,
6101: nzttPersona *persona,
6102: size_t input_length,
6103: size_t *required_buffer_length);
6104:
6105: sword OCISecurityVerifyDetached(OCISecurity *osshandle,
6106: OCIError *error_handle,
6107: nzttPersona *persona,
6108: nzttces signature_state,
6109: size_t data_length,
6110: ub1 *data,
6111: size_t siglen,
6112: ub1 *signature,
6113: boolean *verified,
6114: boolean *validated,
6115: nzttIdentity **signing_party_identity);
6116:
6117: sword OCISecurity_PKEncrypt(OCISecurity *osshandle,
6118: OCIError *error_handle,
6119: nzttPersona *persona,
6120: size_t number_of_recipients,
6121: nzttIdentity *recipient_list,
6122: nzttces encryption_state,
6123: size_t input_length,
6124: ub1 *input,
6125: nzttBufferBlock *encrypted_data);
6126:
6127: sword OCISecurityPKEncryptExpansion(OCISecurity *osshandle,
6128: OCIError *error_handle,
6129: nzttPersona *persona,
6130: size_t number_recipients,
6131: size_t input_length,
6132: size_t *buffer_length_required);
6133:
6134: sword OCISecurityPKDecrypt(OCISecurity *osshandle,
6135: OCIError *error_handle,
6136: nzttPersona *persona,
6137: nzttces encryption_state,
6138: size_t input_length,
6139: ub1 *input,
6140: nzttBufferBlock *encrypted_data);
6141:
6142: sword OCISecurityEncrypt(OCISecurity *osshandle,
6143: OCIError *error_handle,
6144: nzttPersona *persona,
6145: nzttces encryption_state,
6146: size_t input_length,
6147: ub1 *input,
6148: nzttBufferBlock *encrypted_data);
6149:
6150: sword OCISecurityEncryptExpansion(OCISecurity *osshandle,
6151: OCIError *error_handle,
6152: nzttPersona *persona,
6153: size_t input_length,
6154: size_t *encrypted_data_length);
6155:
6156: sword OCISecurityDecrypt(OCISecurity *osshandle,
6157: OCIError *error_handle,
6158: nzttPersona *persona,
6159: nzttces decryption_state,
6160: size_t input_length,
6161: ub1 *input,
6162: nzttBufferBlock *decrypted_data);
6163:
6164: sword OCISecurityEnvelope(OCISecurity *osshandle,
6165: OCIError *error_handle,
6166: nzttPersona *persona,
6167: size_t number_of_recipients,
6168: nzttIdentity *identity,
6169: nzttces encryption_state,
6170: size_t input_length,
6171: ub1 *input,
6172: nzttBufferBlock *enveloped_data);
6173:
6174: sword OCISecurityDeEnvelope(OCISecurity *osshandle,
6175: OCIError *error_handle,
6176: nzttPersona *persona,
6177: nzttces decryption_state,
6178: size_t input_length,
6179: ub1 *input,
6180: nzttBufferBlock *output_message,
6181: boolean *verified,
6182: boolean *validated,
6183: nzttIdentity **sender_identity);
6184:
6185: sword OCISecurityKeyedHash(OCISecurity *osshandle,
6186: OCIError *error_handle,
6187: nzttPersona *persona,
6188: nzttces hash_state,
6189: size_t input_length,
6190: ub1 *input,
6191: nzttBufferBlock *keyed_hash);
6192:
6193: sword OCISecurityKeyedHashExpansion(OCISecurity *osshandle,
6194: OCIError *error_handle,
6195: nzttPersona *persona,
6196: size_t input_length,
6197: size_t *required_buffer_length);
6198:
6199: sword OCISecurityHash(OCISecurity *osshandle,
6200: OCIError *error_handle,
6201: nzttPersona *persona,
6202: nzttces hash_state,
6203: size_t input,
6204: ub1 *input_length,
6205: nzttBufferBlock *hash);
6206:
6207: sword OCISecurityHashExpansion(OCISecurity *osshandle,
6208: OCIError *error_handle,
6209: nzttPersona *persona,
6210: size_t input_length,
6211: size_t *required_buffer_length);
6212:
6213: sword OCISecuritySeedRandom(OCISecurity *osshandle,
6214: OCIError *error_handle,
6215: nzttPersona *persona,
6216: size_t seed_length,
6217: ub1 *seed);
6218:
6219: sword OCISecurityRandomBytes(OCISecurity *osshandle,
6220: OCIError *error_handle,
6221: nzttPersona *persona,
6222: size_t number_of_bytes_desired,
6223: nzttBufferBlock *random_bytes);
6224:
6225: sword OCISecurityRandomNumber(OCISecurity *osshandle,
6226: OCIError *error_handle,
6227: nzttPersona *persona,
6228: uword *random_number_ptr);
6229:
6230: sword OCISecurityInitBlock(OCISecurity *osshandle,
6231: OCIError *error_handle,
6232: nzttBufferBlock *buffer_block);
6233:
6234: sword OCISecurityReuseBlock(OCISecurity *osshandle,
6235: OCIError *error_handle,
6236: nzttBufferBlock *buffer_block);
6237:
6238: sword OCISecurityPurgeBlock(OCISecurity *osshandle,
6239: OCIError *error_handle,
6240: nzttBufferBlock *buffer_block);
6241:
6242: sword OCISecuritySetBlock(OCISecurity *osshandle,
6243: OCIError *error_handle,
6244: uword flags_to_set,
6245: size_t buffer_length,
6246: size_t used_buffer_length,
6247: ub1 *buffer,
6248: nzttBufferBlock *buffer_block);
6249:
6250: sword OCISecurityGetIdentity(OCISecurity *osshandle,
6251: OCIError *error_handle,
6252: size_t namelen,
6253: OraText *distinguished_name,
6254: nzttIdentity **identity);
6255:
6256: sword OCIAQEnq(OCISvcCtx *svchp, OCIError *errhp, OraText *queue_name,
6257: OCIAQEnqOptions *enqopt, OCIAQMsgProperties *msgprop,
6258: OCIType *payload_tdo, dvoid **payload, dvoid **payload_ind,
6259: OCIRaw **msgid, ub4 flags);
6260:
6261: sword OCIAQDeq(OCISvcCtx *svchp, OCIError *errhp, OraText *queue_name,
6262: OCIAQDeqOptions *deqopt, OCIAQMsgProperties *msgprop,
6263: OCIType *payload_tdo, dvoid **payload, dvoid **payload_ind,
6264: OCIRaw **msgid, ub4 flags);
6265:
6266: sword OCIAQListen(/*_ OCISvcCtx *svchp, OCIError *errhp,
6267: OCIAQAgent **agent_list, ub4 num_agents,
6268: sb4 wait, OCIAQAgent **agent,
6269: ub4 flags _*/);
6270:
6271: sword OCIExtractInit(dvoid *hndl, OCIError *err);
6272:
6273: sword OCIExtractTerm(dvoid *hndl, OCIError *err);
6274:
6275: sword OCIExtractReset(dvoid *hndl, OCIError *err);
6276:
6277: sword OCIExtractSetNumKeys(dvoid *hndl, OCIError *err, uword numkeys);
6278:
6279: sword OCIExtractSetKey(dvoid *hndl, OCIError *err, CONST OraText *name,
6280: ub1 type, ub4 flag, CONST dvoid *defval,
6281: CONST sb4 *intrange, CONST OraText *CONST *strlist);
6282:
6283: sword OCIExtractFromFile(dvoid *hndl, OCIError *err, ub4 flag,
6284: OraText *filename);
6285:
6286: sword OCIExtractFromStr(dvoid *hndl, OCIError *err, ub4 flag, OraText *input);
6287:
6288: sword OCIExtractToInt(dvoid *hndl, OCIError *err, OraText *keyname,
6289: uword valno, sb4 *retval);
6290:
6291: sword OCIExtractToBool(dvoid *hndl, OCIError *err, OraText *keyname,
6292: uword valno, ub1 *retval);
6293:
6294: sword OCIExtractToStr(dvoid *hndl, OCIError *err, OraText *keyname, uword valno,
6295: OraText *retval, uword buflen);
6296:
6297: sword OCIExtractToOCINum(dvoid *hndl, OCIError *err, OraText *keyname,
6298: uword valno, OCINumber *retval);
6299:
6300: sword OCIExtractToList(dvoid *hndl, OCIError *err, uword *numkeys);
6301:
6302: sword OCIExtractFromList(dvoid *hndl, OCIError *err, uword index,
6303: OraText **name,
6304: ub1 *type, uword *numvals, dvoid ***values);
6305:
6306: /* Memory Related Service Interfaces */
6307:
6308: sword OCIMemoryAlloc(dvoid *hdl, OCIError *err, dvoid **mem,
6309: OCIDuration dur, ub4 size, ub4 flags);
6310:
6311: sword OCIMemoryResize(dvoid *hdl, OCIError *err, dvoid **mem,
6312: ub4 newsize, ub4 flags);
6313:
6314: sword OCIMemoryFree(dvoid *hdl, OCIError *err, dvoid *mem);
6315:
6316: sword OCIContextSetValue(dvoid *hdl, OCIError *err, OCIDuration duration,
6317: ub1 *key, ub1 keylen, dvoid *ctx_value);
6318:
6319: sword OCIContextGetValue(dvoid *hdl, OCIError *err, ub1 *key,
6320: ub1 keylen, dvoid **ctx_value);
6321:
6322: sword OCIContextClearValue(dvoid *hdl, OCIError *err, ub1 *key,
6323: ub1 keylen);
6324:
6325: sword OCIContextGenerateKey(dvoid *hdl, OCIError *err, ub4 *key);
6326:
6327: sword OCIMemorySetCurrentIDs(dvoid *hdl, OCIError *err,
6328: ub4 curr_session_id, ub4 curr_trans_id, ub4 curr_stmt_id);
6329:
6330: sword OCIPicklerTdsCtxInit(OCIEnv *env, OCIError *err,
6331: OCIPicklerTdsCtx **tdsc);
6332:
6333: sword OCIPicklerTdsCtxFree(OCIEnv *env, OCIError *err, OCIPicklerTdsCtx *tdsc);
6334:
6335: sword OCIPicklerTdsInit(OCIEnv *env, OCIError *err, OCIPicklerTdsCtx *tdsc,
6336: OCIPicklerTds **tdsh);
6337:
6338: sword OCIPicklerTdsFree(OCIEnv *env, OCIError *err, OCIPicklerTds *tdsh);
6339:
6340: sword OCIPicklerTdsCreateElementNumber(OCIEnv *env, OCIError *err,
6341: OCIPicklerTds *tdsh, ub1 prec,
6342: sb1 scale, OCIPicklerTdsElement *elt);
6343:
6344: sword OCIPicklerTdsCreateElementChar(OCIEnv *env, OCIError *err,
6345: OCIPicklerTds *tdsh, ub2 len,
6346: OCIPicklerTdsElement *elt);
6347:
6348: sword OCIPicklerTdsCreateElementVarchar(OCIEnv *env, OCIError *err,
6349: OCIPicklerTds *tdsh, ub2 len,
6350: OCIPicklerTdsElement *elt);
6351:
6352: sword OCIPicklerTdsCreateElementRaw(OCIEnv *env, OCIError *err,
6353: OCIPicklerTds *tdsh, ub2 len,
6354: OCIPicklerTdsElement *elt);
6355:
6356: sword OCIPicklerTdsCreateElement(OCIEnv *env, OCIError *err,
6357: OCIPicklerTds *tdsh, OCITypeCode dty,
6358: OCIPicklerTdsElement *elt);
6359:
6360: sword OCIPicklerTdsAddAttr(OCIEnv *env, OCIError *err,
6361: OCIPicklerTds *tdsh, OCIPicklerTdsElement elt);
6362:
6363: sword OCIPicklerTdsGenerate(OCIEnv *env, OCIError *err,
6364: OCIPicklerTds *tdsh);
6365:
6366: sword OCIPicklerTdsGetAttr(OCIEnv *env, OCIError *err,
6367: CONST OCIPicklerTds *tdsh, ub1 attrno,
6368: OCITypeCode *typ, ub2 *len);
6369:
6370: sword OCIPicklerFdoInit(OCIEnv *env, OCIError *err,
6371: OCIPicklerFdo **fdoh);
6372:
6373: sword OCIPicklerFdoFree(OCIEnv *env, OCIError *err,
6374: OCIPicklerFdo *fdoh);
6375:
6376: sword OCIPicklerImageInit(OCIEnv *env, OCIError *err,
6377: OCIPicklerFdo *fdoh,
6378: OCIPicklerTds *tdsh,
6379: OCIPicklerImage **imgh);
6380:
6381: sword OCIPicklerImageFree(OCIEnv *env, OCIError *err,
6382: OCIPicklerImage *imgh);
6383:
6384: sword OCIPicklerImageAddScalar(OCIEnv *env, OCIError *err,
6385: OCIPicklerImage *imgh, dvoid *scalar, ub4 len);
6386:
6387: sword OCIPicklerImageAddNullScalar(OCIEnv *env, OCIError *err,
6388: OCIPicklerImage *imgh);
6389:
6390: sword OCIPicklerImageGenerate(OCIEnv *env, OCIError *err,
6391: OCIPicklerImage *imgh);
6392:
6393: sword OCIPicklerImageGetScalarSize(OCIEnv *env, OCIError *err,
6394: OCIPicklerImage *imgh,
6395: ub4 attrno, ub4 *size);
6396:
6397: sword OCIPicklerImageGetScalar(OCIEnv *env, OCIError *err,
6398: OCIPicklerImage *imgh, ub4 attrno,
6399: dvoid *buf, ub4 *len, OCIInd *ind);
6400:
6401: sword OCIPicklerImageCollBegin(OCIEnv *env, OCIError *err,
6402: OCIPicklerImage *imgh, CONST OCIPicklerTds *colltdsh);
6403:
6404: sword OCIPicklerImageCollAddScalar( OCIEnv *env, OCIError *err,
6405: OCIPicklerImage *imgh, dvoid *scalar,
6406: ub4 buflen, OCIInd ind);
6407:
6408: sword OCIPicklerImageCollEnd(OCIEnv *env, OCIError *err,
6409: OCIPicklerImage *imgh);
6410:
6411: /* should take svcctx for locator stuff */
6412: sword OCIPicklerImageCollBeginScan(OCIEnv *env, OCIError *err,
6413: OCIPicklerImage *imgh, CONST OCIPicklerTds *coll_tdsh,
6414: ub4 attrnum, ub4 startidx, OCIInd *ind);
6415:
6416: sword OCIPicklerImageCollGetScalarSize(OCIEnv *env, OCIError *err,
6417: CONST OCIPicklerTds *coll_tdsh, ub4 *size);
6418:
6419: sword OCIPicklerImageCollGetScalar(OCIEnv *env, OCIError *err,
6420: OCIPicklerImage *imgh, dvoid *buf,
6421: ub4 *buflen, OCIInd *ind);
6422:
6423: sword OCIFormatInit(dvoid *hndl, OCIError *err);
6424:
6425: sword OCIFormatString(dvoid *hndl, OCIError *err, OraText *buffer,
6426: sbig_ora bufferLength, sbig_ora *returnLength,
6427: CONST OraText *formatString, ...);
6428:
6429: sword OCIFormatTerm(dvoid *hndl, OCIError *err);
6430:
6431: sword OCIFormatTUb1(void);
6432: sword OCIFormatTUb2(void);
6433: sword OCIFormatTUb4(void);
6434: sword OCIFormatTUword(void);
6435: sword OCIFormatTUbig_ora(void);
6436: sword OCIFormatTSb1(void);
6437: sword OCIFormatTSb2(void);
6438: sword OCIFormatTSb4(void);
6439: sword OCIFormatTSword(void);
6440: sword OCIFormatTSbig_ora(void);
6441: sword OCIFormatTEb1(void);
6442: sword OCIFormatTEb2(void);
6443: sword OCIFormatTEb4(void);
6444: sword OCIFormatTEword(void);
6445: sword OCIFormatTChar(void);
6446: sword OCIFormatTText(void);
6447: sword OCIFormatTDouble(void);
6448: sword OCIFormatTDvoid(void);
6449: sword OCIFormatTEnd(void);
6450:
6451: /*-------------------------- Extensions to XA interface ---------------------*/
6452: /* ------------------------- xaosvch ----------------------------------------*/
6453: /*
6454: NAME
6455: xaosvch - XA Oracle get SerViCe Handle
6456: DESCRIPTION
6457: Given a database name return the service handle that is used by the
6458: XA library
6459: NOTE
6460: This macro has been provided for backward compatibilty with 8.0.2
6461: */
6462: OCISvcCtx *xaosvch(OraText *dbname);
6463:
6464: /* ------------------------- xaoSvcCtx --------------------------------------*/
6465: /*
6466: NAME
6467: xaoSvcCtx - XA Oracle get SerViCe ConTeXt
6468: DESCRIPTION
6469: Given a database name return the service handle that is used by the
6470: XA library
6471: NOTE
6472: This routine has been provided for APs to get access to the service
6473: handle that XA library uses. Without this routine APs must use SQLLIB
6474: routine sqlld2 to get access to the Logon data area registered by the
6475: XA library
6476: */
6477: OCISvcCtx *xaoSvcCtx(OraText *dbname);
6478:
6479: /* ------------------------- xaoEnv -----------------------------------------*/
6480: /*
6481: NAME
6482: xaoEnv - XA Oracle get ENvironment Handle
6483: DESCRIPTION
6484: Given a database name return the environment handle that is used by the
6485: XA library
6486: NOTE
6487: This routine has been provided for APs to get access to the environment
6488: handle that XA library uses. Without this routine APs must use SQLLIB
6489: routine sqlld2 to get access to the Logon data area registered by the
6490: XA library
6491: */
6492: OCIEnv *xaoEnv(OraText *dbname);
6493:
6494: /* ------------------------- xaosterr ---------------------------------------*/
6495: /*
6496: NAME
6497: xaosterr - XA Oracle get xa STart ERRor code
6498: DESCRIPTION
6499: Given an oracle error code return the XA error code
6500: */
6501: int xaosterr(OCISvcCtx *svch, sb4 error);
6502: /*-------------------------- End Extensions ---------------------------------*/
6503: /*---------------------- Extensions to NLS cartridge service ----------------*/
6504: /* ----------------------- OCINlsGetInfo ------------------------------------*/
6505: /*
6506: NAME
6507: OCINlsGetInfo - Get NLS info from OCI environment handle
6508: REMARKS
6509: This function generates language information specified by item from OCI
6510: environment handle envhp into an array pointed to by buf within size
6511: limitation as buflen.
6512: RETURNS
6513: OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR on wrong item.
6514: envhp(IN/OUT)
6515: OCI environment handle.
6516: errhp(IN/OUT)
6517: The OCI error handle. If there is an error, it is record in errhp and
6518: this function returns a NULL pointer. Diagnostic information can be
6519: obtained by calling OCIErrorGet().
6520: buf(OUT)
6521: Pointer to the destination buffer.
6522: buflen(IN)
6523: The size of destination buffer. The maximum length for each information
6524: is 32 bytes.
6525: item(IN)
6526: It specifies to get which item in OCI environment handle and can be one
6527: of following values:
6528: OCI_NLS_DAYNAME1 : Native name for Monday.
6529: OCI_NLS_DAYNAME2 : Native name for Tuesday.
6530: OCI_NLS_DAYNAME3 : Native name for Wednesday.
6531: OCI_NLS_DAYNAME4 : Native name for Thursday.
6532: OCI_NLS_DAYNAME5 : Native name for Friday.
6533: OCI_NLS_DAYNAME6 : Native name for for Saturday.
6534: OCI_NLS_DAYNAME7 : Native name for for Sunday.
6535: OCI_NLS_ABDAYNAME1 : Native abbreviated name for Monday.
6536: OCI_NLS_ABDAYNAME2 : Native abbreviated name for Tuesday.
6537: OCI_NLS_ABDAYNAME3 : Native abbreviated name for Wednesday.
6538: OCI_NLS_ABDAYNAME4 : Native abbreviated name for Thursday.
6539: OCI_NLS_ABDAYNAME5 : Native abbreviated name for Friday.
6540: OCI_NLS_ABDAYNAME6 : Native abbreviated name for for Saturday.
6541: OCI_NLS_ABDAYNAME7 : Native abbreviated name for for Sunday.
6542: OCI_NLS_MONTHNAME1 : Native name for January.
6543: OCI_NLS_MONTHNAME2 : Native name for February.
6544: OCI_NLS_MONTHNAME3 : Native name for March.
6545: OCI_NLS_MONTHNAME4 : Native name for April.
6546: OCI_NLS_MONTHNAME5 : Native name for May.
6547: OCI_NLS_MONTHNAME6 : Native name for June.
6548: OCI_NLS_MONTHNAME7 : Native name for July.
6549: OCI_NLS_MONTHNAME8 : Native name for August.
6550: OCI_NLS_MONTHNAME9 : Native name for September.
6551: OCI_NLS_MONTHNAME10 : Native name for October.
6552: OCI_NLS_MONTHNAME11 : Native name for November.
6553: OCI_NLS_MONTHNAME12 : Native name for December.
6554: OCI_NLS_ABMONTHNAME1 : Native abbreviated name for January.
6555: OCI_NLS_ABMONTHNAME2 : Native abbreviated name for February.
6556: OCI_NLS_ABMONTHNAME3 : Native abbreviated name for March.
6557: OCI_NLS_ABMONTHNAME4 : Native abbreviated name for April.
6558: OCI_NLS_ABMONTHNAME5 : Native abbreviated name for May.
6559: OCI_NLS_ABMONTHNAME6 : Native abbreviated name for June.
6560: OCI_NLS_ABMONTHNAME7 : Native abbreviated name for July.
6561: OCI_NLS_ABMONTHNAME8 : Native abbreviated name for August.
6562: OCI_NLS_ABMONTHNAME9 : Native abbreviated name for September.
6563: OCI_NLS_ABMONTHNAME10 : Native abbreviated name for October.
6564: OCI_NLS_ABMONTHNAME11 : Native abbreviated name for November.
6565: OCI_NLS_ABMONTHNAME12 : Native abbreviated name for December.
6566: OCI_NLS_YES : Native string for affirmative response.
6567: OCI_NLS_NO : Native negative response.
6568: OCI_NLS_AM : Native equivalent string of AM.
6569: OCI_NLS_PM : Native equivalent string of PM.
6570: OCI_NLS_AD : Native equivalent string of AD.
6571: OCI_NLS_BC : Native equivalent string of BC.
6572: OCI_NLS_DECIMAL : decimal character.
6573: OCI_NLS_GROUP : group separator.
6574: OCI_NLS_DEBIT : Native symbol of debit.
6575: OCI_NLS_CREDIT : Native sumbol of credit.
6576: OCI_NLS_DATEFORMAT : Oracle date format.
6577: OCI_NLS_INT_CURRENCY: International currency symbol.
6578: OCI_NLS_LOC_CURRENCY : Locale currency symbol.
6579: OCI_NLS_LANGUAGE : Language name.
6580: OCI_NLS_ABLANGUAGE : Abbreviation for language name.
6581: OCI_NLS_TERRITORY : Territory name.
6582: OCI_NLS_CHARACTER_SET : Character set name.
6583: OCI_NLS_LINGUISTIC : Linguistic name.
6584: OCI_NLS_CALENDAR : Calendar name.
6585: OCI_NLS_DUAL_CURRENCY : Dual currency symbol.
6586: */
6587: sword OCINlsGetInfo(dvoid *envhp, OCIError *errhp, OraText *buf,
6588: size_t buflen, ub2 item);
6589:
6590:
6591: /* -------------------- OCIMultiByteToWideChar ------------------------------*/
6592: /*
6593: NAME
6594: OCIMultiByteToWideChar - Convert a null terminated multibyte string into
6595: wchar
6596: REMARKS
6597: This routine converts an entire null-terminated string into the wchar
6598: format. The wchar output buffer will be null-terminated.
6599: RETURNS
6600: OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
6601: envhp(IN/OUT)
6602: OCI environment handle to determine the character set of string.
6603: dst (OUT)
6604: Destination buffer for wchar.
6605: src (IN)
6606: Source string to be converted.
6607: rsize (OUT)
6608: Number of characters converted including null-terminator.
6609: If it is a NULL pointer, no number return
6610: */
6611: sword OCIMultiByteToWideChar(dvoid *envhp, OCIWchar *dst, CONST OraText *src,
6612: size_t *rsize);
6613:
6614:
6615: /* --------------------- OCIMultiByteInSizeToWideChar -----------------------*/
6616: /*
6617: NAME
6618: OCIMultiByteInSizeToWideChar - Convert a mulitbyte string in length into
6619: wchar
6620: REMARKS
6621: This routine converts part of string into the wchar format. It will
6622: convert as many complete characters as it can until it reaches output
6623: buffer size or input buffer size or it reaches a null-terminator in
6624: source string. The output buffer will be null-terminated if space permits.
6625: If dstsz is zero, this function will only return number of characters not
6626: including ending null terminator for converted string.
6627: RETURNS
6628: OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
6629: envhp(IN/OUT)
6630: OCI environment handle to determine the character set of string.
6631: dst (OUT)
6632: Pointer to a destination buffer for wchar. It can be NULL pointer when
6633: dstsz is zero.
6634: dstsz(IN)
6635: Destination buffer size in character. If it is zero, this function just
6636: returns number of characters will be need for the conversion.
6637: src (IN)
6638: Source string to be converted.
6639: srcsz(IN)
6640: Length of source string in byte.
6641: rsize(OUT)
6642: Number of characters written into destination buffer, or number of
6643: characters for converted string is dstsz is zero.
6644: If it is NULL pointer, nothing to return.
6645: */
6646: sword OCIMultiByteInSizeToWideChar(dvoid *envhp, OCIWchar *dst,
6647: size_t dstsz, CONST OraText *src,
6648: size_t srcsz, size_t *rsize);
6649:
6650:
6651: /* ---------------------- OCIWideCharToMultiByte ----------------------------*/
6652: /*
6653: NAME
6654: OCIWideCharToMultiByte - Convert a null terminated wchar string into
6655: multibyte
6656: REMARKS
6657: This routine converts an entire null-terminated wide character string into
6658: multi-byte string. The output buffer will be null-terminated.
6659: RETURNS
6660: OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
6661: envhp(IN/OUT)
6662: OCI environment handle to determine the character set of string.
6663: dst (OUT)
6664: Destination buffer for multi-byte string.
6665: src (IN)
6666: Source wchar string to be converted.
6667: rsize (OUT)
6668: Number of bytes written into the destination buffer.
6669: If it is NULL pointer, nothing to return.
6670: */
6671: sword OCIWideCharToMultiByte(dvoid *envhp, OraText *dst, CONST OCIWchar *src,
6672: size_t *rsize);
6673:
6674:
6675: /* ---------------------- OCIWideCharInSizeToMultiByte ----------------------*/
6676: /*
6677: NAME
6678: OCIWideCharInSizeToMultiByte - Convert a wchar string in length into
6679: mulitbyte
6680: REMARKS
6681: This routine converts part of wchar string into the multi-byte format.
6682: It will convert as many complete characters as it can until it reaches
6683: output buffer size or input buffer size or it reaches a null-terminator
6684: in source string. The output buffer will be null-terminated if space
6685: permits. If dstsz is zero, the function just returns the size of byte not
6686: including ending null-terminator need to store the converted string.
6687: RETURNS
6688: OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
6689: envhp(IN/OUT)
6690: OCI environment handle to determine the character set of string.
6691: dst (OUT)
6692: Destination buffer for multi-byte. It can be NULL pointer if dstsz is zero.
6693: dstsz(IN)
6694: Destination buffer size in byte. If it is zero, it just returns the size
6695: of bytes need for converted string.
6696: src (IN)
6697: Source wchar string to be converted.
6698: srcsz(IN)
6699: Length of source string in character.
6700: rsize(OUT)
6701: Number of bytes written into destination buffer, or number of bytes need
6702: to store the converted string if dstsz is zero.
6703: If it is NULL pointer, nothing to return.
6704: */
6705: sword OCIWideCharInSizeToMultiByte(dvoid *envhp, OraText *dst,
6706: size_t dstsz, CONST OCIWchar *src,
6707: size_t srcsz, size_t *rsize);
6708:
6709:
6710:
6711: /* ----------------------- OCIWideCharIsAlnum -------------------------------*/
6712: /*
6713: NAME
6714: OCIWideCharIsAlnum - test whether wc is a letter or decimal digit
6715: REMARKS
6716: It tests whether wc is a letter or decimal digit.
6717: RETURNS
6718: TRUE or FLASE.
6719: envhp(IN/OUT)
6720: OCI environment handle to determine the character set .
6721: wc(IN)
6722: Wchar for testing.
6723: */
6724: boolean OCIWideCharIsAlnum(dvoid *envhp, OCIWchar wc);
6725:
6726:
6727: /* ----------------------- OCIWideCharIsAlpha -------------------------------*/
6728: /*
6729: NAME
6730: OCIWideCharIsAlpha - test whether wc is an alphabetic letter
6731: REMARKS
6732: It tests whether wc is an alphabetic letter
6733: RETURNS
6734: TRUE or FLASE.
6735: envhp(IN/OUT)
6736: OCI environment handle to determine the character set .
6737: wc(IN)
6738: Wchar for testing.
6739: */
6740: boolean OCIWideCharIsAlpha(dvoid *envhp, OCIWchar wc);
6741:
6742:
6743: /* --------------------- OCIWideCharIsCntrl ---------------------------------*/
6744: /*
6745: NAME
6746: OCIWideCharIsCntrl - test whether wc is a control character
6747: REMARKS
6748: It tests whether wc is a control character.
6749: RETURNS
6750: TRUE or FLASE.
6751: envhp(IN/OUT)
6752: OCI environment handle to determine the character set .
6753: wc(IN)
6754: Wchar for testing.
6755: */
6756: boolean OCIWideCharIsCntrl(dvoid *envhp, OCIWchar wc);
6757:
6758:
6759: /* ----------------------- OCIWideCharIsDigit -------------------------------*/
6760: /*
6761: NAME
6762: OCIWideCharIsDigit - test whether wc is a decimal digit character
6763: REMARKS
6764: It tests whether wc is a decimal digit character.
6765: RETURNS
6766: TRUE or FLASE.
6767: envhp(IN/OUT)
6768: OCI environment handle to determine the character set .
6769: wc(IN)
6770: Wchar for testing.
6771: */
6772: boolean OCIWideCharIsDigit(dvoid *envhp, OCIWchar wc);
6773:
6774:
6775: /* ----------------------- OCIWideCharIsGraph -------------------------------*/
6776: /*
6777: NAME
6778: OCIWideCharIsGraph - test whether wc is a graph character
6779: REMARKS
6780: It tests whether wc is a graph character. A graph character is character
6781: with a visible representation and normally includes alphabetic letter,
6782: decimal digit, and punctuation.
6783: RETURNS
6784: TRUE or FLASE.
6785: envhp(IN/OUT)
6786: OCI environment handle to determine the character set .
6787: wc(IN)
6788: Wchar for testing.
6789: */
6790: boolean OCIWideCharIsGraph(dvoid *envhp, OCIWchar wc);
6791:
6792:
6793: /* ----------------------- OCIWideCharIsLower -------------------------------*/
6794: /*
6795: NAME
6796: OCIWideCharIsLower - test whether wc is a lowercase letter
6797: REMARKS
6798: It tests whether wc is a lowercase letter.
6799: RETURNS
6800: TRUE or FLASE.
6801: envhp(IN/OUT)
6802: OCI environment handle to determine the character set .
6803: wc(IN)
6804: Wchar for testing.
6805: */
6806: boolean OCIWideCharIsLower(dvoid *envhp, OCIWchar wc);
6807:
6808:
6809: /* ----------------------- OCIWideCharIsPrint -------------------------------*/
6810: /*
6811: NAME
6812: OCIWideCharIsPrint - test whether wc is a printable character
6813: REMARKS
6814: It tests whether wc is a printable character.
6815: RETURNS
6816: TRUE or FLASE.
6817: envhp(IN/OUT)
6818: OCI environment handle to determine the character set .
6819: wc(IN)
6820: Wchar for testing.
6821: */
6822: boolean OCIWideCharIsPrint(dvoid *envhp, OCIWchar wc);
6823:
6824:
6825: /* ----------------------- OCIWideCharIsPunct -------------------------------*/
6826: /*
6827: NAME
6828: OCIWideCharIsPunct - test whether wc is a punctuation character
6829: REMARKS
6830: It tests whether wc is a punctuation character.
6831: RETURNS
6832: TRUE or FLASE.
6833: envhp(IN/OUT)
6834: OCI environment handle to determine the character set .
6835: wc(IN)
6836: Wchar for testing.
6837: */
6838: boolean OCIWideCharIsPunct(dvoid *envhp, OCIWchar wc);
6839:
6840:
6841: /* ----------------------- OCIWideCharIsSpace -------------------------------*/
6842: /*
6843: NAME
6844: OCIWideCharIsSpace - test whether wc is a space character
6845: REMARKS
6846: It tests whether wc is a space character. A space character only causes
6847: white space in displayed text(for example, space, tab, carriage return,
6848: newline, vertical tab or form feed).
6849: RETURNS
6850: TRUE or FLASE.
6851: envhp(IN/OUT)
6852: OCI environment handle to determine the character set .
6853: wc(IN)
6854: Wchar for testing.
6855: */
6856: boolean OCIWideCharIsSpace(dvoid *envhp, OCIWchar wc);
6857:
6858:
6859: /* ----------------------- OCIWideCharIsUpper -------------------------------*/
6860: /*
6861: NAME
6862: OCIWideCharIsUpper - test whether wc is a uppercase letter
6863: REMARKS
6864: It tests whether wc is a uppercase letter.
6865: RETURNS
6866: TRUE or FLASE.
6867: envhp(IN/OUT)
6868: OCI environment handle to determine the character set .
6869: wc(IN)
6870: Wchar for testing.
6871: */
6872: boolean OCIWideCharIsUpper(dvoid *envhp, OCIWchar wc);
6873:
6874:
6875: /*----------------------- OCIWideCharIsXdigit -------------------------------*/
6876: /*
6877: NAME
6878: OCIWideCharIsXdigit - test whether wc is a hexadecimal digit
6879: REMARKS
6880: It tests whether wc is a hexadecimal digit ( 0-9, A-F, a-f ).
6881: RETURNS
6882: TRUE or FLASE.
6883: envhp(IN/OUT)
6884: OCI environment handle to determine the character set .
6885: wc(IN)
6886: Wchar for testing.
6887: */
6888: boolean OCIWideCharIsXdigit(dvoid *envhp, OCIWchar wc);
6889:
6890:
6891: /* --------------------- OCIWideCharIsSingleByte ----------------------------*/
6892: /*
6893: NAME
6894: OCIWideCharIsSingleByte - test whether wc is a single-byte character
6895: REMARKS
6896: It tests whether wc is a single-byte character when converted into
6897: multi-byte.
6898: RETURNS
6899: TRUE or FLASE.
6900: envhp(IN/OUT)
6901: OCI environment handle to determine the character set .
6902: wc(IN)
6903: Wchar for testing.
6904: */
6905: boolean OCIWideCharIsSingleByte(dvoid *envhp, OCIWchar wc);
6906:
6907:
6908: /* ----------------------- OCIWideCharToLower -------------------------------*/
6909: /*
6910: NAME
6911: OCIWideCharToLower - Convert a wchar into the lowercase
6912: REMARKS
6913: If there is a lower-case character mapping for wc in the specified locale,
6914: it will return the lower-case in wchar, else return wc itself.
6915: RETURNS
6916: A wchar
6917: envhp(IN/OUT)
6918: OCI environment handle to determine the character set .
6919: wc(IN)
6920: Wchar for lowercase mapping.
6921: */
6922: OCIWchar OCIWideCharToLower(dvoid *envhp, OCIWchar wc);
6923:
6924:
6925: /* ----------------------- OCIWideCharToUpper -------------------------------*/
6926: /*
6927: NAME
6928: OCIWideCharToUpper - Convert a wchar into the uppercase
6929: REMARKS
6930: If there is a upper-case character mapping for wc in the specified locale,
6931: it will return the upper-case in wchar, else return wc itself.
6932: RETURNS
6933: A wchar
6934: envhp(IN/OUT)
6935: OCI environment handle to determine the character set .
6936: wc(IN)
6937: Wchar for uppercase mapping.
6938: */
6939: OCIWchar OCIWideCharToUpper(dvoid *envhp, OCIWchar wc);
6940:
6941:
6942: /* ----------------------- OCIWideCharStrcmp --------------------------------*/
6943: /*
6944: NAME
6945: OCIWideCharStrcmp - compare two null terminated wchar string
6946: REMARKS
6947: It compares two wchar string in binary ( based on wchar encoding value ),
6948: linguistic, or case-insensitive.
6949: RETURNS
6950: 0, if wstr1 == wstr2.
6951: Positive, if wstr1 > wstr2.
6952: Negative, if wstr1 < wstr2.
6953: envhp(IN/OUT)
6954: OCI environment handle to determine the character set.
6955: wstr1(IN)
6956: Pointer to a null-terminated wchar string.
6957: wstr2(IN)
6958: Pointer to a null-terminated wchar string.
6959: flag(IN)
6960: It is used to decide the comparison method. It can be taken one of the
6961: following values:
6962: OCI_NLS_BINARY : for the binary comparison, this is default value.
6963: OCI_NLS_LINGUISTIC : for linguistic comparison specified in the locale.
6964: This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive
6965: comparison.
6966: */
6967: int OCIWideCharStrcmp(dvoid *envhp, CONST OCIWchar *wstr1,
6968: CONST OCIWchar *wstr2, int flag);
6969:
6970:
6971: /* ----------------------- OCIWideCharStrncmp -------------------------------*/
6972: /*
6973: NAME
6974: OCIWideCharStrncmp - compare twe wchar string in length
6975: REMARKS
6976: This function is similar to OCIWideCharStrcmp(), except that at most len1
6977: characters from wstr1 and len2 characters from wstr1 are compared. The
6978: null-terminator will be taken into the comparison.
6979: RETURNS
6980: 0, if wstr1 = wstr2
6981: Positive, if wstr1 > wstr2
6982: Negative, if wstr1 < wstr2
6983: envhp(IN/OUT)
6984: OCI environment handle to determine the character set .
6985: wstr1(IN)
6986: Pointer to the first wchar string
6987: len1(IN)
6988: The length for the first string for comparison
6989: wstr2(IN)
6990: Pointer to the second wchar string
6991: len2(IN)
6992: The length for the second string for comparison.
6993: flag(IN)
6994: It is used to decide the comparison method. It can be taken one of the
6995: following values:
6996: OCI_NLS_BINARY : for the binary comparison, this is default value.
6997: OCI_NLS_LINGUISTIC : for linguistic comparison specified in the locale.
6998: This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive
6999: comparison.
7000: */
7001: int OCIWideCharStrncmp(dvoid *envhp, CONST OCIWchar *wstr1, size_t len1,
7002: CONST OCIWchar *wstr2, size_t len2, int flag);
7003:
7004:
7005: /* ----------------------- OCIWideCharStrcat --------------------------------*/
7006: /*
7007: NAME
7008: OCIWideCharStrcat - concatenate two wchar strings
7009: REMARKS
7010: This function appends a copy of the wchar string pointed to by wsrcstr,
7011: including the null-terminator to the end of wchar string pointed to by
7012: wdststr. It returns the number of character in the result string not
7013: including the ending null-terminator.
7014: RETURNS
7015: number of characters in the result string not including the ending
7016: null-terminator.
7017: envhp(IN/OUT)
7018: OCI environment handle to determine the character set .
7019: wdststr(IN/OUT)
7020: Pointer to the destination wchar string for appending.
7021: wsrcstr(IN)
7022: Pointer to the source wchar string to append.
7023: */
7024: size_t OCIWideCharStrcat(dvoid *envhp, OCIWchar *wdststr,
7025: CONST OCIWchar *wsrcstr);
7026:
7027:
7028: /* ----------------------- OCIWideCharStrchr --------------------------------*/
7029: /*
7030: NAME
7031: OCIWideCharStrchr - Search the first occurrence of wchar in a wchar string
7032: REMARKS
7033: This function searchs for the first occurrence of wc in the wchar string
7034: pointed to by wstr. It returns a pointer to the whcar if successful, or
7035: a null pointer.
7036: RETURNS
7037: wchar pointer if successful, otherwise a null pointer.
7038: envhp(IN/OUT)
7039: OCI environment handle to determine the character set .
7040: wstr(IN)
7041: Pointer to the wchar string to search
7042: wc(IN)
7043: Wchar to search for.
7044: */
7045: OCIWchar *OCIWideCharStrchr(dvoid *envhp, CONST OCIWchar *wstr,
7046: OCIWchar wc);
7047:
7048:
7049: /* ----------------------- OCIWideCharStrcpy --------------------------------*/
7050: /*
7051: NAME
7052: OCIWideCharStrcpy - copy a wchar string
7053: REMARKS
7054: This function copies the wchar string pointed to by wsrcstr, including the
7055: null-terminator, into the array pointed to by wdststr. It returns the
7056: number of character copied not including the ending null-terminator.
7057: RETURNS
7058: number of characters copied not including the ending null-terminator.
7059: envhp(IN/OUT)
7060: OCI environment handle to determine the character set .
7061: wdststr(OUT)
7062: Pointer to the destination wchar buffer.
7063: wsrcstr(IN)
7064: Pointer to the source wchar string.
7065: */
7066: size_t OCIWideCharStrcpy(dvoid *envhp, OCIWchar *wdststr,
7067: CONST OCIWchar *wsrcstr);
7068:
7069:
7070: /* ----------------------- OCIWideCharStrlen --------------------------------*/
7071: /*
7072: NAME
7073: OCIWideCharStrlen - Return number of character in a wchar string
7074: REMARKS
7075: This function computes the number of characters in the wchar string
7076: pointed to by wstr, not including the null-terminator, and returns
7077: this number.
7078: RETURNS
7079: number of characters not including ending null-terminator.
7080: envhp(IN/OUT)
7081: OCI environment handle to determine the character set .
7082: wstr(IN)
7083: Pointer to the source wchar string.
7084: */
7085: size_t OCIWideCharStrlen(dvoid *envhp, CONST OCIWchar *wstr);
7086:
7087:
7088: /* ----------------------- OCIWideCharStrncat -------------------------------*/
7089: /*
7090: NAME
7091: OCIWideCharStrncat - Concatenate wchar string in length
7092: REMARKS
7093: This function is similar to OCIWideCharStrcat(), except that at most n
7094: characters from wsrcstr are appended to wdststr. Note that the
7095: null-terminator in wsrcstr will stop appending. wdststr will be
7096: null-terminated..
7097: RETURNS
7098: Number of characters in the result string not including the ending
7099: null-terminator.
7100: envhp(IN/OUT)
7101: OCI environment handle to determine the character set .
7102: wdststr(IN/OUT)
7103: Pointer to the destination wchar string for appending.
7104: wsrcstr(IN)
7105: Pointer to the source wchar string to append.
7106: n(IN)
7107: Number of characters from wsrcstr to append.
7108: */
7109: size_t OCIWideCharStrncat(dvoid *envhp, OCIWchar *wdststr,
7110: CONST OCIWchar *wsrcstr, size_t n);
7111:
7112:
7113: /* ----------------------- OCIWideCharStrncpy -------------------------------*/
7114: /*
7115: NAME
7116: OCIWideCharStrncpy - Copy wchar string in length
7117: REMARKS
7118: This function is similar to OCIWideCharStrcpy(), except that at most n
7119: characters are copied from the array pointed to by wsrcstr to the array
7120: pointed to by wdststr. Note that the null-terminator in wdststr will
7121: stop coping and result string will be null-terminated.
7122: RETURNS
7123: number of characters copied not including the ending null-terminator.
7124: envhp(IN/OUT)
7125: OCI environment handle to determine the character set .
7126: wdststr(OUT)
7127: Pointer to the destination wchar buffer.
7128: wsrcstr(IN)
7129: Pointer to the source wchar string.
7130: n(IN)
7131: Number of characters from wsrcstr to copy.
7132: */
7133: size_t OCIWideCharStrncpy(dvoid *envhp, OCIWchar *wdststr,
7134: CONST OCIWchar *wsrcstr, size_t n);
7135:
7136:
7137: /* ----------------------- OCIWideCharStrrchr -------------------------------*/
7138: /*
7139: NAME
7140: OCIWideCharStrrchr - search the last occurrence of a wchar in wchar string
7141: REMARKS
7142: This function searchs for the last occurrence of wc in the wchar string
7143: pointed to by wstr. It returns a pointer to the whcar if successful, or
7144: a null pointer.
7145: RETURNS
7146: wchar pointer if successful, otherwise a null pointer.
7147: envhp(IN/OUT)
7148: OCI environment handle to determine the character set .
7149: wstr(IN)
7150: Pointer to the wchar string to search
7151: wc(IN)
7152: Wchar to search for.
7153: */
7154: OCIWchar *OCIWideCharStrrchr(dvoid *envhp, CONST OCIWchar *wstr,
7155: OCIWchar wc);
7156:
7157:
7158: /* --------------------- OCIWideCharStrCaseConversion -----------------------*/
7159: /*
7160: NAME
7161: OCIWideCharStrCaseConversion - convert a wchar string into lowercase or
7162: uppercase
7163: REMARKS
7164: This function convert the wide char string pointed to by wsrcstr into the
7165: uppercase or lowercase specified by flag and copies the result into the
7166: array pointed to by wdststr. The result string will be null-terminated.
7167: RETURNS
7168: number of characters for result string not including null-terminator.
7169: envhp(IN/OUT)
7170: OCI environment handle.
7171: wdststr(OUT)
7172: Pointer to destination array.
7173: wsrcstr(IN)
7174: Pointer to source string.
7175: flag(IN)
7176: Specify the case to convert:
7177: OCI_NLS_UPPERCASE : convert to uppercase.
7178: OCI_NLS_LOWERCASE: convert to lowercase.
7179: This flag can be ORed with OCI_NLS_LINGUISTIC to specify that the
7180: linguistic setting in the locale will be used for case conversion.
7181: */
7182: size_t OCIWideCharStrCaseConversion(dvoid *envhp, OCIWchar *wdststr,
7183: CONST OCIWchar *wsrcstr, ub4 flag);
7184:
7185:
7186: /*---------------------- OCIWideCharDisplayLength ---------------------------*/
7187: /*
7188: NAME
7189: OCIWideCharDisplayLength - Calculate the display length for a wchar
7190: REMARKS
7191: This function determines the number of column positions required for wc
7192: in display. It returns number of column positions, or 0 if wc is
7193: null-terminator.
7194: RETURNS
7195: Number of display positions.
7196: envhp(IN/OUT)
7197: OCI environment handle to determine the character set .
7198: wc(IN)
7199: Wchar character.
7200: */
7201: size_t OCIWideCharDisplayLength(dvoid *envhp, OCIWchar wc );
7202:
7203:
7204: /*---------------------- OCIWideCharMultiByteLength -------------------------*/
7205: /*
7206: NAME
7207: OCIWideCharMultiByteLength - Determine byte size in multi-byte encoding
7208: REMARKS
7209: This function determines the number of byte required for wc in multi-byte
7210: encoding. It returns number of bytes in multi-byte for wc.
7211: RETURNS
7212: Number of bytes.
7213: envhp(IN/OUT)
7214: OCI environment handle to determine the character set .
7215: wc(IN)
7216: Wchar character.
7217: */
7218: size_t OCIWideCharMultiByteLength(dvoid *envhp, OCIWchar wc);
7219:
7220:
7221: /* ----------------------- OCIMultiByteStrcmp -------------------------------*/
7222: /*
7223: NAME
7224: OCIMultiByteStrcmp - Compare two multi-byte strings
7225: REMARKS
7226: It compares two multi-byte strings in binary ( based on encoding value ),
7227: linguistic, or case-insensitive.
7228: RETURNS
7229: 0, if str1 == str2.
7230: Positive, if str1 > str2.
7231: Negative, if str1 < str2.
7232: envhp(IN/OUT)
7233: OCI environment handle to determine the character set.
7234: str1(IN)
7235: Pointer to a null-terminated string.
7236: str2(IN)
7237: Pointer to a null-terminated string.
7238: flag(IN)
7239: It is used to decide the comparison method. It can be taken one of the
7240: following values:
7241: OCI_NLS_BINARY: for the binary comparison, this is default value.
7242: OCI_NLS_LINGUISTIC: for linguistic comparison specified in the locale.
7243: This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive
7244: comparison.
7245: */
7246: int OCIMultiByteStrcmp(dvoid *envhp, CONST OraText *str1,
7247: CONST OraText *str2, int flag);
7248:
7249:
7250: /*----------------------- OCIMultiByteStrncmp -------------------------------*/
7251: /*
7252: NAME
7253: OCIMultiByteStrncmp - compare two strings in length
7254: REMARKS
7255: This function is similar to OCIMultiBytestrcmp(), except that at most len1 bytes
7256: from str1 and len2 bytes from str2 are compared. The null-terminator will
7257: be taken into the comparison.
7258: RETURNS
7259: 0, if str1 = str2
7260: Positive, if str1 > str2
7261: Negative, if str1 < str2
7262: envhp(IN/OUT)
7263: OCI environment handle to determine the character set.
7264: str1(IN)
7265: Pointer to the first string
7266: len1(IN)
7267: The length for the first string for comparison
7268: str2(IN)
7269: Pointer to the second string
7270: len2(IN)
7271: The length for the second string for comparison.
7272: flag(IN)
7273: It is used to decide the comparison method. It can be taken one of the
7274: following values:
7275: OCI_NLS_BINARY: for the binary comparison, this is default value.
7276: OCI_NLS_LINGUISTIC: for linguistic comparison specified in the locale.
7277: This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive
7278: comparison.
7279: */
7280: int OCIMultiByteStrncmp(dvoid *envhp, CONST OraText *str1, size_t len1,
7281: OraText *str2, size_t len2, int flag);
7282:
7283:
7284: /*----------------------- OCIMultiByteStrcat --------------------------------*/
7285: /*
7286: NAME
7287: OCIMultiByteStrcat - concatenate multibyte strings
7288: REMARKS
7289: This function appends a copy of the multi-byte string pointed to by
7290: srcstr, including the null-terminator to the end of string pointed to by
7291: dststr. It returns the number of bytes in the result string not including
7292: the ending null-terminator.
7293: RETURNS
7294: number of bytes in the result string not including the ending
7295: null-terminator.
7296: envhp(IN/OUT)
7297: Pointer to OCI environment handle
7298: dststr(IN/OUT)
7299: Pointer to the destination multi-byte string for appending.
7300: srcstr(IN)
7301: Pointer to the source string to append.
7302: */
7303: size_t OCIMultiByteStrcat(dvoid *envhp, OraText *dststr,
7304: CONST OraText *srcstr);
7305:
7306:
7307: /*------------------------- OCIMultiByteStrcpy ------------------------------*/
7308: /*
7309: NAME
7310: OCIMultiByteStrcpy - copy multibyte string
7311: REMARKS
7312: This function copies the multi-byte string pointed to by srcstr,
7313: including the null-terminator, into the array pointed to by dststr. It
7314: returns the number of bytes copied not including the ending
7315: null-terminator.
7316: RETURNS
7317: number of bytes copied not including the ending null-terminator.
7318: envhp(IN/OUT)
7319: Pointer to the OCI environment handle.
7320: srcstr(OUT)
7321: Pointer to the destination buffer.
7322: dststr(IN)
7323: Pointer to the source multi-byte string.
7324: */
7325: size_t OCIMultiByteStrcpy(dvoid *envhp, OraText *dststr,
7326: CONST OraText *srcstr);
7327:
7328:
7329: /*----------------------- OCIMultiByteStrlen --------------------------------*/
7330: /*
7331: NAME
7332: OCIMultiByteStrlen - Calculate multibyte string length
7333: REMARKS
7334: This function computes the number of bytes in the multi-byte string
7335: pointed to by str, not including the null-terminator, and returns this
7336: number.
7337: RETURNS
7338: number of bytes not including ending null-terminator.
7339: str(IN)
7340: Pointer to the source multi-byte string.
7341: */
7342: size_t OCIMultiByteStrlen(dvoid *envhp, CONST OraText *str);
7343:
7344:
7345: /*----------------------- OCIMultiByteStrncat -------------------------------*/
7346: /*
7347: NAME
7348: OCIMultiByteStrncat - concatenate string in length
7349: REMARKS
7350: This function is similar to OCIMultiBytestrcat(), except that at most n
7351: bytes from srcstr are appended to dststr. Note that the null-terminator in
7352: srcstr will stop appending and the function will append as many character
7353: as possible within n bytes. dststr will be null-terminated.
7354: RETURNS
7355: Number of bytes in the result string not including the ending
7356: null-terminator.
7357: envhp(IN/OUT)
7358: Pointer to OCI environment handle.
7359: srcstr(IN/OUT)
7360: Pointer to the destination multi-byte string for appending.
7361: dststr(IN)
7362: Pointer to the source multi-byte string to append.
7363: n(IN)
7364: Number of bytes from srcstr to append.
7365: */
7366: size_t OCIMultiByteStrncat(dvoid *envhp, OraText *dststr,
7367: CONST OraText *srcstr, size_t n);
7368:
7369:
7370: /*----------------------- OCIMultiByteStrncpy -------------------------------*/
7371: /*
7372: NAME
7373: OCIMultiByteStrncpy - copy multibyte string in length
7374: REMARKS
7375: This function is similar to OCIMultiBytestrcpy(), except that at most n
7376: bytes are copied from the array pointed to by srcstr to the array pointed
7377: to by dststr. Note that the null-terminator in srcstr will stop coping and
7378: the function will copy as many character as possible within n bytes. The
7379: result string will be null-terminated.
7380: RETURNS
7381: number of bytes copied not including the ending null-terminator.
7382: envhp(IN/OUT)
7383: Pointer to a OCI environment handle.
7384: dststr(IN)
7385: Pointer to the source multi-byte string.
7386: srcstr(OUT)
7387: Pointer to the destination buffer.
7388: n(IN)
7389: Number of bytes from srcstr to copy.
7390: */
7391: size_t OCIMultiByteStrncpy(dvoid *envhp, OraText *dststr,
7392: CONST OraText *srcstr, size_t n);
7393:
7394:
7395: /*----------------------- OCIMultiByteStrnDisplayLength ---------------------*/
7396: /*
7397: NAME
7398: OCIMultiByteStrnDisplayLength - calculate the display length for a
7399: multibyt string
7400: REMARKS
7401: This function returns the number of display positions occupied by the
7402: complete characters within the range of n bytes.
7403: RETURNS
7404: number of display positions.
7405: envhp(IN/OUT)
7406: OCI environment handle.
7407: str(IN)
7408: Pointer to a multi-byte string.
7409: n(IN)
7410: Number of bytes to examine.
7411: */
7412: size_t OCIMultiByteStrnDisplayLength(dvoid *envhp, CONST OraText *str1,
7413: size_t n);
7414:
7415:
7416: /*---------------------- OCIMultiByteStrCaseConversion ---------------------*/
7417: /*
7418: NAME
7419: OCIMultiByteStrCaseConversion
7420: REMARKS
7421: This function convert the multi-byte string pointed to by srcstr into the
7422: uppercase or lowercase specified by flag and copies the result into the
7423: array pointed to by dststr. The result string will be null-terminated.
7424: RETURNS
7425: number of bytes for result string not including null-terminator.
7426: envhp(IN/OUT)
7427: OCI environment handle.
7428: dststr(OUT)
7429: Pointer to destination array.
7430: srcstr(IN)
7431: Pointer to source string.
7432: flag(IN)
7433: Specify the case to convert:
7434: OCI_NLS_UPPERCASE: convert to uppercase.
7435: OCI_NLS_LOWERCASE: convert to lowercase.
7436: This flag can be ORed with OCI_NLS_LINGUISTIC to specify that the
7437: linguistic setting in the locale will be used for case conversion.
7438: */
7439: size_t OCIMultiByteStrCaseConversion(dvoid *envhp, OraText *dststr,
7440: CONST OraText *srcstr, ub4 flag);
7441:
7442:
7443: /*------------------------- OCICharSetToUnicode -----------------------------*/
7444: /*
7445: NAME
7446: OCICharSetToUnicode - convert multibyte string into Unicode as UCS2
7447: REMARKS
7448: This function converts a multi-byte string pointed to by src to Unicode
7449: into the array pointed to by dst. The conversion will stop when it reach
7450: to the source limitation or destination limitation.
7451: The function will return number of characters converted into Unicode.
7452: If dstlen is zero, it will just return the number of characters for the
7453: result without real conversion.
7454: RETURNS
7455: OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
7456: envhp(IN/OUT)
7457: Pointer to an OCI environment handle
7458: dst(OUT)
7459: Pointer to a destination buffer
7460: dstlen(IN)
7461: Size of destination buffer in character
7462: src(IN)
7463: Pointer to multi-byte source string.
7464: srclen(IN)
7465: Size of source string in bytes.
7466: rsize(OUT)
7467: Number of characters converted.
7468: If it is a NULL pointer, nothing to return.
7469: */
7470: sword OCICharSetToUnicode(dvoid *envhp, ub2 *dst, size_t dstlen,
7471: CONST OraText *src, size_t srclen, size_t *rsize);
7472:
7473:
7474: /*------------------------- OCIUnicodeToCharSet -----------------------------*/
7475: /*
7476: NAME
7477: OCIUnicodeToCharSet - convert Unicode into multibyte
7478: REMARKS
7479: This function converts a Unicode string pointed to by src to multi-byte
7480: into the array pointed to by dst. The conversion will stop when it reach
7481: to the source limitation or destination limitation. The function will
7482: return number of bytes converted into multi-byte. If dstlen is zero, it
7483: will just return the number of bytes for the result without real
7484: conversion. If a Unicode character is not convertible for the character
7485: set specified in OCI environment handle, a replacement character will be
7486: used for it. In this case, OCICharSetConversionIsReplacementUsed() will
7487: return ture.
7488: RETURNS
7489: OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
7490: envhp(IN/OUT)
7491: Pointer to an OCI environment handle.
7492: dst(OUT)
7493: Pointer to a destination buffer.
7494: dstlen(IN)
7495: Size of destination buffer in byte.
7496: src(IN)
7497: Pointer to a Unicode string.
7498: srclen(IN)
7499: Size of source string in characters.
7500: rsize(OUT)
7501: Number of bytes converted.
7502: If it is a NULL pointer, nothing to return.
7503: */
7504: sword OCIUnicodeToCharSet(dvoid *envhp, OraText *dst, size_t dstlen,
7505: CONST ub2 *src, size_t srclen, size_t *rsize);
7506:
7507:
7508: /* ------------------- OCICharsetConversionIsReplacementUsed ----------------*/
7509: /*
7510: NAME
7511: OCICharsetConversionIsReplacementUsed - chech if replacement is used in
7512: conversion
7513: REMARKS
7514: This function indicates whether or not the replacement character was used
7515: for nonconvertible characters in character set conversion in last invoke
7516: of OCICharsetUcs2ToMb().
7517: RETURNS
7518: TRUE is the replacement character was used in last OCICharsetUcs2ToMb()
7519: invoking, else FALSE.
7520: envhp(IN/OUT)
7521: OCI environment handle. This should be the first handle passed to
7522: OCICharsetUcs2ToMb().
7523: */
7524: boolean OCICharSetConversionIsReplacementUsed(dvoid *envhp);
7525:
7526:
7527: /*------------------------- OCIMessageOpen ----------------------------------*/
7528: /*
7529: NAME
7530: OCIMessageOpen - open a locale message file
7531: REMARKS
7532: This function opens a message handle for facility of product in a language
7533: pointed to by envhp. It first try to open the message file corresponding
7534: to envhp for the facility. If it successes, it will use that file to
7535: initialize a message handle, else it will use the default message file
7536: which is for American language for the facility. The function return a
7537: pointer pointed to a message handle into msghp parameter.
7538: RETURNS
7539: OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
7540: envhp(IN/OUT)
7541: A pointer to OCI environment handle for message language.
7542: errhp(IN/OUT)
7543: The OCI error handle. If there is an error, it is record in errhp and this
7544: function returns a NULL pointer. Diagnostic information can be obtained by
7545: calling OCIErrorGet().
7546: msghp(OUT)
7547: a message handle for return
7548: product(IN)
7549: A pointer to a product name. Product name is used to locate the directory
7550: for message in a system dependent way. For example, in Solaris, the
7551: directory of message files for the product `rdbms' is
7552: `${ORACLE_HOME}/rdbms'.
7553: facility(IN)
7554: A pointer to a facility name in the product. It is used to construct a
7555: message file name. A message file name follows the conversion with
7556: facility as prefix. For example, the message file name for facility
7557: `img' in American language will be `imgus.msb' where `us' is the
7558: abbreviation of American language and `msb' as message binary file
7559: extension.
7560: dur(IN)
7561: Duration for memory allocation for the return message handle. It can be
7562: the following values:
7563: OCI_DURATION_CALL
7564: OCI_DURATION_STATEMENT
7565: OCI_DURATION_SESSION
7566: OCI_DURATION_TRANSACTION
7567: For the detail description, please refer to Memory Related Service
7568: Interfaces section.
7569: */
7570: sword OCIMessageOpen(dvoid *envhp, OCIError *errhp, OCIMsg **msghp,
7571: CONST OraText *product, CONST OraText *facility,
7572: OCIDuration dur);
7573:
7574:
7575: /*------------------------- OCIMessageGet -----------------------------------*/
7576: /*
7577: NAME
7578: OCIMessageGet - get a locale message from a message handle
7579: REMARKS
7580: This function will get message with message number identified by msgno and
7581: if buflen is not zero, the function will copy the message into the buffer
7582: pointed to by msgbuf. If buflen is zero, the message will be copied into
7583: a message buffer inside the message handle pointed to by msgh. For both
7584: cases. it will return the pointer to the null-terminated message string.
7585: If it cannot get the message required, it will return a NULL pointer.
7586: RETURNS
7587: A pointer to a null-terminated message string on success, otherwise a NULL
7588: pointer.
7589: msgh(IN/OUT)
7590: Pointer to a message handle which was previously opened by OCIMessageOpen().
7591: msgno(IN)
7592: The message number for getting message.
7593: msgbuf(OUT)
7594: Pointer to a destination buffer to the message retrieved. If buflen is
7595: zero, it can be NULL pointer.
7596: buflen(IN)
7597: The size of the above destination buffer.
7598: */
7599: OraText *OCIMessageGet(OCIMsg *msgh, ub4 msgno, OraText *msgbuf, size_t buflen);
7600:
7601:
7602: /*------------------------- OCIMessageClose ---------------------------------*/
7603: /*
7604: NAME
7605: OCIMessageClose - close a message handle
7606: REMARKS
7607: This function closes a message handle pointed to by msgh and frees any
7608: memory associated with this handle.
7609: RETURNS
7610: OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
7611: envhp(IN/OUT)
7612: A pointer to OCI environment handle for message language.
7613: errhp(IN/OUT)
7614: The OCI error handle. If there is an error, it is record in errhp and this
7615: function returns a NULL pointer. Diagnostic information can be obtained by
7616: calling OCIErrorGet().
7617: msghp(IN/OUT)
7618: A pointer to a message handle which was previously opened by
7619: OCIMessageOpen().
7620: */
7621: sword OCIMessageClose(dvoid *envhp, OCIError *errhp, OCIMsg *msghp);
7622:
7623: /*--------------- End of Extensions to NLS cartridge service ----------------*/
7624:
7625:
7626: /*----------------- Extensions to OCI Thread interface ---------------------*/
7627: /*****************************************************************************
7628: DESCRIPTION
7629: ******************************************************************************
7630: 1 Threads Interface
7631:
7632: The OCIThread package provides a number of commonly used threading
7633: primitives for use by Oracle customers. It offers a portable interface to
7634: threading capabilities native to various platforms. It does not implement
7635: threading on platforms which do not have native threading capability.
7636:
7637: OCIThread does not provide a portable implementation of multithreaded
7638: facilities. It only serves as a set of portable covers for native
7639: multithreaded facilities. Therefore, platforms that do not have native
7640: support for multi-threading will only be able to support a limited
7641: implementation of OCIThread. As a result, products that rely on all of
7642: OCIThread's functionality will not port to all platforms. Products that must
7643: port to all platforms must use only a subset of OCIThread's functionality.
7644: This issue is discussed further in later sections of this document.
7645:
7646: The OCIThread API is split into four main parts. Each part is described
7647: briefly here. The following subsections describe each in greater detail.
7648:
7649: 1. Initialization and Termination Calls
7650:
7651: These calls deal with the initialization and termination of OCIThread.
7652: Initialization of OCIThread initializes the OCIThread context which is
7653: a member of the OCI environment or session handle. This context is
7654: required for other OCIThread calls.
7655:
7656: 2. Passive Threading Primitives
7657:
7658: The passive threading primitives include primitives to manipulate mutual
7659: exclusion (mutex) locks, thread ID's, and thread-specific data keys.
7660:
7661: The reason that these primitives are described as 'passive' is that while
7662: their specifications allow for the existence of multiple threads, they do
7663: not require it. This means that it is possible for these primitives to
7664: be implemented according to specification in both single-threaded and
7665: multi-threaded environments.
7666:
7667: As a result, OCIThread clients that use only these primitives will not
7668: require the existence of multiple threads in order to work correctly,
7669: i.e., they will be able to work in single-threaded environments without
7670: branching code.
7671:
7672: 3. Active Threading Primitives
7673:
7674: Active threading primitives include primitives dealing with the creation,
7675: termination, and other manipulation of threads.
7676:
7677: The reason that these primitives are described as 'active' is that they
7678: can only be used in true multi-threaded environments. Their
7679: specifications explicitly require that it be possible to have multiple
7680: threads. If you need to determine at runtime whether or not you are in a
7681: multi-threaded environment, call OCIThreadIsMulti() before calling an
7682: OCIThread active primitive.
7683:
7684:
7685: 1.1 Initialization & Termination
7686: ==================================
7687:
7688: The types and functions described in this section are associated with the
7689: initialization and termination of the OCIThread package. OCIThread must
7690: be properly initialized before any of its functionality can be used.
7691: OCIThread's process initialization function, 'OCIThreadProcessInit()',
7692: must be called with care; see below.
7693:
7694: The observed behavior of the initialization and termination functions is the
7695: same regardless of whether OCIThread is in single-threaded or multi-threaded
7696: environment. It is OK to call the initialization functions from both generic
7697: and operating system specific (OSD) code.
7698:
7699: 1.1.1 Types
7700:
7701: OCIThreadContext - OCIThread Context
7702: -------------------------------------
7703:
7704: Most calls to OCIThread functions take the OCI environment or session
7705: handle as a parameter. The OCIThread context is part of the OCI
7706: environment or session handle and it must be initialized by calling
7707: 'OCIThreadInit()'. Termination of the OCIThread context occurs by calling
7708: 'OCIThreadTerm()'.
7709:
7710: The OCIThread context is a private data structure. Clients must NEVER
7711: attempt to examine the contents of the context.
7712:
7713: 1.1.2 OCIThreadProcessInit
7714:
7715: OCIThreadProcessInit - OCIThread Process INITialization
7716: --------------------------------------------------------
7717:
7718: Description
7719:
7720: This function should be called to perform OCIThread process
7721: initialization.
7722:
7723: Prototype
7724:
7725: void OCIThreadProcessInit();
7726:
7727: Returns
7728:
7729: Nothing.
7730:
7731: Notes
7732:
7733: Whether or not this function needs to be called depends on how OCI
7734: Thread is going to be used.
7735:
7736: * In a single-threaded application, calling this function is optional.
7737: If it is called at all, the first call to it must occur before calls
7738: to any other OCIThread functions. Subsequent calls can be made
7739: without restriction; they will not have any effect.
7740:
7741: * In a multi-threaded application, this function MUST be called. The
7742: first call to it MUST occur 'strictly before' any other OCIThread
7743: calls; i.e., no other calls to OCIThread functions (including other
7744: calls to this one) can be concurrent with the first call.
7745: Subsequent calls to this function can be made without restriction;
7746: they will not have any effect.
7747:
7748:
7749: 1.1.3 OCIThreadInit
7750:
7751: OCIThreadInit - OCIThread INITialize
7752: -------------------------------------
7753:
7754: Description
7755:
7756: This initializes OCIThread context.
7757:
7758: Prototype
7759:
7760: sword OCIThreadInit(dvoid *hndl, OCIError *err);
7761:
7762: hndl(IN/OUT): The OCI environment or session handle.
7763:
7764: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
7765: is returned, the error is recorded in err and diagnostic
7766: information can be obtained by calling OCIErrorGet().
7767:
7768: Returns
7769:
7770: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
7771:
7772: Notes
7773:
7774: It is illegal for OCIThread clients to try an examine the memory
7775: pointed to by the returned pointer.
7776:
7777: It is safe to make concurrent calls to 'OCIThreadInit()'. Unlike
7778: 'OCIThreadProcessInit()', there is no need to have a first call
7779: that occurs before all the others.
7780:
7781: The first time 'OCIThreadInit()' is called, it initilaizes the OCI
7782: Thread context. It also saves a pointer to the context in some system
7783: dependent manner. Subsequent calls to 'OCIThreadInit()' will return
7784: the same context.
7785:
7786: Each call to 'OCIThreadInit()' must eventually be matched by a call to
7787: 'OCIThreadTerm()'.
7788:
7789: OCIThreadTerm - OCIThread TERMinate
7790: ------------------------------------
7791:
7792: Description
7793:
7794: This should be called to release the OCIThread context. It should be
7795: called exactly once for each call made to 'OCIThreadInit()'.
7796:
7797: Prototype
7798:
7799: sword OCIThreadTerm(dvoid *hndl, OCIError *err);
7800:
7801: hndl(IN/OUT): The OCI environment or session handle.
7802:
7803: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
7804: is returned, the error is recorded in err and diagnostic
7805: information can be obtained by calling OCIErrorGet().
7806:
7807: Returns
7808:
7809: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
7810:
7811: Notes
7812:
7813: It is safe to make concurrent calls to 'OCIThreadTerm()'.
7814:
7815: 'OCIThreadTerm()' will not do anything until it has been called as
7816: many times as 'OCIThreadInit()' has been called. When that happens,
7817: it terminates the OCIThread layer and frees the memory allocated for
7818: the context. Once this happens, the context should not be re-used.
7819: It will be necessary to obtain a new one by calling 'OCIThreadInit()'.
7820:
7821:
7822: OCIThreadIsMulti - OCIThread Is Multi-Threaded?
7823: ------------------------------------------------
7824:
7825: Description
7826:
7827: This tells the caller whether the application is running in a
7828: multi-threaded environment or a single-threaded environment.
7829:
7830: Prototype
7831: boolean OCIThreadIsMulti(void);
7832:
7833: Returns
7834:
7835: TRUE if the environment is multi-threaded;
7836: FALSE if the environment is single-threaded.
7837:
7838:
7839: 1.2 Passive Threading Primitives
7840: ==================================
7841:
7842: 1.2.1 Types
7843:
7844: The passive threading primitives deal with the manipulation of mutex,
7845: thread ID's, and thread-specific data. Since the specifications of these
7846: primitives do not require the existence of multiple threads, they can be
7847: used both on multithreaded and single-threaded platforms.
7848:
7849: 1.2.1.1 OCIThreadMutex - OCIThread Mutual Exclusion Lock
7850: -----------------------------------------------------------
7851:
7852: The type 'OCIThreadMutex' is used to represent a mutual exclusion lock
7853: (mutex). A mutex is typically used for one of two purposes: (i) to
7854: ensure that only one thread accesses a given set of data at a time, or
7855: (ii) to ensure that only one thread executes a given critical section of
7856: code at a time.
7857:
7858: Mutexes pointer can be declared as parts of client structures or as
7859: stand-alone variables. Before they can be used, they must be initialized
7860: using 'OCIThreadMutexInit()'. Once they are no longer needed, they must be
7861: destroyed using 'OCIThreadMutexDestroy()'. A mutex pointer must NOT be
7862: used after it is destroyed.
7863:
7864: A thread can acquire a mutex by using either 'OCIThreadMutexAcquire()' or
7865: 'OCIThreadMutexTry()'. They both ensure that only one thread at a time is
7866: allowed to hold a given mutex. A thread that holds a mutex can release it
7867: by calling 'OCIThreadMutexRelease()'.
7868:
7869:
7870: 1.2.1.2 OCIThreadKey - OCIThread Key for Thread-Specific Data
7871: ----------------------------------------------------------------
7872:
7873: A key can be thought of as a process-wide variable that has a
7874: thread-specific value. What this means is that all the threads in a
7875: process can use any given key. However, each thread can examine or modify
7876: that key independently of the other threads. The value that a thread sees
7877: when it examines the key will always be the same as the value that it last
7878: set for the key. It will not see any values set for the key by the other
7879: threads.
7880:
7881: The type of the value held by a key is a 'dvoid *' generic pointer.
7882:
7883: Keys can be created using 'OCIThreadKeyInit()'. When a key is created, its
7884: value is initialized to 'NULL' for all threads.
7885:
7886: A thread can set a key's value using 'OCIThreadKeySet()'. A thread can
7887: get a key's value using 'OCIThreadKeyGet()'.
7888:
7889: The OCIThread key functions will save and retrieve data SPECIFIC TO THE
7890: THREAD. When clients maintain a pool of threads and assign the threads to
7891: different tasks, it *may not* be appropriate for a task to use OCIThread
7892: key functions to save data associated with it. Here is a scenario of how
7893: things can fail: A thread is assigned to execute the initialization of a
7894: task. During the initialization, the task stored some data related to it
7895: in the thread using OCIThread key functions. After the initialization,
7896: the thread is returned back to the threads pool. Later, the threads pool
7897: manager assigned another thread to perform some operations on the task,
7898: and the task needs to retrieve those data it stored earlier in
7899: initialization. Since the task is running in another thread, it will not
7900: be able to retrieve the same data back! Applications that use thread
7901: pools should be aware of this and be cautious when using OCIThread key
7902: functions.
7903:
7904:
7905: 1.2.1.3 OCIThreadKeyDestFunc - OCIThread Key Destructor Function Type
7906: ------------------------------------------------------------------------
7907:
7908: This is the type of a pointer to a key's destructor routine. Keys can be
7909: associated with a destructor routine when they are created (see
7910: 'OCIThreadKeyInit()').
7911:
7912: A key's destructor routine will be called whenever a thread that has a
7913: non-NULL value for the key terminates.
7914:
7915: The destructor routine returns nothing and takes one parameter. The
7916: parameter will be the value that was set for key when the thread
7917: terminated.
7918:
7919: The destructor routine is guaranteed to be called on a thread's value
7920: in the key after the termination of the thread and before process
7921: termination. No more precise guarantee can be made about the timing
7922: of the destructor routine call; thus no code in the process may assume
7923: any post-condition of the destructor routine. In particular, the
7924: destructor is not guaranteed to execute before a join call on the
7925: terminated thread returns.
7926:
7927:
7928: 1.2.1.4 OCIThreadId - OCIThread Thread ID
7929: --------------------------------------------
7930:
7931: Type 'OCIThreadId' is the type that will be used to identify a thread.
7932: At any given time, no two threads will ever have the same 'OCIThreadId'.
7933: However, 'OCIThreadId' values can be recycled; i.e., once a thread dies,
7934: a new thread may be created that has the same 'OCIThreadId' as the one
7935: that died. In particular, the thread ID must uniquely identify a thread
7936: T within a process, and it must be consistent and valid in all threads U
7937: of the process for which it can be guaranteed that T is running
7938: concurrently with U. The thread ID for a thread T must be retrievable
7939: within thread T. This will be done via OCIThreadIdGet().
7940:
7941: The 'OCIThreadId' type supports the concept of a NULL thread ID: the NULL
7942: thread ID will never be the same as the ID of an actual thread.
7943:
7944:
7945:
7946: 1.2.2 Function prototypes for passive primitives
7947: --------------------------------------------------
7948:
7949: 1.2.2.1 Mutex functions
7950: -------------------------
7951:
7952: OCIThreadMutexInit - OCIThread MuteX Initialize
7953: -----------------------------------------------
7954:
7955: Description
7956:
7957: This allocate and initializes a mutex. All mutexes must be
7958: initialized prior to use.
7959:
7960: Prototype
7961:
7962: sword OCIThreadMutexInit(dvoid *hndl, OCIError *err,
7963: OCIThreadMutex **mutex);
7964:
7965: hndl(IN/OUT): The OCI environment or session handle.
7966:
7967: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
7968: is returned, the error is recorded in err and diagnostic
7969: information can be obtained by calling OCIErrorGet().
7970:
7971: mutex(OUT): The mutex to initialize.
7972:
7973: Returns
7974:
7975: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
7976:
7977: Notes
7978:
7979: Multiple threads must not initialize the same mutex simultaneously.
7980: Also, a mutex must not be reinitialized until it has been destroyed (see
7981: 'OCIThreadMutexDestroy()').
7982:
7983: OCIThreadMutexDestroy - OCIThread MuteX Destroy
7984: -----------------------------------------------
7985:
7986: Description
7987:
7988: This destroys and deallocate a mutex. Each mutex must be destroyed
7989: once it is no longer needed.
7990:
7991: Prototype
7992:
7993: sword OCIThreadMutexDestroy(dvoid *hndl, OCIError *err,
7994: OCIThreadMutex **mutex);
7995:
7996: hndl(IN/OUT): The OCI environment or session handle.
7997:
7998: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
7999: is returned, the error is recorded in err and diagnostic
8000: information can be obtained by calling OCIErrorGet().
8001:
8002: mutex(IN/OUT): The mutex to destroy.
8003:
8004: Returns
8005:
8006: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8007:
8008: Notes
8009:
8010: It is not legal to destroy a mutex that is uninitialized or is currently
8011: held by a thread. The destruction of a mutex must not occur concurrently
8012: with any other operations on the mutex. A mutex must not be used after
8013: it has been destroyed.
8014:
8015:
8016: OCIThreadMutexAcquire - OCIThread MuteX Acquire
8017: -----------------------------------------------
8018:
8019: Description
8020:
8021: This acquires a mutex for the thread in which it is called. If the mutex
8022: is held by another thread, the calling thread is blocked until it can
8023: acquire the mutex.
8024:
8025: Prototype
8026:
8027: sword OCIThreadMutexAcquire(dvoid *hndl, OCIError *err,
8028: OCIThreadMutex *mutex);
8029:
8030: hndl(IN/OUT): The OCI environment or session handle.
8031:
8032: err(IN/OUT): The OCI error handle. If there is an error, it is
8033: recorded in err and this function returns OCI_ERROR.
8034: Diagnostic information can be obtained by calling
8035: OCIErrorGet().
8036:
8037: mutex(IN/OUT): The mutex to acquire.
8038:
8039: Returns
8040:
8041: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8042:
8043: Notes
8044:
8045: It is illegal to attempt to acquire an uninitialized mutex.
8046:
8047: This function's behavior is undefined if it is used by a thread to
8048: acquire a mutex that is already held by that thread.
8049:
8050:
8051:
8052: OCIThreadMutexRelease - OCIThread MuteX Release
8053: -----------------------------------------------
8054:
8055: Description
8056:
8057: This releases a mutex. If there are any threads blocked on the mutex,
8058: one of them will acquire it and become unblocked.
8059:
8060: Prototype
8061:
8062: sword OCIThreadMutexRelease(dvoid *hndl, OCIError *err,
8063: OCIThreadMutex *mutex);
8064:
8065: hndl(IN/OUT): The OCI environment or session handle.
8066:
8067: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8068: is returned, the error is recorded in err and diagnostic
8069: information can be obtained by calling OCIErrorGet().
8070:
8071: mutex(IN/OUT): The mutex to release.
8072:
8073: Returns
8074:
8075: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8076:
8077: Notes
8078:
8079: It is illegal to attempt to release an uninitialized mutex. It is also
8080: illegal for a thread to release a mutex that it does not hold.
8081:
8082:
8083: OCIThreadKeyInit - OCIThread KeY Initialize
8084: -------------------------------------------
8085:
8086: Description
8087:
8088: This creates a key. Each call to this routine allocate and generates
8089: a new key that is distinct from all other keys.
8090:
8091: Prototype
8092:
8093: sword OCIThreadKeyInit(dvoid *hndl, OCIError *err, OCIThreadKey **key,
8094: OCIThreadKeyDestFunc destFn);
8095:
8096: hndl(IN/OUT): The OCI environment or session handle.
8097:
8098: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8099: is returned, the error is recorded in err and diagnostic
8100: information can be obtained by calling OCIErrorGet().
8101:
8102: key(OUT): The 'OCIThreadKey' in which to create the new key.
8103:
8104: destFn(IN): The destructor for the key. NULL is permitted.
8105:
8106: Returns
8107:
8108: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8109:
8110: Notes
8111:
8112: Once this function executes successfully, a pointer to an allocated and
8113: initialized key is return. That key can be used with 'OCIThreadKeyGet()'
8114: and 'OCIThreadKeySet()'. The initial value of the key will be 'NULL' for
8115: all threads.
8116:
8117: It is illegal for this function to be called more than once to create the
8118: same key (i.e., to be called more than once with the same value for the
8119: 'key' parameter).
8120:
8121: If the 'destFn' parameter is not NULL, the routine pointed to by 'destFn'
8122: will be called whenever a thread that has a non-NULL value for the key
8123: terminates. The routine will be called with one parameter. The
8124: parameter will be the key's value for the thread at the time at which the
8125: thread terminated.
8126: If the key does not need a destructor function, pass NULL for 'destFn'.
8127:
8128:
8129: OCIThreadKeyDestroy - OCIThread KeY DESTROY
8130: -------------------------------------------
8131:
8132: Description
8133:
8134: Destroy and deallocate the key pointed to by 'key'.
8135:
8136: Prototype
8137:
8138: sword OCIThreadKeyDestroy(dvoid *hndl, OCIError *err,
8139: OCIThreadKey **key);
8140:
8141: hndl(IN/OUT): The OCI environment or session handle.
8142:
8143: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8144: is returned, the error is recorded in err and diagnostic
8145: information can be obtained by calling OCIErrorGet().
8146:
8147: key(IN/OUT): The 'OCIThreadKey' in which to destroy the key.
8148:
8149: Returns
8150:
8151: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8152:
8153: Notes
8154:
8155: This is different from the destructor function callback passed to the
8156: key create routine. This new destroy function 'OCIThreadKeyDestroy' is
8157: used to terminate any resources OCI THREAD acquired when it created
8158: 'key'. [The 'OCIThreadKeyDestFunc' callback type is a key VALUE
8159: destructor; it does in no way operate on the key itself.]
8160:
8161: This must be called once the user has finished using the key. Not
8162: calling the key destroy function may result in memory leaks.
8163:
8164:
8165:
8166:
8167: 1.2.2.2 Thread Key operations
8168: -------------------------------
8169:
8170: OCIThreadKeyGet - OCIThread KeY Get value
8171: -----------------------------------------
8172:
8173: Description
8174:
8175: This gets the calling thread's current value for a key.
8176:
8177: Prototype
8178:
8179: sword OCIThreadKeyGet(dvoid *hndl, OCIError *err, OCIThreadKey *key,
8180: dvoid **pValue);
8181:
8182: hndl(IN/OUT): The OCI environment or session handle.
8183:
8184: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8185: is returned, the error is recorded in err and diagnostic
8186: information can be obtained by calling OCIErrorGet().
8187:
8188: key(IN): The key.
8189:
8190: pValue(IN/OUT): The location in which to place the thread-specific
8191: key value.
8192:
8193: Returns
8194:
8195: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8196:
8197: Notes
8198:
8199: It is illegal to use this function on a key that has not been created
8200: using 'OCIThreadKeyInit()'.
8201:
8202: If the calling thread has not yet assigned a value to the key, 'NULL' is
8203: placed in the location pointed to by 'pValue'.
8204:
8205:
8206: OCIThreadKeySet - OCIThread KeY Set value
8207: -----------------------------------------
8208:
8209: Description
8210:
8211: This sets the calling thread's value for a key.
8212:
8213: Prototype
8214:
8215: sword OCIThreadKeySet(dvoid *hndl, OCIError *err, OCIThreadKey *key,
8216: dvoid *value);
8217:
8218: hndl(IN/OUT): The OCI environment or session handle.
8219:
8220: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8221: is returned, the error is recorded in err and diagnostic
8222: information can be obtained by calling OCIErrorGet().
8223:
8224: key(IN/OUT): The key.
8225:
8226: value(IN): The thread-specific value to set in the key.
8227:
8228: Returns
8229:
8230: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8231:
8232: Notes
8233:
8234: It is illegal to use this function on a key that has not been created
8235: using 'OCIThreadKeyInit()'.
8236:
8237: 1.2.2.3 Thread Id
8238: --------------------
8239:
8240: OCIThreadIdInit - OCIThread Thread Id INITialize
8241: --------------------------------------------------
8242:
8243: Description
8244:
8245: Allocate and initialize the thread id 'tid'.
8246:
8247: Prototype
8248:
8249: sword OCIThreadIdInit(dvoid *hndl, OCIError *err, OCIThreadId **tid);
8250:
8251: hndl(IN/OUT): The OCI environment or session handle.
8252:
8253: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8254: is returned, the error is recorded in err and diagnostic
8255: information can be obtained by calling OCIErrorGet().
8256:
8257: tid (OUT): Pointer to the thread ID to initialize.
8258:
8259: Returns
8260:
8261: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8262:
8263:
8264: OCIThreadIdDestroy - OCIThread Thread Id DESTROY
8265: --------------------------------------------------
8266:
8267: Description
8268:
8269: Destroy and deallocate the thread id 'tid'.
8270:
8271: Prototype
8272:
8273: sword OCIThreadIdDestroy(dvoid *hndl, OCIError *err, OCIThreadId **tid);
8274:
8275: hndl(IN/OUT): The OCI environment or session handle.
8276:
8277: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8278: is returned, the error is recorded in err and diagnostic
8279: information can be obtained by calling OCIErrorGet().
8280:
8281: tid(IN/OUT): Pointer to the thread ID to destroy.
8282:
8283: Returns
8284:
8285: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8286:
8287: Note
8288:
8289: 'tid' should be initialized by OCIThreadIdInit().
8290:
8291:
8292: OCIThreadIdSet - OCIThread Thread Id Set
8293: -----------------------------------------
8294:
8295: Description
8296:
8297: This sets one 'OCIThreadId' to another.
8298:
8299: Prototype
8300:
8301: sword OCIThreadIdSet(dvoid *hndl, OCIError *err,
8302: OCIThreadId *tidDest,
8303: OCIThreadId *tidSrc);
8304:
8305: hndl(IN/OUT): The OCI environment or session handle.
8306:
8307: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8308: is returned, the error is recorded in err and diagnostic
8309: information can be obtained by calling OCIErrorGet().
8310:
8311: tidDest(OUT): This should point to the location of the 'OCIThreadId'
8312: to be set to.
8313:
8314: tidSrc(IN): This should point to the 'OCIThreadId' to set from.
8315:
8316: Returns
8317:
8318: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8319:
8320: Notes
8321:
8322: 'tid' should be initialized by OCIThreadIdInit().
8323:
8324:
8325: OCIThreadIdSetNull - OCIThread Thread Id Set Null
8326: ---------------------------------------------------------
8327:
8328: Description
8329:
8330: This sets the NULL thread ID to a given 'OCIThreadId'.
8331:
8332: Prototype
8333:
8334: sword OCIThreadIdSetNull(dvoid *hndl, OCIError *err,
8335: OCIThreadId *tid);
8336:
8337: hndl(IN/OUT): The OCI environment or session handle.
8338:
8339: err(IN/OUT): The OCI error handle. If there is an error, it is
8340: recorded in err and this function returns OCI_ERROR.
8341: Diagnostic information can be obtained by calling
8342: OCIErrorGet().
8343:
8344: tid(OUT): This should point to the 'OCIThreadId' in which to put
8345: the NULL thread ID.
8346:
8347: Returns
8348:
8349: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8350:
8351: Notes
8352:
8353: 'tid' should be initialized by OCIThreadIdInit().
8354:
8355:
8356: OCIThreadIdGet - OCIThread Thread Id Get
8357: ------------------------------------------
8358:
8359: Description
8360:
8361: This retrieves the 'OCIThreadId' of the thread in which it is called.
8362:
8363: Prototype
8364:
8365: sword OCIThreadIdGet(dvoid *hndl, OCIError *err,
8366: OCIThreadId *tid);
8367:
8368: hndl(IN/OUT): The OCI environment or session handle.
8369:
8370: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8371: is returned, the error is recorded in err and diagnostic
8372: information can be obtained by calling OCIErrorGet().
8373:
8374: tid(OUT): This should point to the location in which to place the
8375: ID of the calling thread.
8376:
8377: Returns
8378:
8379: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8380:
8381: Notes
8382:
8383: 'tid' should be initialized by OCIThreadIdInit().
8384:
8385: When OCIThread is used in a single-threaded environment,
8386: OCIThreadIdGet() will always place the same value in the location
8387: pointed to by 'tid'. The exact value itself is not important. The
8388: important thing is that it is not the same as the NULL thread ID and
8389: that it is always the same value.
8390:
8391:
8392: OCIThreadIdSame - OCIThread Thread Ids Same?
8393: ----------------------------------------------
8394:
8395: Description
8396:
8397: This determines whether or not two 'OCIThreadId's represent the same
8398: thread.
8399:
8400: Prototype
8401:
8402: sword OCIThreadIdSame(dvoid *hndl, OCIError *err,
8403: OCIThreadId *tid1, OCIThreadId *tid2,
8404: boolean *result);
8405:
8406: hndl(IN/OUT): The OCI environment or session handle.
8407:
8408: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8409: is returned, the error is recorded in err and diagnostic
8410: information can be obtained by calling OCIErrorGet().
8411:
8412: tid1(IN): Pointer to the first 'OCIThreadId'.
8413:
8414: tid2(IN): Pointer to the second 'OCIThreadId'.
8415:
8416: result(IN/OUT): Pointer to the result.
8417:
8418: Returns
8419:
8420: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8421:
8422: Notes
8423:
8424: If 'tid1' and 'tid2' represent the same thread, 'result' is set to TRUE.
8425: Otherwise, 'result' is set to FALSE.
8426:
8427: 'result' is set to TRUE if both 'tid1' and 'tid2' are the NULL thread ID.
8428:
8429: 'ti1d' and 'tid2' should be initialized by OCIThreadIdInit().
8430:
8431:
8432: OCIThreadIdNull - OCIThread Thread Id NULL?
8433: ---------------------------------------------
8434:
8435: Description
8436:
8437: This determines whether or not a given 'OCIThreadId' is the NULL thread
8438: ID.
8439:
8440: Prototype
8441:
8442: sword OCIThreadIdNull(dvoid *hndl, OCIError *err,
8443: OCIThreadId *tid,
8444: boolean *result);
8445:
8446: hndl(IN/OUT): The OCI environment or session handle.
8447:
8448: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8449: is returned, the error is recorded in err and diagnostic
8450: information can be obtained by calling OCIErrorGet().
8451:
8452: tid(IN): Pointer to the 'OCIThreadId' to check.
8453:
8454: result(IN/OUT): Pointer to the result.
8455:
8456: Returns
8457:
8458: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8459:
8460: Notes
8461:
8462: If 'tid' is the NULL thread ID, 'result' is set to TRUE. Otherwise,
8463: 'result' is set to FALSE.
8464:
8465: 'tid' should be initialized by OCIThreadIdInit().
8466:
8467:
8468: 1.3 Active Threading Primitives
8469: =================================
8470:
8471: The active threading primitives deal with the manipulation of actual
8472: threads. Because the specifications of most of these primitives require
8473: that it be possible to have multiple threads, they work correctly only in
8474: the enabled OCIThread; In the disabled OCIThread, they always return
8475: failure. The exception is OCIThreadHandleGet(); it may be called in a
8476: single-threaded environment, in which case it will have no effect.
8477:
8478: Active primitives should only be called by code running in a multi-threaded
8479: environment. You can call OCIThreadIsMulti() to determine whether the
8480: environment is multi-threaded or single-threaded.
8481:
8482:
8483: 1.3.1 Types
8484: --------------
8485:
8486: 1.3.1.1 OCIThreadHandle - OCIThread Thread Handle
8487: ------------------------------------------------------
8488:
8489: Type 'OCIThreadHandle' is used to manipulate a thread in the active
8490: primitives: OCIThreadJoin()and OCIThreadClose(). A thread handle opened by
8491: OCIThreadCreate() must be closed in a matching call to
8492: OCIThreadClose(). A thread handle is invalid after the call to
8493: OCIThreadClose().
8494:
8495: The distinction between a thread ID and a thread handle in OCIThread usage
8496: follows the distinction between the thread ID and the thread handle on
8497: Windows NT. On many platforms, the underlying native types are the same.
8498:
8499:
8500: 1.3.2 Functions
8501: ------------------
8502:
8503: OCIThreadHndInit - OCIThread HaNDle Initialize
8504: ----------------------------------------------
8505:
8506: Description
8507:
8508: Allocate and initialize the thread handle.
8509:
8510: Prototype
8511:
8512: sword OCIThreadHndInit(dvoid *hndl, OCIError *err,
8513: OCIThreadHandle **thnd);
8514:
8515: hndl(IN/OUT): The OCI environment or session handle.
8516:
8517: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8518: is returned, the error is recorded in err and diagnostic
8519: information can be obtained by calling OCIErrorGet().
8520:
8521: thnd(OUT): The address of pointer to the thread handle to initialize.
8522:
8523: Returns
8524:
8525: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8526:
8527:
8528: OCIThreadHndDestroy - OCIThread HaNDle Destroy
8529: ----------------------------------------------
8530:
8531: Description
8532:
8533: Destroy and deallocate the thread handle.
8534:
8535: Prototype
8536:
8537: sword OCIThreadHndDestroy(dvoid *hndl, OCIError *err,
8538: OCIThreadHandle **thnd);
8539:
8540: hndl(IN/OUT): The OCI environment or session handle.
8541:
8542: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8543: is returned, the error is recorded in err and diagnostic
8544: information can be obtained by calling OCIErrorGet().
8545:
8546: thnd(IN/OUT): The address of pointer to the thread handle to destroy.
8547:
8548: Returns
8549:
8550: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8551:
8552: Notes
8553:
8554: 'thnd' should be initialized by OCIThreadHndInit().
8555:
8556:
8557: OCIThreadCreate - OCIThread Thread Create
8558: -----------------------------------------
8559:
8560: Description
8561:
8562: This creates a new thread.
8563:
8564: Prototype
8565:
8566: sword OCIThreadCreate(dvoid *hndl, OCIError *err,
8567: void (*start)(dvoid *), dvoid *arg,
8568: OCIThreadId *tid, OCIThreadHandle *tHnd);
8569:
8570: hndl(IN/OUT): The OCI environment or session handle.
8571:
8572: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8573: is returned, the error is recorded in err and diagnostic
8574: information can be obtained by calling OCIErrorGet().
8575:
8576: start(IN): The function in which the new thread should begin
8577: execution.
8578:
8579: arg(IN): The argument to give the function pointed to by 'start'.
8580:
8581: tid(IN/OUT): If not NULL, gets the ID for the new thread.
8582:
8583: tHnd(IN/OUT): If not NULL, gets the handle for the new thread.
8584:
8585: Returns
8586:
8587: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8588:
8589: Notes
8590:
8591: The new thread will start by executing a call to the function pointed
8592: to by 'start' with the argument given by 'arg'. When that function
8593: returns, the new thread will terminate. The function should not
8594: return a value and should accept one parameter, a 'dvoid *'.
8595:
8596: The call to OCIThreadCreate() must be matched by a call to
8597: OCIThreadClose() if and only if tHnd is non-NULL.
8598:
8599: If tHnd is NULL, a thread ID placed in *tid will not be valid in the
8600: calling thread because the timing of the spawned thread's termination
8601: is unknown.
8602:
8603: 'tid' should be initialized by OCIThreadIdInit().
8604:
8605: 'thnd' should be initialized by OCIThreadHndInit().
8606:
8607:
8608:
8609: OCIThreadJoin - OCIThread Thread Join
8610: -------------------------------------
8611:
8612: Description
8613:
8614: This function allows the calling thread to 'join' with another thread.
8615: It blocks the caller until the specified thread terminates.
8616:
8617: Prototype
8618:
8619: sword OCIThreadJoin(dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd);
8620:
8621: hndl(IN/OUT): The OCI environment or session handle.
8622:
8623: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8624: is returned, the error is recorded in err and diagnostic
8625: information can be obtained by calling OCIErrorGet().
8626:
8627: tHnd(IN): The 'OCIThreadHandle' of the thread to join with.
8628:
8629: Returns
8630:
8631: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8632:
8633: Notes
8634:
8635: 'thnd' should be initialized by OCIThreadHndInit().
8636:
8637: The result of multiple threads all trying to join with the same thread is
8638: undefined.
8639:
8640:
8641: OCIThreadClose - OCIThread Thread Close
8642: ---------------------------------------
8643:
8644: Description
8645:
8646: This function should be called to close a thread handle.
8647:
8648: Prototype
8649:
8650: sword OCIThreadClose(dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd);
8651:
8652: hndl(IN/OUT): The OCI environment or session handle.
8653:
8654: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8655: is returned, the error is recorded in err and diagnostic
8656: information can be obtained by calling OCIErrorGet().
8657:
8658: tHnd(IN/OUT): The OCIThread thread handle to close.
8659:
8660: Returns
8661:
8662: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8663:
8664: Notes
8665:
8666: 'thnd' should be initialized by OCIThreadHndInit().
8667:
8668: Both thread handle and the thread ID that was returned by the same call
8669: to OCIThreadCreate() are invalid after the call to OCIThreadClose().
8670:
8671:
8672:
8673: OCIThreadHandleGet - OCIThread Thread Get Handle
8674: ------------------------------------------------
8675:
8676: Description
8677:
8678: Retrieve the 'OCIThreadHandle' of the thread in which it is called.
8679:
8680: Prototype
8681:
8682: sword OCIThreadHandleGet(dvoid *hndl, OCIError *err,
8683: OCIThreadHandle *tHnd);
8684:
8685: hndl(IN/OUT): The OCI environment or session handle.
8686:
8687: err(IN/OUT): The OCI error handle. If there is an error and OCI_ERROR
8688: is returned, the error is recorded in err and diagnostic
8689: information can be obtained by calling OCIErrorGet().
8690:
8691: tHnd(IN/OUT): If not NULL, the location to place the thread
8692: handle for the thread.
8693:
8694: Returns
8695:
8696: OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
8697:
8698: Notes
8699:
8700: 'thnd' should be initialized by OCIThreadHndInit().
8701:
8702: The thread handle 'tHnd' retrieved by this function must be closed
8703: with OCIThreadClose() and destroyed by OCIThreadHndDestroy() after it
8704: is used.
8705:
8706:
8707:
8708:
8709: 1.4 Using OCIThread
8710: =====================
8711:
8712: This section summarizes some of the more important details relating to the use
8713: of OCIThread.
8714:
8715: * Process initialization
8716:
8717: OCIThread only requires that the process initialization function
8718: ('OCIThreadProcessInit()') be called when OCIThread is being used in a
8719: multi-threaded application. Failing to call 'OCIThreadProcessInit()' in
8720: a single-threaded application is not an error.
8721:
8722: * OCIThread initialization
8723:
8724: Separate calls to 'OCIThreadInit()' will all return the same OCIThread
8725: context.
8726:
8727: Also, remember that each call to 'OCIThreadInit()' must eventually be
8728: matched by a call to 'OCIThreadTerm()'.
8729:
8730: * Active vs. Passive Threading primitives
8731:
8732: OCIThread client code written without using any active primitives can be
8733: compiled and used without change on both single-threaded and
8734: multi-threaded platforms.
8735:
8736: OCIThread client code written using active primitives will only work
8737: correctly on multi-threaded platforms. In order to write a version of the
8738: same application to run on single-threaded platform, it is necessary to
8739: branch the your code, whether by branching versions of the source file or
8740: by branching at runtime with the OCIThreadIsMulti() call.
8741:
8742: ******************************************************************************/
8743:
8744: /*****************************************************************************
8745: ACTUAL PROTOTYPE DECLARATIONS
8746: ******************************************************************************/
8747:
8748: void OCIThreadProcessInit();
8749:
8750: sword OCIThreadInit(dvoid *hndl, OCIError *err);
8751:
8752: sword OCIThreadTerm(dvoid *hndl, OCIError *err);
8753:
8754: boolean OCIThreadIsMulti();
8755:
8756: sword OCIThreadMutexInit(dvoid *hndl, OCIError *err,
8757: OCIThreadMutex **mutex);
8758:
8759: sword OCIThreadMutexDestroy(dvoid *hndl, OCIError *err,
8760: OCIThreadMutex **mutex);
8761:
8762: sword OCIThreadMutexAcquire(dvoid *hndl, OCIError *err,
8763: OCIThreadMutex *mutex);
8764:
8765: sword OCIThreadMutexRelease(dvoid *hndl, OCIError *err,
8766: OCIThreadMutex *mutex);
8767:
8768: sword OCIThreadKeyInit(dvoid *hndl, OCIError *err, OCIThreadKey **key,
8769: OCIThreadKeyDestFunc destFn);
8770:
8771: sword OCIThreadKeyDestroy(dvoid *hndl, OCIError *err,
8772: OCIThreadKey **key);
8773:
8774: sword OCIThreadKeyGet(dvoid *hndl, OCIError *err, OCIThreadKey *key,
8775: dvoid **pValue);
8776:
8777: sword OCIThreadKeySet(dvoid *hndl, OCIError *err, OCIThreadKey *key,
8778: dvoid *value);
8779:
8780: sword OCIThreadIdInit(dvoid *hndl, OCIError *err, OCIThreadId **tid);
8781:
8782: sword OCIThreadIdDestroy(dvoid *hndl, OCIError *err, OCIThreadId **tid);
8783:
8784: sword OCIThreadIdSet(dvoid *hndl, OCIError *err,
8785: OCIThreadId *tidDest, OCIThreadId *tidSrc);
8786:
8787: sword OCIThreadIdSetNull(dvoid *hndl, OCIError *err, OCIThreadId *tid);
8788:
8789: sword OCIThreadIdGet(dvoid *hndl, OCIError *err, OCIThreadId *tid);
8790:
8791: sword OCIThreadIdSame(dvoid *hndl, OCIError *err,
8792: OCIThreadId *tid1, OCIThreadId *tid2,
8793: boolean *result);
8794:
8795: sword OCIThreadIdNull(dvoid *hndl, OCIError *err,
8796: OCIThreadId *tid, boolean *result);
8797:
8798: sword OCIThreadHndInit(dvoid *hndl, OCIError *err, OCIThreadHandle **thnd);
8799:
8800: sword OCIThreadHndDestroy(dvoid *hndl, OCIError *err, OCIThreadHandle **thnd);
8801:
8802: sword OCIThreadCreate(dvoid *hndl, OCIError *err,
8803: void (*start)(dvoid *), dvoid *arg,
8804: OCIThreadId *tid, OCIThreadHandle *tHnd);
8805:
8806: sword OCIThreadJoin(dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd);
8807:
8808: sword OCIThreadClose(dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd);
8809:
8810: sword OCIThreadHandleGet(dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd);
8811: /*----------------- End OCI Thread interface Extensions ---------------------*/
8812:
8813: /*--------------- Begin OCI Client Notification Interfaces ------------------*/
8814:
8815: typedef ub4 (*OCISubscriptionNotify)(dvoid *ctx, OCISubscription *subscrhp,
8816: dvoid *pay, ub4 payl,
8817: dvoid *desc, ub4 mode);
8818:
8819: sword OCISubscriptionRegister(OCISvcCtx *svchp, OCISubscription **subscrhpp,
8820: ub2 count, OCIError *errhp, ub4 mode);
8821:
8822:
8823: sword OCISubscriptionPost(OCISvcCtx *svchp, OCISubscription **subscrhpp,
8824: ub2 count, OCIError *errhp, ub4 mode);
8825:
8826: sword OCISubscriptionUnRegister(OCISvcCtx *svchp, OCISubscription *subscrhp,
8827: OCIError *errhp, ub4 mode);
8828:
8829: sword OCISubscriptionDisable(OCISubscription *subscrhp,
8830: OCIError *errhp, ub4 mode);
8831:
8832: sword OCISubscriptionEnable(OCISubscription *subscrhp,
8833: OCIError *errhp, ub4 mode);
8834:
8835: /*------------------- End OCI Publish/Subscribe Interfaces ------------------*/
8836:
8837: /*----------------- Extensions to Datetime interfaces -----------------------*/
8838: /*--------------------- Actual Prototypes -----------------------------------*/
8839: sword OCIDateTimeGetTime(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
8840: ub1 *hr, ub1 *mm, ub1 *ss, ub4 *fsec);
8841:
8842: sword OCIDateTimeGetDate(dvoid *hndl, OCIError *err, CONST OCIDateTime *date,
8843: sb2 *yr, ub1 *mnth, ub1 *dy );
8844:
8845: sword OCIDateTimeGetTimeZoneOffset(dvoid *hndl,OCIError *err,
8846: CONST OCIDateTime *datetime,sb1 *hr,sb1 *mm);
8847:
8848: sword OCIDateTimeConstruct(dvoid *hndl,OCIError *err,OCIDateTime *datetime,
8849: sb2 yr,ub1 mnth,ub1 dy,ub1 hr,ub1 mm,ub1 ss,ub4 fsec,
8850: OraText *timezone,size_t timezone_length);
8851:
8852: sword OCIDateTimeSysTimeStamp(dvoid *hndl, OCIError *err,
8853: OCIDateTime *sys_date );
8854:
8855: sword OCIDateTimeAssign(dvoid *hndl, OCIError *err, CONST OCIDateTime *from,
8856: OCIDateTime *to);
8857:
8858: sword OCIDateTimeToText(dvoid *hndl, OCIError *err, CONST OCIDateTime *date,
8859: CONST OraText *fmt, ub1 fmt_length, ub1 fsprec,
8860: CONST OraText *lang_name, size_t lang_length,
8861: size_t *buf_size, OraText *buf );
8862:
8863: sword OCIDateTimeFromText(dvoid *hndl, OCIError *err, CONST OraText *date_str,
8864: size_t dstr_length, CONST OraText *fmt, ub1 fmt_length,
8865: CONST OraText *lang_name, size_t lang_length, OCIDateTime *date );
8866:
8867: sword OCIDateTimeCompare(dvoid *hndl, OCIError *err, CONST OCIDateTime *date1,
8868: CONST OCIDateTime *date2, sword *result );
8869:
8870: sword OCIDateTimeCheck(dvoid *hndl, OCIError *err, CONST OCIDateTime *date,
8871: ub4 *valid );
8872:
8873: sword OCIDateTimeConvert(dvoid *hndl, OCIError *err, OCIDateTime *indate,
8874: OCIDateTime *outdate);
8875:
8876: sword OCIDateTimeSubtract(dvoid *hndl, OCIError *err, OCIDateTime *indate1,
8877: OCIDateTime *indate2, OCIInterval *inter);
8878:
8879: sword OCIDateTimeIntervalAdd(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
8880: OCIInterval *inter, OCIDateTime *outdatetime);
8881:
8882: sword OCIDateTimeIntervalSub(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
8883: OCIInterval *inter, OCIDateTime *outdatetime);
8884:
8885: sword OCIIntervalSubtract(dvoid *hndl, OCIError *err, OCIInterval *minuend,
8886: OCIInterval *subtrahend, OCIInterval *result );
8887:
8888: sword OCIIntervalAdd(dvoid *hndl, OCIError *err, OCIInterval *addend1,
8889: OCIInterval *addend2, OCIInterval *result );
8890:
8891: sword OCIIntervalMultiply(dvoid *hndl, OCIError *err, CONST OCIInterval *inter,
8892: OCINumber *nfactor, OCIInterval *result );
8893:
8894: sword OCIIntervalDivide(dvoid *hndl, OCIError *err, OCIInterval *dividend,
8895: OCINumber *divisor, OCIInterval *result );
8896:
8897: sword OCIIntervalCompare(dvoid *hndl, OCIError *err, OCIInterval *inter1,
8898: OCIInterval *inter2, sword *result );
8899:
8900: sword OCIIntervalFromNumber(dvoid *hndl, OCIError *err, OCIInterval *inter,
8901: OCINumber *number);
8902:
8903: sword OCIIntervalFromText( dvoid *hndl, OCIError *err, CONST OraText *inpstr,
8904: size_t str_len, OCIInterval *result );
8905:
8906: sword OCIIntervalToText( dvoid *hndl, OCIError *err, CONST OCIInterval *inter,
8907: ub1 lfprec, ub1 fsprec,
8908: OraText *buffer, size_t buflen, size_t *resultlen );
8909:
8910: sword OCIIntervalToNumber(dvoid *hndl, OCIError *err,const OCIInterval *inter,
8911: OCINumber *number);
8912:
8913: sword OCIIntervalCheck(dvoid *hndl, OCIError *err, CONST OCIInterval *interval,
8914: ub4 *valid );
8915:
8916: sword OCIIntervalAssign(dvoid *hndl, OCIError *err, CONST OCIInterval *ininter,
8917: OCIInterval *outinter );
8918:
8919: sword OCIIntervalSetYearMonth(dvoid *hndl, OCIError *err, sb4 yr, sb4 mnth,
8920: OCIInterval *result );
8921:
8922: sword OCIIntervalGetYearMonth(dvoid *hndl, OCIError *err, sb4 *yr, sb4 *mnth,
8923: CONST OCIInterval *result );
8924:
8925: sword OCIIntervalSetDaySecond(dvoid *hndl, OCIError *err, sb4 dy, sb4 hr,
8926: sb4 mm, sb4 ss, sb4 fsec, OCIInterval *result );
8927:
8928: sword OCIIntervalGetDaySecond(dvoid *hndl, OCIError *err, sb4 *dy, sb4 *hr,
8929: sb4 *mm, sb4 *ss, sb4 *fsec, CONST OCIInterval *result );
8930:
8931: /*----------------- End Datetime interface Extensions -----------------------*/
8932:
8933:
8934: /*---------------------------------------------------------------------------
8935: PRIVATE FUNCTIONS
8936: ---------------------------------------------------------------------------*/
8937:
8938: /* the following functions are depracated and should not be used */
8939: #ifdef NEVER
8940: sword OCIStmtBindByPos (OCIStmt *stmtp, OCIBind *bindp, OCIError *errhp,
8941: ub4 position, dvoid *valuep, sb4 value_sz,
8942: ub2 dty, dvoid *indp, ub2 *alenp, ub2 *rcodep,
8943: ub4 maxarr_len, ub4 *curelep, ub4 mode);
8944:
8945:
8946: sword OCIStmtBindByName (OCIStmt *stmtp, OCIBind *bindp, OCIError *errhp,
8947: CONST OraText *placeholder, sb4 placeh_len, dvoid *valuep,
8948: sb4 value_sz, ub2 dty, dvoid *indp, ub2 *alenp,
8949: ub2 *rcodep, ub4 maxarr_len, ub4 *curelep, ub4 mode);
8950:
8951: sword ocidefn (OCIStmt *stmtp, OCIDefine *defnp, OCIError *errhp,
8952: ub4 position, dvoid *valuep, sb4 value_sz, ub2 dty,
8953: dvoid *indp, ub2 *rlenp, ub2 *rcodep, ub4 mode);
8954: #endif /* NEVER */
8955:
8956: #endif /* OCIAP_ORACLE */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ociap.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / sql / oracle / include / oci