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