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