| TerraLib 4.1

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files
- Examples

- File List
- File Members

E:/Projetos_Primeiro_Semestre_2012/TerraView/terralib/src/terralib/drivers/Oracle/OCI/include/ociap.h
Go to the documentation of this file.

    00001 /*
    00002  * $Header$
    00003  */
    00004
    00005 /* Copyright (c) 1996, 2003, Oracle Corporation.  All rights reserved.  */
    00006
    00007 /* NOTE:  See 'header_template.doc' in the 'doc' dve under the 'forms'
    00008       directory for the header file template that includes instructions.
    00009 */
    00010
    00011 /*
    00012    NAME
    00013      ociap.h - Oracle Call Interface - Ansi Prototypes
    00014
    00015    DESCRIPTION
    00016      <short description of component this file declares/defines>
    00017
    00018    RELATED DOCUMENTS
    00019
    00020    INSPECTION STATUS
    00021      Inspection date:
    00022      Inspection status:
    00023      Estimated increasing cost defects per page:
    00024      Rule sets:
    00025
    00026    ACCEPTANCE REVIEW STATUS
    00027      Review date:
    00028      Review status:
    00029      Reviewers:
    00030
    00031    PUBLIC FUNCTION(S)
    00032      <list of external functions declared/defined - with one-line descriptions>
    00033
    00034    PRIVATE FUNCTION(S)
    00035      <list of static functions defined in .c file - with one-line descriptions>
    00036
    00037    EXAMPLES
    00038
    00039    NOTES
    00040      <other useful comments, qualifications, etc.>
    00041
    00042    MODIFIED   (MM/DD/YY)
    00043    debanerj    08/26/03 - 6003: Lob interface changes
    00044    sgollapu    06/23/03 - Add OCIPing
    00045    debanerj    01/16/03 - Bug 2753018: Lob Locator parameter for
    00046                           OCILobGetStorageLimit
    00047    tkeefe      02/17/03 - bug-2773794: Add new interface for setting Kerb attrs
    00048    ataracha    01/03/03 - Move OCIXMLType functions to ocixml.h
    00049    akatti      11/28/02 - [2521361]:add OCIRowidToChar prototype
    00050    chliang     10/23/02 - add OCIFetchRowCallback
    00051    cparampa    10/13/02 - Fix the prototype of OCIAQListen(ansi prototype)
    00052    chliang     10/12/02 - add OCIBindRowCallback
    00053    debanerj    09/30/02 - Unlimited size LOB 6003
    00054    thoang      09/25/02 - Add csid to XMLType create functions
    00055    thoang      04/19/02 - Add OCIXMLTypeGetNS
    00056    aahluwal    08/09/02 - adding OCIAQDeqArray
    00057    aahluwal    06/03/02 - bug 2360115
    00058    skabraha    04/16/02 - fix compiler warnings
    00059    sichandr    02/12/02 - fix OCIXMLTypeExists
    00060    gayyappa    02/01/02 - fix 2210776 : change Dom to DOM
    00061    sichandr    10/24/01 - OCISvcCtx for XMLType create routines
    00062    schandir    09/14/01 - Add prototypes for Stmt Caching
    00063    abande      09/04/01 - Add Prototypes for Session Pooling Methods
    00064    stakeda     09/12/01 - add OCINlsCharSetConvert
    00065    whe         08/28/01 - add OCIEnvNlsCreate
    00066    wzhang      08/22/01 - Add OCINlsCharSetNameToId.
    00067    whe         10/05/01 - add prototype for OCIXMLType functions
    00068    mdmehta     04/06/01 - Bug 1683763, OCIDateTimeToText: buf_size to ub4*
    00069    schandir    12/12/00 - modify the ociconnectionpoolcreate() interface.
    00070    porangas    12/04/00 - Forward merge bug#974710 to 9i
    00071    rpingte     11/29/00 - Fix bug# 1485795.
    00072    gtarora     11/30/00 - fix comment for OCILobIsTemporary
    00073    akatti      11/07/00 - [1198379]:add OCIRowidToChar
    00074    bpalaval    10/15/00 - Forward merge 892654.
    00075    kmohan      09/18/00 - add OCILogon2
    00076    etucker     07/28/00 - add OCIIntervalFromTZ
    00077    vjayaram    07/18/00 - add connection pooling changes
    00078    etucker     07/13/00 - add dls apis for oci
    00079    hmasaki     07/05/00 - fix 1230846: forward merge into 8.2
    00080    mbastawa    06/05/00 - add OCIStmtFetch2
    00081    rxgovind    06/07/00 - update OCIAnyData interfaces
    00082    rxgovind    05/04/00 - add OCIAnyDataSet interfaces
    00083    rkasamse    05/01/00 - remove attrno from OCIAnyDataAttrGet
    00084    rkasamse    03/13/00 - add prototype s for OCCIAnyData
    00085    slari       09/01/99 - remove OCIEnvCallback
    00086    slari       08/23/99 - add OCIUcb in user callback functions
    00087    dsaha       07/07/99 - Add OCIFEnvCreate for forms
    00088    vyanaman    06/21/99 - Change OCI DateTime/Interval APIs.
    00089    esoyleme    07/01/99 - expose MTS performance enhancements
    00090    whe         06/14/99 - bug727872:add CONST to match definitions
    00091    kkarun      02/23/99 - Fix OCIDateTime APIs
    00092    jiyang      12/07/98 - Add comments for OCI_NLS_DUAL_CURRENCY
    00093    aroy        12/01/98 - add OCIEnvCreate
    00094    slari       11/23/98 - use ORASTDARG
    00095    slari       11/21/98 - replace ellipsis by arglist in OCIUserCallback
    00096    thchang     10/20/98 - correct comment on OCILobCreateTemporary
    00097    slari       09/08/98 - allow envh to receive error info also in CallbackReg/
    00098    kkarun      09/02/98 - Change const to CONST
    00099    aroy        08/04/98 - add OCITerminate calls
    00100    nramakri    06/25/98 - remove CONST from some OCIPickler APIs
    00101    jiyang      06/22/98 - Fix a lint error
    00102    nmallava    06/08/98 - ociistemporary -> envhp
    00103    jhasenbe    05/27/98 - Remove definitions for U-Calls (Unicode)
    00104    nmallava    05/18/98 - add comments
    00105    sgollapu    05/19/98 - Change text to OraText
    00106    aroy        04/20/98 - merge forward 8.0.5 -> 8.1.3
    00107    nbhatt      05/14/98 -  aq listen call
    00108    lchidamb    03/02/98 - Client Notification prototypes
    00109    vyanaman    04/19/98 - System Timestamp
    00110    kkarun      04/17/98 - Add more Interval functions
    00111    vyanaman    04/17/98 - Fix min (proc error)
    00112    vyanaman    04/16/98 - Add get/set TZ
    00113    kkarun      04/13/98 - Add Datetime prototypes
    00114    rkasamse    04/13/98 - change OCIEnv* to dvoid* for context/memory cart serv
    00115    rkasamse    04/15/98 - chage pickler cart interface
    00116    slari       03/20/98 - change proto of OCIUserCallback
    00117    slari       02/17/98 - add OCIUserCallback
    00118    jiyang      04/02/98 - Accept both env and user handles for NLS
    00119    rkasamse    03/20/98 - remove prototypes for OCIMemoryDuration* functions.
    00120    tsaulys     03/20/98 - use environment or session handle
    00121    nmallava    04/09/98 - OCILobLocatorAssign
    00122    nmallava    04/07/98 - lobgetchunksize and writeappend apis
    00123    jhasenbe    04/06/98 - Add new interfaces for Unicode support
    00124    nmallava    03/17/98 - add interfaces
    00125    nmallava    03/16/98 - add open/close apis
    00126    nmallava    03/10/98 - add temporary lobs apis
    00127    sgollapu    07/10/97 - Add OCIReset
    00128    sgollapu    02/09/98 - OCI non-blocking
    00129    nramakri    01/16/98 - remove #ifdef NEVER clause for OCIExtract
    00130    rmurthy     01/08/98 - OCIContextGenerateKey: change ub1 to ub4
    00131    ewaugh      12/18/97 - Turn type wrappers into functions.
    00132    skabraha    12/02/97 - adding OCIFile functions
    00133    rhwu        12/02/97 - add OCI Thread
    00134    nramakri    12/15/97 - move to core4
    00135    nramakri    12/11/97 - modify OCIExtract prototype
    00136    ewaugh      12/10/97 - add OCIFormat prototypes
    00137    nmallava    12/17/97 - Add ilob open and close apis
    00138    rkasamse    12/03/97 - Change some of the function names for pickler cartrid
    00139    nramakri    11/12/97 - add OCIExtract prototypes
    00140    rkasamse    11/21/97 - add prototypes for memory cartridge services and cont
    00141    rkasamse    11/03/97 - Add pickler cartridge interfaces.
    00142    jiyang      11/11/97 - Add NLS service for cartridge
    00143    tanguyen    08/19/97 -
    00144    cxcheng     07/30/97 - replace OCISvcCtx with OCISvcCtx
    00145    schandra    06/25/97 - AQ OCI interface
    00146    bnainani    07/21/97 - add prototypes for Oracle XA extensions
    00147    esoyleme    05/13/97 - move failover callback prototype
    00148    skmishra    05/06/97 - stdc compiler fixes
    00149    skmishra    04/24/97 - C++ Compatibility changes
    00150    skotsovo    04/21/97 - make lob parameter names consistent
    00151    rwhitman    04/16/97 - Fix LOB prototypes - Olint OCI 8.0.3
    00152    ramkrish    04/15/97 - Add free flag to OCILobFlushBuffer
    00153    dchatter    04/10/97 - add nzt.h inclusion
    00154    cxcheng     04/09/97 - change objnamp from CONST text* to dvoid*
    00155    cxcheng     04/08/97 - fix prototype of OCIDescribeAny()
    00156    skotsovo    03/31/97 - remove OCILobLocatorSize
    00157    skotsovo    03/27/97 - add OCILobLoadFromFile
    00158    bcchang     02/18/97 - Fix syntax error
    00159    dchatter    01/13/97 - fix comments on LOB calls
    00160    aroy        01/10/97 - remove ocilobfilecreate delete
    00161    sgollapu    12/27/96 - Correct OCILogon prototype
    00162    dchatter    01/04/97 - comments to describe the functions
    00163    sgollapu    11/25/96 - Change OCILobFileIsExistent
    00164    schandra    11/18/96 - Remove xa.h include
    00165    sgollapu    11/09/96 - Change prototype of OCIDescribeAny
    00166    dchatter    10/31/96 - delete CONST from lob write cb fn
    00167    dchatter    10/30/96 - more changes
    00168    dchatter    10/26/96 - lob/file long name corrections
    00169    slari       10/16/96 - delete unused calls
    00170    rwessman    10/29/96 - Fixed OCISecurityGetIdentity prototype
    00171    bcchang     10/25/96 - Fix syntax error
    00172    sgollapu    10/22/96 - Add OCILogon and OCILogoff
    00173    rwessman    10/16/96 - Added cryptographic and digital signature functions
    00174    sgollapu    10/10/96 - Add ocibdp and ocibdn
    00175    rxgovind    10/07/96 - add oci file calls
    00176    skotsovo    10/01/96 - move orl lob fnts to oci
    00177    skotsovo    09/20/96 - in OCILobGetLength(), remove the 'isnull' parameter.
    00178    aroy        08/29/96 - change prototype for Nchar Lob support
    00179    dchatter    08/21/96 - OCIResultSetToStmt prototype change
    00180    sthakur     08/14/96 - add OCIParamSet
    00181    schandra    07/26/96 - TX OCI return values - sb4->sword
    00182    aroy        07/17/96 - terminology change: OCILobLocator => OCILobLocator
    00183    dchatter    07/01/96 - create ANSI prototypes
    00184    dchatter    07/01/96 - Creation
    00185
    00186 */
    00187
    00188
    00189 #ifndef OCIAP_ORACLE
    00190 # define OCIAP_ORACLE
    00191
    00192 # ifndef ORATYPES
    00193 #  include <oratypes.h>
    00194 # endif
    00195
    00196 #ifndef ORASTDARG
    00197 #include <stdarg.h>
    00198 #define ORASTDARG
    00199 #endif
    00200
    00201 #ifndef OCIDFN
    00202 #include <ocidfn.h>
    00203 #endif
    00204
    00205 #ifndef NZT_ORACLE
    00206 #include <nzt.h>
    00207 #endif /* NZT_ORACLE */
    00208
    00209 #ifndef OCI_ORACLE
    00210 #include <oci.h>
    00211 #endif
    00212
    00213 #ifndef ORT_ORACLE
    00214 #include <ort.h>
    00215 #endif
    00216
    00217
    00218
    00219 /*---------------------------------------------------------------------------
    00220                      PUBLIC TYPES AND CONSTANTS
    00221   ---------------------------------------------------------------------------*/
    00222
    00223
    00224 /*---------------------------------------------------------------------------
    00225                      PRIVATE TYPES AND CONSTANTS
    00226   ---------------------------------------------------------------------------*/
    00227
    00228
    00229 /*---------------------------------------------------------------------------
    00230                            PUBLIC FUNCTIONS
    00231   ---------------------------------------------------------------------------*/
    00232
    00233 /*****************************************************************************
    00234                               DESCRIPTION
    00235 ******************************************************************************
    00236 Note: the descriptions of the functions are alphabetically arranged. Please
    00237 maintain the arrangement when adding a new function description. The actual
    00238 prototypes are below this comment section and donot follow any alphabetical
    00239 ordering.
    00240
    00241
    00242 --------------------------------OCIAttrGet------------------------------------
    00243
    00244 OCIAttrGet()
    00245 Name
    00246 OCI Attribute Get
    00247 Purpose
    00248 This call is used to get a particular attribute of a handle.
    00249 Syntax
    00250 sword OCIAttrGet ( CONST dvoid    *trgthndlp,
    00251                  ub4            trghndltyp,
    00252                  dvoid          *attributep,
    00253                  ub4            *sizep,
    00254                  ub4            attrtype,
    00255                  OCIError       *errhp );
    00256 Comments
    00257 This call is used to get a particular attribute of a handle.
    00258 See Appendix B,  "Handle Attributes",  for a list of handle types and their
    00259 readable attributes.
    00260 Parameters
    00261 trgthndlp (IN) - is the pointer to a handle type.
    00262 trghndltyp (IN) - is the handle type.
    00263 attributep (OUT) - is a pointer to the storage for an attribute value. The
    00264 attribute value is filled in.
    00265 sizep (OUT) - is the size of the attribute value.
    00266 This can be passed in as NULL for most parameters as the size is well known.
    00267 For text* parameters, a pointer to a ub4 must be passed in to get the length
    00268 of the string.
    00269 attrtype (IN) - is the type of attribute.
    00270 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    00271 diagnostic information in the event of an error.
    00272 Related Functions
    00273 OCIAttrSet()
    00274
    00275 --------------------------------OCIAttrSet------------------------------------
    00276
    00277
    00278 OCIAttrSet()
    00279 Name
    00280 OCI Attribute Set
    00281 Purpose
    00282 This call is used to set a particular attribute of a handle or a descriptor.
    00283 Syntax
    00284 sword OCIAttrSet ( dvoid       *trgthndlp,
    00285                  ub4         trghndltyp,
    00286                  dvoid       *attributep,
    00287                  ub4         size,
    00288                  ub4         attrtype,
    00289                  OCIError    *errhp );
    00290 Comments
    00291 This call is used to set a particular attribute of a handle or a descriptor.
    00292 See Appendix B for a list of handle types and their writeable attributes.
    00293 Parameters
    00294 trghndlp (IN/OUT) - the pointer to a handle type whose attribute gets
    00295 modified.
    00296 trghndltyp (IN/OUT) - is the handle type.
    00297 attributep (IN) - a pointer to an attribute value.
    00298 The attribute value is copied into the target handle. If the attribute value
    00299 is a pointer, then only the pointer is copied, not the contents of the pointer.
    00300 size (IN) - is the size of an attribute value. This can be passed in as 0 for
    00301 most attributes as the size is already known by the OCI library. For text*
    00302 attributes, a ub4 must be passed in set to the length of the string.
    00303 attrtype (IN) - the type of attribute being set.
    00304 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    00305 diagnostic information in the event of an error.
    00306 Related Functions
    00307 OCIAttrGet()
    00308
    00309
    00310
    00311 --------------------------------OCIBindArrayOfStruct--------------------------
    00312
    00313
    00314
    00315 OCIBindArrayOfStruct()
    00316 Name
    00317 OCI Bind for Array of Structures
    00318 Purpose
    00319 This call sets up the skip parameters for a static array bind.
    00320 Syntax
    00321 sword OCIBindArrayOfStruct ( OCIBind     *bindp,
    00322                            OCIError    *errhp,
    00323                            ub4         pvskip,
    00324                            ub4         indskip,
    00325                            ub4         alskip,
    00326                            ub4         rcskip );
    00327 Comments
    00328 This call sets up the skip parameters necessary for a static array bind.
    00329 This call follows a call to OCIBindByName() or OCIBindByPos(). The bind
    00330 handle returned by that initial bind call is used as a parameter for the
    00331 OCIBindArrayOfStruct() call.
    00332 For information about skip parameters, see the section "Arrays of Structures"
    00333 on page 4-16.
    00334 Parameters
    00335 bindp (IN) - the handle to a bind structure.
    00336 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    00337 diagnostic information in the event of an error.
    00338 pvskip (IN) - skip parameter for the next data value.
    00339 indskip (IN) - skip parameter for the next indicator value or structure.
    00340 alskip (IN) - skip parameter for the next actual length value.
    00341 rcskip (IN) - skip parameter for the next column-level return code value.
    00342 Related Functions
    00343 OCIAttrGet()
    00344
    00345
    00346 --------------------------------OCIBindByName---------------------------------
    00347
    00348 OCIBindByName()
    00349 Name
    00350 OCI Bind by Name
    00351 Purpose
    00352 Creates an association between a program variable and a placeholder in a SQL
    00353 statement or PL/SQL block.
    00354 Syntax
    00355 sword OCIBindByName (
    00356               OCIStmt       *stmtp,
    00357               OCIBind       **bindp,
    00358               OCIError      *errhp,
    00359               CONST OraText    *placeholder,
    00360               sb4           placeh_len,
    00361               dvoid         *valuep,
    00362               sb4           value_sz,
    00363               ub2           dty,
    00364               dvoid         *indp,
    00365               ub2           *alenp,
    00366               ub2           *rcodep,
    00367               ub4           maxarr_len,
    00368               ub4           *curelep,
    00369               ub4           mode );
    00370 Description
    00371 This call is used to perform a basic bind operation. The bind creates an
    00372 association between the address of a program variable and a placeholder in a
    00373 SQL statement or PL/SQL block. The bind call also specifies the type of data
    00374 which is being bound, and may also indicate the method by which data will be
    00375 provided at runtime.
    00376 This function also implicitly allocates the bind handle indicated by the bindp
    00377 parameter.
    00378 Data in an OCI application can be bound to placeholders statically or
    00379 dynamically. Binding is static when all the IN bind data and the OUT bind
    00380 buffers are well-defined just before the execute. Binding is dynamic when the
    00381 IN bind data and the OUT bind buffers are provided by the application on
    00382 demand at execute time to the client library. Dynamic binding is indicated by
    00383 setting the mode parameter of this call to OCI_DATA_AT_EXEC.
    00384 Related Functions: For more information about dynamic binding, see
    00385 the section "Runtime Data Allocation and Piecewise Operations" on
    00386 page 5-16.
    00387 Both OCIBindByName() and OCIBindByPos() take as a parameter a bind handle,
    00388 which is implicitly allocated by the bind call A separate bind handle is
    00389 allocated for each placeholder the application is binding.
    00390 Additional bind calls may be required to specify particular attributes
    00391 necessary when binding certain data types or handling input data in certain
    00392 ways:
    00393 If arrays of structures are being utilized, OCIBindArrayOfStruct() must
    00394 be called to set up the necessary skip parameters.
    00395 If data is being provided dynamically at runtime, and the application
    00396 will be using user-defined callback functions, OCIBindDynamic() must
    00397 be called to register the callbacks.
    00398 If a named data type is being bound, OCIBindObject() must be called to
    00399 specify additional necessary information.
    00400 Parameters
    00401 stmth (IN/OUT) - the statement handle to the SQL or PL/SQL statement
    00402 being processed.
    00403 bindp (IN/OUT) - a pointer to a pointer to a bind handle which is implicitly
    00404 allocated by this call.  The bind handle  maintains all the bind information
    00405 for this particular input value. The handle is feed implicitly when the
    00406 statement handle is deallocated.
    00407 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    00408 diagnostic information in the event of an error.
    00409 placeholder (IN) - the placeholder attributes are specified by name if
    00410 ocibindn() is being called.
    00411 placeh_len (IN) - the length of the placeholder name specified in placeholder.
    00412 valuep (IN/OUT) - a pointer to a data value or an array of data values of the
    00413 type specified in the dty parameter. An array of data values can be specified
    00414 for mapping into a PL/SQL table or for providing data for SQL multiple-row
    00415 operations. When an array of bind values is provided, this is called an array
    00416 bind in OCI terms. Additional attributes of the array bind (not bind to a
    00417 column of ARRAY type) are set up in OCIBindArrayOfStruct() call.
    00418 For a REF, named data type  bind, the valuep parameter is used only for IN
    00419 bind data. The pointers to OUT buffers are set in the pgvpp parameter
    00420 initialized by OCIBindObject(). For named data type and REF binds, the bind
    00421 values are unpickled into the Object Cache. The OCI object navigational calls
    00422 can then be used to navigate the objects and the refs in the Object Cache.
    00423 If the OCI_DATA_AT_EXEC mode is specified in the mode parameter, valuep
    00424 is ignored for all data types. OCIBindArrayOfStruct() cannot be used and
    00425 OCIBindDynamic() must be invoked to provide callback functions if desired.
    00426 value_sz (IN) - the size of a data value. In the case of an array bind, this is
    00427 the maximum size of any element possible with the actual sizes being specified
    00428 in the alenp parameter.
    00429 If the OCI_DATA_AT_EXEC mode is specified, valuesz defines the maximum
    00430 size of the data that can be ever provided at runtime for data types other than
    00431 named data types or REFs.
    00432 dty (IN) - the data type of the value(s) being bound. Named data types
    00433 (SQLT_NTY) and REFs (SQLT_REF) are valid only if the application has been
    00434 initialized in object mode. For named data types, or REFs, additional calls
    00435 must be made with the bind handle to set up the datatype-specific attributes.
    00436 indp (IN/OUT) - pointer to an indicator variable or array. For scalar data
    00437 types, this is a pointer to sb2 or an array of sb2s. For named data types,
    00438 this pointer is ignored and the actual pointer to the indicator structure or
    00439 an array of indicator structures is initialized by OCIBindObject().
    00440 Ignored for dynamic binds.
    00441 See the section "Indicator Variables" on page 2-43 for more information about
    00442 indicator variables.
    00443 alenp (IN/OUT) - pointer to array of actual lengths of array elements. Each
    00444 element in alenp is the length of the data in the corresponding element in the
    00445 bind value array before and after the execute. This parameter is ignored for
    00446 dynamic binds.
    00447 rcodep (OUT) - pointer to array of column level return codes. This parameter
    00448 is ignored for dynamic binds.
    00449 maxarr_len (IN) - the maximum possible number of elements of type dty in a
    00450 PL/SQL binds. This parameter is not required for non-PL/SQL binds. If
    00451 maxarr_len is non-zero, then either OCIBindDynamic() or
    00452 OCIBindArrayOfStruct() can be invoked to set up additional bind attributes.
    00453 curelep(IN/OUT) - a pointer to the actual number of elements. This parameter
    00454 is only required for PL/SQL binds.
    00455 mode (IN) - the valid modes for this parameter are:
    00456 OCI_DEFAULT. This is default mode.
    00457 OCI_DATA_AT_EXEC. When this mode is selected, the value_sz
    00458 parameter defines the maximum size of the data that can be ever
    00459 provided at runtime. The application must be ready to provide the OCI
    00460 library runtime IN data buffers at any time and any number of times.
    00461 Runtime data is provided in one of the two ways:
    00462 callbacks using a user-defined function which must be registered
    00463 with a subsequent call to OCIBindDynamic().
    00464 a polling mechanism using calls supplied by the OCI. This mode
    00465 is assumed if no callbacks are defined.
    00466 For more information about using the OCI_DATA_AT_EXEC mode, see
    00467 the section "Runtime Data Allocation and Piecewise Operations" on
    00468 page 5-16.
    00469 When the allocated buffers are not required any more, they should be
    00470 freed by the client.
    00471 Related Functions
    00472 OCIBindDynamic(), OCIBindObject(), OCIBindArrayOfStruct(), OCIAttrGet()
    00473
    00474
    00475
    00476 -------------------------------OCIBindByPos-----------------------------------
    00477
    00478
    00479 OCIBindByPos()
    00480 Name
    00481 OCI Bind by Position
    00482 Purpose
    00483 Creates an association between a program variable and a placeholder in a SQL
    00484 statement or PL/SQL block.
    00485 Syntax
    00486 sword OCIBindByPos (
    00487               OCIStmt      *stmtp,
    00488               OCIBind      **bindp,
    00489               OCIError     *errhp,
    00490               ub4          position,
    00491               dvoid        *valuep,
    00492               sb4          value_sz,
    00493               ub2          dty,
    00494               dvoid        *indp,
    00495               ub2          *alenp,
    00496               ub2          *rcodep,
    00497               ub4          maxarr_len,
    00498               ub4          *curelep,
    00499               ub4          mode);
    00500
    00501 Description
    00502 This call is used to perform a basic bind operation. The bind creates an
    00503 association between the address of a program variable and a placeholder in a
    00504 SQL statement or PL/SQL block. The bind call also specifies the type of data
    00505 which is being bound, and may also indicate the method by which data will be
    00506 provided at runtime.
    00507 This function also implicitly allocates the bind handle indicated by the bindp
    00508 parameter.
    00509 Data in an OCI application can be bound to placeholders statically or
    00510 dynamically. Binding is static when all the IN bind data and the OUT bind
    00511 buffers are well-defined just before the execute. Binding is dynamic when the
    00512 IN bind data and the OUT bind buffers are provided by the application on
    00513 demand at execute time to the client library. Dynamic binding is indicated by
    00514 setting the mode parameter of this call to OCI_DATA_AT_EXEC.
    00515 Related Functions: For more information about dynamic binding, see
    00516 the section "Runtime Data Allocation and Piecewise Operations" on
    00517 page 5-16
    00518 Both OCIBindByName() and OCIBindByPos() take as a parameter a bind handle,
    00519 which is implicitly allocated by the bind call A separate bind handle is
    00520 allocated for each placeholder the application is binding.
    00521 Additional bind calls may be required to specify particular attributes
    00522 necessary when binding certain data types or handling input data in certain
    00523 ways:
    00524 If arrays of structures are being utilized, OCIBindArrayOfStruct() must
    00525 be called to set up the necessary skip parameters.
    00526 If data is being provided dynamically at runtime, and the application
    00527 will be using user-defined callback functions, OCIBindDynamic() must
    00528 be called to register the callbacks.
    00529 If a named data type is being bound, OCIBindObject() must be called to
    00530 specify additional necessary information.
    00531 Parameters
    00532 stmth (IN/OUT) - the statement handle to the SQL or PL/SQL statement
    00533 being processed.
    00534 bindp (IN/OUT) - a pointer to a pointer to a bind handle which is implicitly
    00535 allocated by this call.  The bind handle  maintains all the bind information
    00536 for this particular input value. The handle is feed implicitly when the
    00537 statement handle is deallocated.
    00538 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    00539 diagnostic information in the event of an error.
    00540 position (IN) - the placeholder attributes are specified by position if
    00541 ocibindp() is being called.
    00542 valuep (IN/OUT) - a pointer to a data value or an array of data values of the
    00543 type specified in the dty parameter. An array of data values can be specified
    00544 for mapping into a PL/SQL table or for providing data for SQL multiple-row
    00545 operations. When an array of bind values is provided, this is called an array
    00546 bind in OCI terms. Additional attributes of the array bind (not bind to a
    00547 column of ARRAY type) are set up in OCIBindArrayOfStruct() call.
    00548 For a REF, named data type  bind, the valuep parameter is used only for IN
    00549 bind data. The pointers to OUT buffers are set in the pgvpp parameter
    00550 initialized by OCIBindObject(). For named data type and REF binds, the bind
    00551 values are unpickled into the Object Cache. The OCI object navigational calls
    00552 can then be used to navigate the objects and the refs in the Object Cache.
    00553 If the OCI_DATA_AT_EXEC mode is specified in the mode parameter, valuep
    00554 is ignored for all data types. OCIBindArrayOfStruct() cannot be used and
    00555 OCIBindDynamic() must be invoked to provide callback functions if desired.
    00556 value_sz (IN) - the size of a data value. In the case of an array bind, this is
    00557 the maximum size of any element possible with the actual sizes being specified
    00558 in the alenp parameter.
    00559 If the OCI_DATA_AT_EXEC mode is specified, valuesz defines the maximum
    00560 size of the data that can be ever provided at runtime for data types other than
    00561 named data types or REFs.
    00562 dty (IN) - the data type of the value(s) being bound. Named data types
    00563 (SQLT_NTY) and REFs (SQLT_REF) are valid only if the application has been
    00564 initialized in object mode. For named data types, or REFs, additional calls
    00565 must be made with the bind handle to set up the datatype-specific attributes.
    00566 indp (IN/OUT) - pointer to an indicator variable or array. For scalar data
    00567 types, this is a pointer to sb2 or an array of sb2s. For named data types,
    00568 this pointer is ignored and the actual pointer to the indicator structure or
    00569 an array of indicator structures is initialized by OCIBindObject(). Ignored
    00570 for dynamic binds.
    00571 See the section "Indicator Variables" on page 2-43 for more information about
    00572 indicator variables.
    00573 alenp (IN/OUT) - pointer to array of actual lengths of array elements. Each
    00574 element in alenp is the length of the data in the corresponding element in the
    00575 bind value array before and after the execute. This parameter is ignored for
    00576 dynamic binds.
    00577 rcodep (OUT) - pointer to array of column level return codes. This parameter
    00578 is ignored for dynamic binds.
    00579 maxarr_len (IN) - the maximum possible number of elements of type dty in a
    00580 PL/SQL binds. This parameter is not required for non-PL/SQL binds. If
    00581 maxarr_len is non-zero, then either OCIBindDynamic() or
    00582 OCIBindArrayOfStruct() can be invoked to set up additional bind attributes.
    00583 curelep(IN/OUT) - a pointer to the actual number of elements. This parameter
    00584 is only required for PL/SQL binds.
    00585 mode (IN) - the valid modes for this parameter are:
    00586 OCI_DEFAULT. This is default mode.
    00587 OCI_DATA_AT_EXEC. When this mode is selected, the value_sz
    00588 parameter defines the maximum size of the data that can be ever
    00589 provided at runtime. The application must be ready to provide the OCI
    00590 library runtime IN data buffers at any time and any number of times.
    00591 Runtime data is provided in one of the two ways:
    00592 callbacks using a user-defined function which must be registered
    00593 with a subsequent call to OCIBindDynamic() .
    00594 a polling mechanism using calls supplied by the OCI. This mode
    00595 is assumed if no callbacks are defined.
    00596 For more information about using the OCI_DATA_AT_EXEC mode, see
    00597 the section "Runtime Data Allocation and Piecewise Operations" on
    00598 page 5-16.
    00599 When the allocated buffers are not required any more, they should be
    00600 freed by the client.
    00601 Related Functions
    00602 OCIBindDynamic(), OCIBindObject(), OCIBindArrayOfStruct(), OCIAttrGet()
    00603
    00604
    00605
    00606 -------------------------------OCIBindDynamic---------------------------------
    00607
    00608 OCIBindDynamic()
    00609 Name
    00610 OCI Bind Dynamic Attributes
    00611 Purpose
    00612 This call is used to register user callbacks for dynamic data allocation.
    00613 Syntax
    00614 sword OCIBindDynamic( OCIBind     *bindp,
    00615                     OCIError    *errhp,
    00616                     dvoid       *ictxp,
    00617                     OCICallbackInBind         (icbfp)(
    00618                                 dvoid            *ictxp,
    00619                                 OCIBind          *bindp,
    00620                                 ub4              iter,
    00621                                 ub4              index,
    00622                                 dvoid            **bufpp,
    00623                                 ub4              *alenp,
    00624                                 ub1              *piecep,
    00625                                 dvoid            **indp ),
    00626                     dvoid       *octxp,
    00627                     OCICallbackOutBind         (ocbfp)(
    00628                                 dvoid            *octxp,
    00629                                 OCIBind          *bindp,
    00630                                 ub4              iter,
    00631                                 ub4              index,
    00632                                 dvoid            **bufp,
    00633                                 ub4              **alenpp,
    00634                                 ub1              *piecep,
    00635                                 dvoid            **indpp,
    00636                                 ub2              **rcodepp)   );
    00637 Comments
    00638 This call is used to register user-defined callback functions for providing
    00639 data for an UPDATE or INSERT if OCI_DATA_AT_EXEC mode was specified in a
    00640 previous call to OCIBindByName() or OCIBindByPos().
    00641 The callback function pointers must return OCI_CONTINUE if it the call is
    00642 successful. Any return code other than OCI_CONTINUE signals that the client
    00643 wishes to abort processing immediately.
    00644 For more information about the OCI_DATA_AT_EXEC mode, see the section
    00645 "Runtime Data Allocation and Piecewise Operations" on page 5-16.
    00646 Parameters
    00647 bindp (IN/OUT) - a bind handle returned by a call to OCIBindByName() or
    00648 OCIBindByPos().
    00649 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    00650 diagnostic information in the event of an error.
    00651 ictxp (IN) - the context pointer required by the call back function icbfp.
    00652 icbfp (IN) - the callback function which returns a pointer to the IN bind
    00653 value or piece at run time. The callback takes in the following parameters.
    00654 ictxp (IN/OUT) - the context pointer for this callback function.
    00655 bindp (IN) - the bind handle passed in to uniquely identify this bind
    00656 variable.
    00657 iter (IN) - 1-based execute iteration value.
    00658 index (IN) - index of the current array, for an array bind. 1 based not
    00659 greater than curele parameter of the bind call.
    00660 index (IN) - index of the current array, for an array bind. This parameter
    00661 is 1-based, and may not be greater than curele parameter of the bind call.
    00662 bufpp (OUT) - the pointer to the buffer.
    00663 piecep (OUT) - which piece of the bind value. This can be one of the
    00664 following values - OCI_ONE_PIECE, OCI_FIRST_PIECE,
    00665 OCI_NEXT_PIECE and OCI_LAST_PIECE.
    00666 indp (OUT) - contains the indicator value. This is apointer to either an
    00667 sb2 value or a pointer to an indicator structure for binding named data
    00668 types.
    00669 indszp (OUT) - contains the indicator value size. A pointer containing
    00670 the size of either an sb2 or an indicator structure pointer.
    00671 octxp (IN) - the context pointer required by the callback function ocbfp.
    00672 ocbfp (IN) - the callback function which returns a pointer to the OUT bind
    00673 value or piece at run time. The callback takes in the following parameters.
    00674 octxp (IN/OUT) - the context pointer for this call back function.
    00675 bindp (IN) - the bind handle passed in to uniquely identify this bind
    00676 variable.
    00677 iter (IN) - 1-based execute iteration value.
    00678 index (IN) - index of the current array, for an array bind. This parameter
    00679 is 1-based, and must not be greater than curele parameter of the bind call.
    00680 bufpp (OUT) - a pointer to a buffer to write the bind value/piece.
    00681 buflp (OUT) - returns the buffer size.
    00682 alenpp (OUT) - a pointer to a storage for OCI to fill in the size of the bind
    00683 value/piece after it has been read.
    00684 piecep (IN/OUT) - which piece of the bind value. It will be set by the
    00685 library to be one of the following values - OCI_ONE_PIECE or
    00686 OCI_NEXT_PIECE. The callback function can leave it unchanged or set
    00687 it to OCI_FIRST_PIECE or OCI_LAST_PIECE. By default -
    00688 OCI_ONE_PIECE.
    00689 indpp (OUT) - returns a pointer to contain the indicator value which
    00690 either an sb2 value or a pointer to an indicator structure for named data
    00691 types.
    00692 indszpp (OUT) - returns a pointer to return the size of the indicator
    00693 value which is either size of an sb2 or size of an indicator structure.
    00694 rcodepp (OUT) - returns a pointer to contains the return code.
    00695 Related Functions
    00696 OCIAttrGet()
    00697
    00698
    00699 ---------------------------------OCIBindObject--------------------------------
    00700
    00701
    00702 OCIBindObject()
    00703 Name
    00704 OCI Bind Object
    00705 Purpose
    00706 This function sets up additional attributes which are required for a named
    00707 data type (object)  bind.
    00708 Syntax
    00709 sword OCIBindObject ( OCIBind          *bindp,
    00710                     OCIError         *errhp,
    00711                     CONST OCIType    *type,
    00712                     dvoid            **pgvpp,
    00713                     ub4              *pvszsp,
    00714                     dvoid            **indpp,
    00715                     ub4              *indszp, );
    00716 Comments
    00717 This function sets up additional attributes which binding a named data type
    00718 or a REF. An error will be returned if this function is called when the OCI
    00719 environment has been initialized in non-object mode.
    00720 This call takes as a paramter a type descriptor object (TDO) of datatype
    00721 OCIType for the named data type being defined.  The TDO can be retrieved
    00722 with a call to OCITypeByName().
    00723 If the OCI_DATA_AT_EXEC mode was specified in ocibindn() or ocibindp(), the
    00724 pointers to the IN buffers are obtained either using the callback icbfp
    00725 registered in the OCIBindDynamic() call or by the OCIStmtSetPieceInfo() call.
    00726 The buffers are dynamically allocated for the OUT data and the pointers to
    00727 these buffers are returned either by calling ocbfp() registered by the
    00728 OCIBindDynamic() or by setting the pointer to the buffer in the buffer passed
    00729 in by OCIStmtSetPieceInfo() called when OCIStmtExecute() returned
    00730 OCI_NEED_DATA. The memory of these client library- allocated buffers must be
    00731 freed when not in use anymore by using the OCIObjectFreee() call.
    00732 Parameters
    00733 bindp ( IN/OUT) - the bind handle returned by the call to OCIBindByName()
    00734 or OCIBindByPos().
    00735 errhp ( IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    00736 diagnostic information in the event of an error.
    00737 type ( IN) - points to the TDO which describes the type of the program
    00738 variable being bound. Retrieved by calling OCITypeByName().
    00739 pgvpp ( IN/OUT) - points to a pointer to the program variable buffer. For an
    00740 array, pgvpp points to an array of pointers. When the bind variable is also an
    00741 OUT variable, the OUT Named Data Type value or REF is allocated
    00742 (unpickled) in the Object Cache, and a pointer to the value or REF is returned,
    00743 At the end of execute, when all OUT values have been received, pgvpp points
    00744 to an array of pointer(s) to these newly allocated named data types in the
    00745 object cache.
    00746 pgvpp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the Named
    00747 Data Type buffers are requested at runtime. For static array binds, skip
    00748 factors may be specified using the OCIBindArrayOfStruct() call. The skip
    00749 factors are used to compute the address of the next pointer to the value, the
    00750 indicator structure and their sizes.
    00751 pvszsp ( IN/OUT) - points to the size of the program variable. The size of the
    00752 named data type is not required on input. For an array, pvszsp is an array of
    00753 ub4s. On return, for OUT bind variables, this points to size(s) of the Named
    00754 Data Types and REFs received. pvszsp is ignored if the OCI_DATA_AT_EXEC
    00755 mode is set. Then the size of the buffer is taken at runtime.
    00756 indpp ( IN/OUT) - points to a pointer to the program variable buffer
    00757 containing the parallel indicator structure. For an array, points to an array
    00758 of pointers. When the bind variable is also an OUT bind variable, memory is
    00759 allocated in the object cache, to store the unpickled OUT indicator values. At
    00760 the end of the execute when all OUT values have been received, indpp points
    00761 to the pointer(s) to these newly allocated indicator structure(s).
    00762 indpp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the indicator
    00763 is requested at runtime.
    00764 indszp ( IN/OUT) - points to the size of the IN indicator structure program
    00765 variable. For an array, it is an array of sb2s. On return for OUT bind
    00766 variables, this points to size(s) of the received OUT indicator structures.
    00767 indszp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the indicator
    00768 size is requested at runtime.
    00769 Related Functions
    00770 OCIAttrGet()
    00771
    00772
    00773
    00774 ----------------------------------OCIBreak------------------------------------
    00775
    00776
    00777 OCIBreak()
    00778 Name
    00779 OCI Break
    00780 Purpose
    00781 This call performs an immediate (asynchronous) abort of any currently
    00782 executing OCI function that is associated with a server .
    00783 Syntax
    00784 sword OCIBreak ( dvoid      *hndlp,
    00785                  OCIError   *errhp);
    00786 Comments
    00787 This call performs an immediate (asynchronous) abort of any currently
    00788 executing OCI function that is associated with a server. It is normally used
    00789 to stop a long-running OCI call being processed on the server.
    00790 This call can take either the service context handle or the server context
    00791 handle as a parameter to identify the function to be aborted.
    00792 Parameters
    00793 hndlp (IN) - the service context handle or the server context handle.
    00794 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    00795 diagnostic information in the event of an error.
    00796 Related Functions
    00797
    00798 -----------------------------OCIConnectionPoolCreate --------------------------
    00799 Name:
    00800 OCIConnectionPoolCreate
    00801
    00802 Purpose:
    00803 Creates the connections in the pool
    00804
    00805 Syntax:
    00806 OCIConnectionPoolCreate (OCIEnv *envhp, OCIError *errhp, OCICPool *poolhp,
    00807                          OraText **poolName, sb4 *poolNameLen,
    00808                          CONST Oratext *dblink, sb4 dblinkLen,
    00809                          ub4 connMin, ub4 connMax, ub4 connIncr,
    00810                          CONST OraText *poolUsername, sb4 poolUserLen,
    00811                          CONST OraText *poolPassword, sb4 poolPassLen,
    00812                          ub4 mode)
    00813 Comments:
    00814 This call is used to create a connection pool. conn_min connections
    00815 to the database are started on calling OCIConnectionPoolCreate.
    00816
    00817 Parameters:
    00818 envhp (IN/OUT)  - A pointer to the environment where the Conencton Pool
    00819                   is to be created
    00820 errhp (IN/OUT)  - An error handle which can be passed to OCIErrorGet().
    00821 poolhp (IN/OUT) - An uninitialiazed pool handle.
    00822 poolName (OUT) - The connection pool name.
    00823 poolNameLen (OUT) - The length of the connection pool name
    00824 dblink (IN/OUT) - Specifies the database(server) to connect. This will also
    00825                   be used as the default pool name.
    00826 dblinkLen (IN)  - The length of the string pointed to by dblink.
    00827 connMin (IN)    - Specifies the minimum number of connections in the
    00828                   Connection Pool at any instant.
    00829                   connMin number of connections are started when
    00830                   OCIConnectionPoolCreate() is called.
    00831 connMax (IN)    - Specifies the maximum number of connections that can be
    00832                   opened to the database. Once this value is reached, no
    00833                   more connections are opened.
    00834 connIncr (IN)   - Allows application to set the next increment for
    00835                   connections to be opened to the database if the current
    00836                   number of connections are less than conn_max.
    00837 poolUsername (IN/OUT) - Connection pooling requires an implicit proxy
    00838                          session and this attribute provides a username
    00839                          for that session.
    00840 poolUserLen (IN) - This represents the length of pool_username.
    00841 poolPassword (IN/OUT) - The password for the parameter pool_username passed
    00842                         above.
    00843 poolPassLen (IN) - This represents the length of pool_password.
    00844
    00845 mode (IN) - The modes supported are OCI_DEFAULT and
    00846 OCI_CPOOL_REINITIALIZE
    00847
    00848 Related Functions
    00849 OCIConnectionPoolDestroy()
    00850
    00851 ---------------------------------------------------------------------------
    00852
    00853 ----------------------------OCIConnectionPoolDestroy-------------------------
    00854 Name:
    00855 OCIConnectionPoolDestroy
    00856
    00857 Purpose:
    00858 Terminates the connections in the pool
    00859
    00860 Syntax:
    00861 OCIConnectionPoolDestroy (OCICPool *poolhp, OCIError *errhp, ub4 mode)
    00862
    00863 Comments:
    00864 On calling OCIConnectionPoolDestroy, all the open connections in the pool
    00865 are closed and the pool is destroyed.
    00866
    00867 Parameters:
    00868 poolhp (IN/OUT) - An initialiazed pool handle.
    00869 errhp (IN/OUT)  - An error handle which can be passed to OCIErrorGet().
    00870 mode (IN)       - Currently, OCIConnectionPoolDestroy() will support only
    00871                   the OCI_DEFAULT mode.
    00872
    00873 Related Functions:
    00874 OCIConnectionPoolCreate()
    00875
    00876 -----------------------------------------------------------------------------
    00877 ----------------------------OCISessionPoolCreate-----------------------------
    00878 Name:
    00879 OCISessionPoolCreate
    00880
    00881 Purpose:
    00882 Creates the sessions in the session pool.
    00883
    00884 Syntax:
    00885 sword OCISessionPoolCreate (OCIEnv *envhp, OCIError *errhp, OCISpool *spoolhp,
    00886                       OraText **poolName, ub4 *poolNameLen,
    00887                       CONST OraText *connStr, ub4 connStrLen,
    00888                       ub4 sessMin, ub4 sessMax, ub4 sessIncr,
    00889                       OraText *userid,  ub4 useridLen,
    00890                       OraText *password, ub4 passwordLen,
    00891                       ub4 mode)
    00892
    00893 Comments:
    00894 When OCISessionPoolCreate is called, a session pool is initialized for
    00895 the associated environment and the database specified by the
    00896 connStr parameter. This pool is named uniquely and the name
    00897 is returned to the user in the poolname parameter.
    00898
    00899 Parameters:
    00900 envhp (IN/OUT) - A pointer to the environment handle in which the session
    00901                  pool needs to be created.
    00902 errhp (IN/OUT) - An error handle which can be passed to OCIErrorGet().
    00903 spoolhp (IN/OUT) - A pointer to the session pool handle that is created.
    00904 poolName (OUT) - Session pool name returned to the user.
    00905 poolNameLen (OUT) - Length of the PoolName
    00906 connStr (IN) - The TNS alias of the database to connect to.
    00907 connStrLen (IN) - Length of the connStr.
    00908 sessMin (IN) - Specifies the minimum number of sessions in the Session Pool.
    00909                These are the number of sessions opened in the beginning, if
    00910                in Homogeneous mode. Else, the parameter is ignored.
    00911 sessMax (IN) - Specifies the maximum number of sessions in the Session Pool.
    00912                Once this value is reached, no more sessions are opened,
    00913                unless the OCI_ATTR_SPOOL_FORCEGET is set.
    00914 userid (IN) - Specifies the userid with which to start up the sessions.
    00915 useridLen (IN) - Length of userid.
    00916 password (IN) - Specifies the password for the corresponding userid.
    00917 passwordLen (IN) - Specifies the length of the password
    00918 mode(IN) - May be OCI_DEFAULT, OCI_SPC_SPOOL_REINITIALIZE, or
    00919            OCI_SPC_SPOOL_HOMOGENEOUS.
    00920
    00921 Returns:
    00922 SUCCESS - If pool could be allocated and created successfully.
    00923 ERROR - If above conditions could not be met.
    00924
    00925 Related Functions:
    00926 OCISessionPoolDestroy()
    00927 -----------------------------------------------------------------------------
    00928 -----------------------------OCISessionPoolDestroy---------------------------
    00929 Name:
    00930 OCISessionPoolDestroy
    00931
    00932 Purpose:
    00933 Terminates all the sessions in the session pool.
    00934
    00935 Syntax:
    00936 sword OCISessionPoolDestroy (OCISPool *spoolhp, OCIError *errhp, ub4 mode)
    00937
    00938 Comments:
    00939 spoolhp (IN/OUT) - The pool handle of the session pool to be destroyed.
    00940 errhp (IN/OUT) - An error handle which can be passed to OCIErrorGet().
    00941 mode (IN) - Currently only OCI_DEFAULT mode is supported.
    00942
    00943 Returns:
    00944 SUCCESS - All the sessions could be closed.
    00945 ERROR - If the above condition is not met.
    00946
    00947 Related Functions:
    00948 OCISessionPoolCreate()
    00949 -----------------------------------------------------------------------------
    00950 -------------------------------OCISessionGet---------------------------------
    00951 Name:
    00952 OCISessionGet
    00953
    00954 Purpose:
    00955 Get a session. This could be from a session pool, connection pool or
    00956 a new standalone session.
    00957
    00958 Syntax:
    00959 sword OCISessionGet(OCIenv *envhp, OCIError *errhp, OCISvcCtx **svchp,
    00960                     OCIAuthInfo *authhp,
    00961                     OraText *poolName, ub4 poolName_len,
    00962                     CONST OraText *tagInfo, ub4 tagInfo_len,
    00963                     OraText **retTagInfo, ub4 *retTagInfo_len,
    00964                     boolean *found,
    00965                     ub4 mode)
    00966
    00967 Comments:
    00968 envhp (IN/OUT) - OCI environment handle.
    00969 errhp (IN/OUT) - OCI error handle to be passed to OCIErrorGet().
    00970 svchp (IN/OUT) - Address of an OCI service context pointer. This will be
    00971                  filled with a server and session handle, attached to the
    00972                  pool.
    00973 authhp (IN/OUT) - OCI Authentication Information handle.
    00974 poolName (IN) - This indicates the session/connection pool to get the
    00975                 session/connection from in the OCI_SPOOL/OCI_CPOOL mode.
    00976                 In the OCI_DEFAULT mode it refers to the connect string.
    00977 poolName_len (IN) - length of poolName.
    00978 tagInfo (IN) - indicates the tag of the session that the user wants. If the
    00979                    user wants a default session, he must specify a NULL here.
    00980                    Only used for Session Pooling.
    00981 tagInfo_len (IN) - the length of tagInfo.
    00982 retTagInfo (OUT) - This indicates the type of session that is returned to
    00983                    the user. Only used for Session Pooling.
    00984 retTagInfo_len (OUT) - the length of retTagInfo.
    00985 found (OUT) - set to true if the user gets a session he had requested, else
    00986               set to false. Only used for Session Pooling.
    00987 mode (IN) - The supported modes are OCI_DEFAULT, OCI_CRED_PROXY and
    00988             OCI_GET_SPOOL_MATCHANY, OCI_SPOOL and OCI_CPOOL. OCI_SPOOL and
    00989             OCI_CPOOL are mutually exclusive.
    00990
    00991 Returns:
    00992 SUCCESS -  if a session was successfully returned into svchp.
    00993 SUCCESS_WITH_INFO - if a session was successfully returned into svchp and the
    00994                     total number of sessions > maxsessions. Only valid for
    00995                     Session Pooling.
    00996 ERROR - If a session could not be retrieved.
    00997
    00998 Related Functions:
    00999 OCISessionRelease()
    01000 -----------------------------------------------------------------------------
    01001 ---------------------------OCISessionRelease---------------------------------
    01002 Name:
    01003 OCISessionRelease
    01004
    01005 Purpose:
    01006 Release the session.
    01007
    01008 Syntax:
    01009 sword OCISessionRelease ( OCISvcCtx *svchp, OCIError *errhp,
    01010                           OraText *tag, ub4 tag_len,
    01011                           ub4 mode);
    01012
    01013 Comments:
    01014 svchp (IN/OUT) - The service context associated with the session/connection.
    01015 errhp (IN/OUT) - OCI error handle to be passed to OCIErrorGet().
    01016 tag (IN) - Only used for Session Pooling.
    01017            This parameter will be ignored unless mode OCI_RLS_SPOOL_RETAG is
    01018            specified. In this case, the session is labelled with this tag and
    01019            returned to the pool. If this is NULL, then the session is untagged.
    01020 tag_len (IN) - Length of the tag. This is ignored unless mode
    01021                OCI_RLS_SPOOL_RETAG is set.
    01022 mode (IN) - The supported modes are OCI_DEFAULT, OCI_RLS_SPOOL_DROPSESS,
    01023             OCI_RLS_SPOOL_RETAG. The last 2 are only valid for Session Pooling.
    01024             When OCI_RLS_SPOOL_DROPSESS is specified, the session
    01025             will be removed from the session pool. If OCI_RLS_SPOOL_RETAG
    01026             is set, the tag on the session will be altered. If this mode is
    01027             not set, the tag and tag_len parameters will be ignored.
    01028
    01029 Returns:
    01030 ERROR - If the session could not be released successfully.
    01031 SUCCESS - In all other cases.
    01032
    01033 Related Functions:
    01034 OCISessionGet().
    01035 -----------------------------------------------------------------------------
    01036 ------------------------------OCIDateTimeAssign --------------------------
    01037 sword OCIDateTimeAssign(dvoid *hndl, OCIError *err, CONST OCIDateTime *from,
    01038                         OCIDateTime *to);
    01039 NAME: OCIDateTimeAssign - OCIDateTime Assignment
    01040 PARAMETERS:
    01041 hndl (IN) - Session/Env handle.
    01042 err (IN/OUT) - error handle. If there is an error, it is
    01043                 recorded in 'err' and this function returns OCI_ERROR.
    01044                 The error recorded in 'err' can be retrieved by calling
    01045                 OCIErrorGet().
    01046 from (IN) - datetime to be assigned
    01047 to (OUT) - lhs of assignment
    01048 DESCRIPTION:
    01049         Performs date assignment. The type of the output will be same as that
    01050         of input
    01051
    01052 ------------------------------OCIDateTimeCheck----------------------------
    01053 sword OCIDateTimeCheck(dvoid *hndl, OCIError *err, CONST OCIDateTime *date,
    01054                  ub4 *valid );
    01055 NAME: OCIDateTimeCheck - OCIDateTime CHecK if the given date is valid
    01056 PARAMETERS:
    01057 hndl (IN) - Session/Env handle.
    01058 err (IN/OUT) - error handle. If there is an error, it is
    01059                 recorded in 'err' and this function returns OCI_ERROR.
    01060                 The error recorded in 'err' can be retrieved by calling
    01061                 OCIErrorGet().
    01062 date (IN) - date to be checked
    01063 valid (OUT) -  returns zero for a valid date, otherwise
    01064                 the ORed combination of all error bits specified below:
    01065    Macro name                   Bit number      Error
    01066    ----------                   ----------      -----
    01067    OCI_DATE_INVALID_DAY         0x1             Bad day
    01068    OCI_DATE_DAY_BELOW_VALID     0x2             Bad DAy Low/high bit (1=low)
    01069    OCI_DATE_INVALID_MONTH       0x4             Bad MOnth
    01070    OCI_DATE_MONTH_BELOW_VALID   0x8             Bad MOnth Low/high bit (1=low)
    01071    OCI_DATE_INVALID_YEAR        0x10            Bad YeaR
    01072    OCI_DATE_YEAR_BELOW_VALID    0x20            Bad YeaR Low/high bit (1=low)
    01073    OCI_DATE_INVALID_HOUR        0x40            Bad HouR
    01074    OCI_DATE_HOUR_BELOW_VALID    0x80            Bad HouR Low/high bit (1=low)
    01075    OCI_DATE_INVALID_MINUTE      0x100           Bad MiNute
    01076    OCI_DATE_MINUTE_BELOW_VALID  0x200           Bad MiNute Low/high bit (1=low)
    01077    OCI_DATE_INVALID_SECOND      0x400           Bad SeCond
    01078    OCI_DATE_SECOND_BELOW_VALID  0x800           bad second Low/high bit (1=low)
    01079    OCI_DATE_DAY_MISSING_FROM_1582 0x1000        Day is one of those "missing"
    01080                                                 from 1582
    01081    OCI_DATE_YEAR_ZERO           0x2000          Year may not equal zero
    01082    OCI_DATE_INVALID_TIMEZONE    0x4000          Bad Timezone
    01083    OCI_DATE_INVALID_FORMAT      0x8000          Bad date format input
    01084
    01085    So, for example, if the date passed in was 2/0/1990 25:61:10 in
    01086    (month/day/year hours:minutes:seconds format), the error returned
    01087    would be OCI_DATE_INVALID_DAY | OCI_DATE_DAY_BELOW_VALID |
    01088    OCI_DATE_INVALID_HOUR | OCI_DATE_INVALID_MINUTE
    01089
    01090 DESCRIPTION:
    01091         Check if the given date is valid.
    01092 RETURNS:
    01093         OCI_SUCCESS if the function completes successfully.
    01094         OCI_INVALID_HANDLE if 'err' is NULL.
    01095         OCI_ERROR if
    01096           'date' and 'valid' pointers are NULL pointers
    01097
    01098 ------------------------------- OCIDateTimeCompare----------------------------
    01099 sword OCIDateTimeCompare(dvoid *hndl, OCIError *err, CONST OCIDateTime *date1,
    01100                      CONST OCIDateTime *date2,  sword *result );
    01101 NAME: OCIDateTimeCompare - OCIDateTime CoMPare dates
    01102 PARAMETERS:
    01103 hndl (IN) - Session/Env handle.
    01104 err (IN/OUT) - error handle. If there is an error, it is
    01105                 recorded in 'err' and this function returns OCI_ERROR.
    01106                 The error recorded in 'err' can be retrieved by calling
    01107                 OCIErrorGet().
    01108 date1, date2 (IN) - dates to be compared
    01109 result (OUT) - comparison result, 0 if equal, -1 if date1 < date2,
    01110                 1 if date1 > date2
    01111 DESCRIPTION:
    01112 The function OCIDateCompare compares two dates. It returns -1 if
    01113 date1 is smaller than date2, 0 if they are equal, and 1 if date1 is
    01114 greater than date2.
    01115 RETURNS:
    01116        OCI_SUCCESS if the function completes successfully.
    01117         OCI_INVALID_HANDLE if 'err' is NULL.
    01118         OCI_ERROR if
    01119           invalid date
    01120           input dates are not mutually comparable
    01121
    01122 ------------------------------OCIDateTimeConvert----------------------
    01123 sword OCIDateTimeConvert(dvoid *hndl, OCIError *err, OCIDateTime *indate,
    01124                                 OCIDateTime *outdate);
    01125 NAME: OCIDateTimeConvert - Conversion between different DATETIME types
    01126 PARAMETERS:
    01127 hndl (IN) - Session/Env handle.
    01128 err (IN/OUT) - error handle. If there is an error, it is
    01129                 recorded in 'err' and this function returns OCI_ERROR.
    01130                 The error recorded in 'err' can be retrieved by calling
    01131                 OCIErrorGet().
    01132 indate (IN) - pointer to input date
    01133 outdate (OUT) - pointer to output datetime
    01134 DESCRIPTION: Converts one datetime type to another. The result type is
    01135        the type of the 'outdate' descriptor.
    01136 RETURNS:
    01137         OCI_SUCCESS if the function completes successfully.
    01138         OCI_INVALID_HANDLE if 'err' is NULL.
    01139         OCI_ERROR if
    01140             conversion not possible.
    01141
    01142 ---------------------------- OCIDateTimeFromText-----------------------
    01143 sword OCIDateTimeFromText(dvoid *hndl, OCIError *err, CONST OraText *date_str,
    01144              size_t d_str_length, CONST OraText *fmt, ub1 fmt_length,
    01145              CONST OraText *lang_name, size_t lang_length, OCIDateTime *date );
    01146 NAME: OCIDateTimeFromText - OCIDateTime convert String FROM Date
    01147 PARAMETERS:
    01148 hndl (IN) - Session/Env handle. If Session Handle is passed, the
    01149                     conversion takes place in session NLS_LANGUAGE and
    01150                     session NLS_CALENDAR, otherwise the default is used.
    01151 err (IN/OUT) - error handle. If there is an error, it is
    01152                 recorded in 'err' and this function returns OCI_ERROR.
    01153                 The error recorded in 'err' can be retrieved by calling
    01154                 OCIErrorGet().
    01155 date_str (IN) - input string to be converted to Oracle date
    01156 d_str_length (IN) - size of the input string, if the length is -1
    01157                 then 'date_str' is treated as a null terminated  string
    01158 fmt (IN) - conversion format; if 'fmt' is a null pointer, then
    01159                 the string is expected to be in the default format for
    01160                 the datetime type.
    01161 fmt_length (IN) - length of the 'fmt' parameter
    01162 lang_name (IN) - language in which the names and abbreviations of
    01163                 days and months are specified, if null i.e. (OraText *)0,
    01164                 the default language of session is used,
    01165 lang_length (IN) - length of the 'lang_name' parameter
    01166 date (OUT) - given string converted to date
    01167 DESCRIPTION:
    01168         Converts the given string to Oracle datetime type set in the
    01169         OCIDateTime descriptor according to the specified format. Refer to
    01170         "TO_DATE" conversion function described in "Oracle SQL Language
    01171         Reference Manual" for a description of format.
    01172 RETURNS:
    01173         OCI_SUCCESS if the function completes successfully.
    01174         OCI_INVALID_HANDLE if 'err' is NULL.
    01175         OCI_ERROR if
    01176           invalid format
    01177           unknown language
    01178           invalid input string
    01179
    01180 --------------------------- OCIDateTimeGetDate-------------------------
    01181 sword OCIDateTimeGetDate(dvoid *hndl, OCIError *err,  CONST OCIDateTime *date,
    01182                            sb2 *year, ub1 *month, ub1 *day );
    01183 NAME: OCIDateTimeGetDate - OCIDateTime Get Date (year, month, day)
    01184                                 portion of DATETIME.
    01185 PARAMETERS:
    01186 hndl (IN) - Session/Env handle.
    01187 err (IN/OUT) - error handle. If there is an error, it is
    01188                 recorded in 'err' and this function returns OCI_ERROR.
    01189                 The error recorded in 'err' can be retrieved by calling
    01190                 OCIErrorGet().
    01191 datetime (IN) - Pointer to OCIDateTime
    01192 year      (OUT) - year value
    01193 month     (OUT) - month value
    01194 day       (OUT) - day value
    01195
    01196 --------------------------- OCIDateTimeGetTime ------------------------
    01197 sword OCIDateTimeGetTime(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
    01198                  ub1 *hour, ub1 *minute, ub1 *sec, ub4 *fsec);
    01199 NAME: OCIDateTimeGetTime - OCIDateTime Get Time (hour, min, second,
    01200                         fractional second)  of DATETIME.
    01201 PARAMETERS:
    01202 hndl (IN) - Session/Env handle.
    01203 err (IN/OUT) - error handle. If there is an error, it is
    01204                 recorded in 'err' and this function returns OCI_ERROR.
    01205                 The error recorded in 'err' can be retrieved by calling
    01206                 OCIErrorGet().
    01207 datetime (IN) - Pointer to OCIDateTime
    01208 hour      (OUT) - hour value
    01209 minute       (OUT) - minute value
    01210 sec       (OUT) - second value
    01211 fsec      (OUT) - Fractional Second value
    01212
    01213 --------------------------- OCIDateTimeGetTimeZoneOffset ----------------------
    01214 sword OCIDateTimeGetTimeZoneOffset(dvoid *hndl,OCIError *err,CONST
    01215               OCIDateTime *datetime,sb1 *hour,sb1  *minute);
    01216
    01217 NAME: OCIDateTimeGetTimeZoneOffset - OCIDateTime Get TimeZone (hour, minute)
    01218                          portion of DATETIME.
    01219 PARAMETERS:
    01220 hndl (IN) - Session/Env handle.
    01221 err (IN/OUT) - error handle. If there is an error, it is
    01222                 recorded in 'err' and this function returns OCI_ERROR.
    01223                 The error recorded in 'err' can be retrieved by calling
    01224                 OCIErrorGet().
    01225 datetime (IN) - Pointer to OCIDateTime
    01226 hour      (OUT) - TimeZone Hour value
    01227 minute     (OUT) - TimeZone Minute value
    01228
    01229 --------------------------- OCIDateTimeSysTimeStamp---------------------
    01230 sword OCIDateTimeSysTimeStamp(dvoid *hndl, OCIError *err,
    01231               OCIDateTime *sys_date );
    01232
    01233 NAME: OCIDateTimeSysTimeStamp - Returns system date/time as a TimeStamp with
    01234                       timezone
    01235 PARAMETERS:
    01236 hndl (IN) - Session/Env handle.
    01237 err (IN/OUT) - error handle. If there is an error, it is
    01238                 recorded in 'err' and this function returns OCI_ERROR.
    01239                 The error recorded in 'err' can be retrieved by calling
    01240                 OCIErrorGet().
    01241 sys_date (OUT) - Pointer to output timestamp
    01242
    01243 DESCRIPTION:
    01244         Gets the system current date and time as a timestamp with timezone
    01245 RETURNS:
    01246         OCI_SUCCESS if the function completes successfully.
    01247         OCI_INVALID_HANDLE if 'err' is NULL.
    01248
    01249
    01250 ------------------------------OCIDateTimeIntervalAdd----------------------
    01251 sword OCIDateTimeIntervalAdd(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
    01252          OCIInterval *inter, OCIDateTime *outdatetime);
    01253 NAME: OCIDateTimeIntervalAdd - Adds an interval to datetime
    01254 PARAMETERS:
    01255 hndl (IN) - Session/Env handle.
    01256 err (IN/OUT) - error handle. If there is an error, it is
    01257                 recorded in 'err' and this function returns OCI_ERROR.
    01258                 The error recorded in 'err' can be retrieved by calling
    01259                 OCIErrorGet().
    01260 datetime (IN) - pointer to input datetime
    01261 inter    (IN) - pointer to interval
    01262 outdatetime (IN) - pointer to output datetime. The output datetime
    01263                                 will be of same type as input datetime
    01264 DESCRIPTION:
    01265         Adds an interval to a datetime to produce a resulting datetime
    01266 RETURNS:
    01267         OCI_SUCCESS if the function completes successfully.
    01268         OCI_INVALID_HANDLE if 'err' is NULL.
    01269         OCI_ERROR if:
    01270                 resulting date is before Jan 1, -4713
    01271                 resulting date is after Dec 31, 9999
    01272
    01273 ------------------------------OCIDateTimeIntervalSub----------------------
    01274 sword OCIDateTimeIntervalSub(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
    01275               OCIInterval *inter, OCIDateTime *outdatetime);
    01276 NAME: OCIDateTimeIntervalSub - Subtracts an interval from a datetime
    01277 PARAMETERS:
    01278 hndl (IN) - Session/Env handle.
    01279 err (IN/OUT) - error handle. If there is an error, it is
    01280                 recorded in 'err' and this function returns OCI_ERROR.
    01281                 The error recorded in 'err' can be retrieved by calling
    01282                 OCIErrorGet().
    01283 datetime (IN) - pointer to input datetime
    01284 inter    (IN) - pointer to interval
    01285 outdatetime (IN) - pointer to output datetime. The output datetime
    01286                                 will be of same type as input datetime
    01287 DESCRIPTION:
    01288         Subtracts an interval from a datetime and stores the result in a
    01289         datetime
    01290 RETURNS:
    01291         OCI_SUCCESS if the function completes successfully.
    01292         OCI_INVALID_HANDLE if 'err' is NULL.
    01293         OCI_ERROR if:
    01294                 resulting date is before Jan 1, -4713
    01295                 resulting date is after Dec 31, 9999
    01296
    01297 --------------------------- OCIDateTimeConstruct-------------------------
    01298 sword OCIDateTimeConstruct(dvoid  *hndl,OCIError *err,OCIDateTime *datetime,
    01299                sb2 year,ub1 month,ub1 day,ub1 hour,ub1 min,ub1 sec,ub4 fsec,
    01300                OraText  *timezone,size_t timezone_length);
    01301
    01302 NAME: OCIDateTimeConstruct - Construct an OCIDateTime. Only the relevant
    01303        fields for the OCIDateTime descriptor types are used.
    01304 PARAMETERS:
    01305         hndl (IN) - Session/Env handle.
    01306         err (IN/OUT) - error handle. If there is an error, it is
    01307                 recorded in 'err' and this function returns OCI_ERROR.
    01308                 The error recorded in 'err' can be retrieved by calling
    01309                 OCIErrorGet().
    01310         datetime (IN) - Pointer to OCIDateTime
    01311         year      (IN) - year value
    01312         month     (IN) - month value
    01313         day       (IN) - day value
    01314         hour      (IN) - hour value
    01315         min       (IN) - minute value
    01316         sec       (IN) - second value
    01317         fsec      (IN) - Fractional Second value
    01318         timezone  (IN) - Timezone string
    01319         timezone_length(IN) - Length of timezone string
    01320
    01321 DESCRIPTION:
    01322        Constructs a DateTime descriptor. The type of the datetime is the
    01323        type of the OCIDateTime descriptor. Only the relevant fields based
    01324        on the type are used. For Types with timezone, the date and time
    01325        fields are assumed to be in the local time of the specified timezone.
    01326        If timezone is not specified, then session default timezone is
    01327        assumed.
    01328 RETURNS:
    01329         OCI_SUCCESS if the function completes successfully.
    01330         OCI_ERROR if datetime is not valid.
    01331
    01332 ------------------------------OCIDateTimeSubtract-----------------------
    01333 sword OCIDateTimeSubtract(dvoid *hndl, OCIError *err, OCIDateTime *indate1,
    01334                 OCIDateTime *indate2, OCIInterval *inter);
    01335 NAME: OCIDateTimeSubtract - subtracts two datetimes to return an interval
    01336 PARAMETERS:
    01337 hndl (IN) - Session/Env handle.
    01338 err (IN/OUT) - error handle. If there is an error, it is
    01339                 recorded in 'err' and this function returns OCI_ERROR.
    01340                 The error recorded in 'err' can be retrieved by calling
    01341                 OCIErrorGet().
    01342 indate1(IN) - pointer to subtrahend
    01343 indate2(IN) - pointer to minuend
    01344 inter  (OUT) - pointer to output interval
    01345 DESCRIPTION:
    01346         Takes two datetimes as input and stores their difference in an
    01347         interval. The type of the interval is the type of the 'inter'
    01348         descriptor.
    01349 RETURNS:
    01350         OCI_SUCCESS if the function completes successfully.
    01351         OCI_INVALID_HANDLE if 'err' is NULL.
    01352         OCI_ERROR if
    01353            datetimes are not comparable.
    01354
    01355 --------------------------- OCIDateTimeToText--------------------------
    01356 sword OCIDateTimeToText(dvoid *hndl, OCIError *err, CONST OCIDateTime *date,
    01357                         CONST OraText *fmt, ub1 fmt_length, ub1 fsprec,
    01358                         CONST OraText *lang_name, size_t lang_length,
    01359                         ub4 *buf_size, OraText *buf );
    01360 NAME: OCIDateTimeToText - OCIDateTime convert date TO String
    01361 PARAMETERS:
    01362 hndl (IN) - Session/Env handle. If Session Handle is passed, the
    01363                     conversion takes place in session NLS_LANGUAGE and
    01364                     session NLS_CALENDAR, otherwise the default is used.
    01365 err (IN/OUT) - error handle. If there is an error, it is
    01366                 recorded in 'err' and this function returns OCI_ERROR.
    01367                 The error recorded in 'err' can be retrieved by calling
    01368                 OCIErrorGet().
    01369 date (IN) - Oracle datetime to be converted
    01370 fmt (IN) - conversion format, if null string pointer (OraText*)0, then
    01371                 the date is converted to a character string in the
    01372                 default format for that type.
    01373 fmt_length (IN) - length of the 'fmt' parameter
    01374 fsprec (IN) - specifies the fractional second precision in which the
    01375                fractional seconds is returned.
    01376 lang_name (IN) - specifies the language in which the names and
    01377                 abbreviations of months and days are returned;
    01378                 default language of session is used if 'lang_name'
    01379                 is null i.e. (OraText *)0
    01380 lang_length (IN) - length of the 'nls_params' parameter
    01381 buf_size (IN/OUT) - size of the buffer; size of the resulting string
    01382                 is returned via this parameter
    01383 buf (OUT) - buffer into which the converted string is placed
    01384 DESCRIPTION:
    01385         Converts the given date to a string according to the specified format.
    01386         Refer to "TO_DATE" conversion function described in
    01387         "Oracle SQL Language Reference Manual" for a description of format
    01388         and NLS arguments. The converted null-terminated date string is
    01389         stored in the buffer 'buf'.
    01390 RETURNS:
    01391         OCI_SUCCESS if the function completes successfully.
    01392         OCI_INVALID_HANDLE if 'err' is NULL.
    01393         OCI_ERROR if
    01394           buffer too small
    01395           invalid format
    01396           unknown language
    01397           overflow error
    01398
    01399 ----------------------------OCIDateTimeGetTimeZoneName------------------------
    01400 sword OCIDateTimeGetTimeZoneName(dvoid *hndl,
    01401                                  OCIError *err,
    01402                                  CONST OCIDateTime *datetime,
    01403                                  ub1 *buf,
    01404                                  ub4 *buflen);
    01405 NAME OCIDateTimeGetTimeZoneName - OCI DateTime Get the Time Zone Name
    01406 PARAMETERS:
    01407 hndl (IN)      - Session/Env handle.
    01408 err (IN/OUT)   - error handle. If there is an error, it is
    01409                  recorded in 'err' and this function returns OCI_ERROR.
    01410                  The error recorded in 'err' can be retrieved by calling
    01411                  OCIErrorGet().
    01412 datetime (IN)   - Pointer to an OCIDateTime.
    01413 buf (OUT)       - User allocated storage for name string.
    01414 buflen (IN/OUT) - length of buf on input, length of name on out
    01415 DESCRIPTION:
    01416         Returns either the timezone region name or the absolute hour and minute
    01417         offset. If the DateTime was created with a region id then the region
    01418         name will be returned in the buf.  If the region id is zero, then the
    01419         hour and minute offset is returned as "[-]HH:MM".
    01420 RETURNS:
    01421        OCI_SUCCESS if the function completes successfully.
    01422        OCI_INVALID_HANDLE if 'err' is NULL.
    01423        OCI_ERROR if
    01424          buffer too small
    01425          error retrieving timezone data
    01426          invalid region
    01427          invalid LdiDateTime type
    01428
    01429 ---------------------------------OCIDateTimeToArray----------------------------
    01430 sword OCIDateTimeToArray(dvoid *hndl,
    01431                          OCIError *err,
    01432                          CONST OCIDateTime *datetime,
    01433                          CONST OCIInterval *reftz,
    01434                          ub1 *outarray,
    01435                          ub4 *len
    01436                          ub1 *fsprec);
    01437 NAME OCIDateTimeToArray - OCI DateTime convert To Array format
    01438 PARAMETERS:
    01439 hndl (IN)      - Session/Env handle.
    01440 err (IN/OUT)   - error handle. If there is an error, it is
    01441                  recorded in 'err' and this function returns OCI_ERROR.
    01442                  The error recorded in 'err' can be retrieved by calling
    01443                  OCIErrorGet().
    01444 datetime (IN)   - Pointer to OCIDateTime to be converted.
    01445 outarray (OUT)  - Result array storage
    01446 len (OUT)        - pointer to  length of outarray.
    01447 fsprec (IN)     - Number of fractional seconds digits.
    01448 DESCRIPTION:
    01449         Returns an array representing the input DateTime descriptor.
    01450 RETURNS:
    01451        OCI_SUCCESS if the function completes successfully.
    01452        OCI_INVALID_HANDLE if 'err' is NULL.
    01453        OCI_ERROR if
    01454          buffer too small
    01455          error retrieving timezone data
    01456          invalid region
    01457          invalid LdiDateTime type
    01458
    01459 --------------------------------OCIDateTimeFromArray---------------------------
    01460 sword OCIDateTimeFromArray(dvoid *hndl,
    01461                          OCIError *err,
    01462                          ub1 *inarray,
    01463                          ub4 len
    01464                          ub1 type
    01465                          OCIDateTime *datetime,
    01466                          OCIInterval *reftz,
    01467                          ub1 fsprec);
    01468 NAME OCIDateTimeFromArray - OCI DateTime convert From Array format
    01469 PARAMETERS:
    01470 hndl (IN)      - Session/Env handle.
    01471 err (IN/OUT)   - error handle. If there is an error, it is
    01472                  recorded in 'err' and this function returns OCI_ERROR.
    01473                  The error recorded in 'err' can be retrieved by calling
    01474                  OCIErrorGet().
    01475 inarray (IN)   - Pointer to input array representtion of DateTime
    01476 len (IN)       - len of inarray.
    01477 type (IN)      - One of SQLT_DATE, SQLT_TIME, SQLT_TIME_TZ, SQLT_TIMESTAMP,
    01478                  SQLT_TIMESTAMP_TZ, or SQLT_TIMESTAMP_LTZ.
    01479 datetime (OUT) - Pointer to the result OCIDateTime.
    01480 reftz (IN)     - timezone interval used with SQLT_TIMESTAMP_LTZ.
    01481 fsprec (IN)    - fractionl seconds digits of precision (0-9).
    01482 DESCRIPTION:
    01483         Returns a pointer to an OCIDateTime of type type converted from
    01484         the inarray.
    01485 RETURNS:
    01486        OCI_SUCCESS if the function completes successfully.
    01487        OCI_INVALID_HANDLE if 'err' is NULL.
    01488        OCI_ERROR if
    01489          buffer too small
    01490          error retrieving timezone data
    01491          invalid region
    01492          invalid LdiDateTime type
    01493
    01494 ----------------------------------OCIRowidToChar-----------------------------
    01495 Name
    01496 OCIRowidToChar
    01497
    01498 Purpose
    01499 Converts physical/logical (universal) ROWID to chracter extended (Base 64)
    01500 representation into user provided buffer outbfp of length outbflp. After
    01501 execution outbflp contains amount of bytes converted.In case of truncation
    01502 error, outbflp contains required size to make this conversion successful
    01503 and returns ORA-1405.
    01504
    01505 Syntax
    01506 sword OCIRowidToChar( OCIRowid *rowidDesc,
    01507                       OraText *outbfp,
    01508                       ub2 *outbflp,
    01509                       OCIError *errhp)
    01510
    01511 Comments
    01512 After this conversion, ROWID in character format can be bound using
    01513 OCIBindByPos or OCIBindByName call and used to query a row at a
    01514 desired ROWID.
    01515
    01516 Parameters
    01517 rowidDesc (IN)   - rowid DESCriptor which is allocated from OCIDescritorAlloc
    01518                    and populated by a prior SQL statement execution
    01519 outbfp (OUT)     - pointer to the buffer where converted rowid in character
    01520                    representation is stored after successful execution.
    01521 outbflp (IN/OUT) - pointer to output buffer length variable.
    01522                    Before execution (IN mode) *outbflp contains the size of
    01523                    outbfp, after execution (OUT mode) *outbflp contains amount
    01524                    of bytes converted. In an event of truncation during
    01525                    conversion *outbflp contains the required length to make
    01526                    conversion successful.
    01527 errhp (IN/OUT)   - an error handle which can be passed to OCIErrorGet() for
    01528                    diagnostic information in the event of an error.
    01529
    01530 ------------------------------OCIDefineArrayOfStruct--------------------------
    01531
    01532
    01533 OCIDefineArrayOfStruct()
    01534 Name
    01535 OCI Define for Array of Structures
    01536 Purpose
    01537 This call specifies additional attributes necessary for a static array define.
    01538 Syntax
    01539 sword OCIDefineArrayOfStruct ( OCIDefine   *defnp,
    01540                              OCIError    *errhp,
    01541                              ub4         pvskip,
    01542                              ub4         indskip,
    01543                              ub4         rlskip,
    01544                              ub4         rcskip );
    01545 Comments
    01546 This call specifies additional attributes necessary for an array define,
    01547 used in an array of structures (multi-row, multi-column) fetch.
    01548 For more information about skip parameters, see the section "Skip Parameters"
    01549 on page 4-17.
    01550 Parameters
    01551 defnp (IN) - the handle to the define structure which was returned by a call
    01552 to OCIDefineByPos().
    01553 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    01554 diagnostic information in the event of an error.
    01555 pvskip (IN) - skip parameter for the next data value.
    01556 indskip (IN) - skip parameter for the next indicator location.
    01557 rlskip (IN) - skip parameter for the next return length value.
    01558 rcskip (IN) - skip parameter for the next return code.
    01559 Related Functions
    01560 OCIAttrGet()
    01561
    01562
    01563
    01564
    01565
    01566 OCIDefineByPos()
    01567 Name
    01568 OCI Define By Position
    01569 Purpose
    01570 Associates an item in a select-list with the type and output data buffer.
    01571 Syntax
    01572 sb4 OCIDefineByPos (
    01573               OCIStmt     *stmtp,
    01574               OCIDefine   **defnp,
    01575               OCIError    *errhp,
    01576               ub4         position,
    01577               dvoid       *valuep,
    01578               sb4         value_sz,
    01579               ub2         dty,
    01580               dvoid       *indp,
    01581               ub2         *rlenp,
    01582               ub2         *rcodep,
    01583               ub4         mode );
    01584 Comments
    01585 This call defines an output buffer which will receive data retreived from
    01586 Oracle. The define is a local step which is necessary when a SELECT statement
    01587 returns data to your OCI application.
    01588 This call also implicitly allocates the define handle for the select-list item.
    01589 Defining attributes of a column for a fetch is done in one or more calls. The
    01590 first call is to OCIDefineByPos(), which defines the minimal attributes
    01591 required to specify the fetch.
    01592 This call takes as a parameter a define handle, which must have been
    01593 previously allocated with a call to OCIHandleAlloc().
    01594 Following the call to OCIDefineByPos() additional define calls may be
    01595 necessary for certain data types or fetch modes:
    01596 A call to OCIDefineArrayOfStruct() is necessary to set up skip parameters
    01597 for an array fetch of multiple columns.
    01598 A call to OCIDefineObject() is necessary to set up the appropriate
    01599 attributes of a named data type fetch. In this case the data buffer pointer
    01600 in ocidefn() is ignored.
    01601 Both OCIDefineArrayOfStruct() and OCIDefineObject() must be called
    01602 after ocidefn() in order to fetch multiple rows with a column of named
    01603 data types.
    01604 For a LOB define, the buffer pointer must be a lob locator of type
    01605 OCILobLocator , allocated by the OCIDescAlloc() call. LOB locators, and not
    01606 LOB values, are always returned for a LOB column. LOB values can then be
    01607 fetched using OCI LOB calls on the fetched locator.
    01608 For NCHAR (fixed and varying length), the buffer pointer must point to an
    01609 array of bytes sufficient for holding the required NCHAR characters.
    01610 Nested table columns are defined and fetched like any other named data type.
    01611 If the mode parameter is this call is set to OCI_DYNAMIC_FETCH, the client
    01612 application can fetch data dynamically at runtime.
    01613 Runtime data can be provided in one of two ways:
    01614 callbacks using a user-defined function which must be registered with a
    01615 subsequent call to OCIDefineDynamic(). When the client library needs a
    01616 buffer to return the fetched data, the callback will be invoked and the
    01617 runtime buffers provided will return a piece or the whole data.
    01618 a polling mechanism using calls supplied by the OCI. This mode is
    01619 assumed if no callbacks are defined. In this case, the fetch call returns the
    01620 OCI_NEED_DATA error code, and a piecewise polling method is used
    01621 to provide the data.
    01622 Related Functions: For more information about using the
    01623 OCI_DYNAMIC_FETCH mode, see the section "Runtime Data
    01624 Allocation and Piecewise Operations" on page 5-16 of Volume 1..
    01625 For more information about the define step, see the section "Defining"
    01626 on page 2-30.
    01627 Parameters
    01628 stmtp (IN) - a handle to the requested SQL query operation.
    01629 defnp (IN/OUT) - a pointer to a pointer to a define handle which is implicitly
    01630 allocated by this call.  This handle is used to  store the define information
    01631 for this column.
    01632 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    01633 diagnostic information in the event of an error.
    01634 position (IN) - the position of this value in the select list. Positions are
    01635 1-based and are numbered from left to right. For example, in the SELECT
    01636 statement
    01637 SELECT empno, ssn, mgrno FROM employees;
    01638 empno is at position 1, ssn is at position 2, and mgrno is at position 3.
    01639 valuep (IN/OUT) - a pointer to a buffer or an array of buffers of the type
    01640 specified in the dty parameter. A number of buffers can be specified when
    01641 results for more than one row are desired in a single fetch call.
    01642 value_sz (IN) - the size of each valuep buffer in bytes. If the data is stored
    01643 internally in VARCHAR2 format, the number of characters desired, if different
    01644 from the buffer size in bytes, may be additionally specified by the using
    01645 OCIAttrSet().
    01646 In an NLS conversion environment, a truncation error will be generated if the
    01647 number of bytes specified is insufficient to handle the number of characters
    01648 desired.
    01649 dty (IN) - the data type. Named data type (SQLT_NTY) and REF (SQLT_REF)
    01650 are valid only if the environment has been intialized with in object mode.
    01651 indp - pointer to an indicator variable or array. For scalar data types,
    01652 pointer to sb2 or an array of sb2s. Ignored for named data types. For named
    01653 data types, a pointer to a named data type indicator structure or an array of
    01654 named data type indicator structures is associated by a subsequent
    01655 OCIDefineObject() call.
    01656 See the section "Indicator Variables" on page 2-43 for more information about
    01657 indicator variables.
    01658 rlenp (IN/OUT) - pointer to array of length of data fetched. Each element in
    01659 rlenp is the length of the data in the corresponding element in the row after
    01660 the fetch.
    01661 rcodep (OUT) - pointer to array of column-level return codes
    01662 mode (IN) - the valid modes are:
    01663 OCI_DEFAULT. This is the default mode.
    01664 OCI_DYNAMIC_FETCH. For applications requiring dynamically
    01665 allocated data at the time of fetch, this mode must be used. The user may
    01666 additionally call OCIDefineDynamic() to set up a callback function that
    01667 will be invoked to receive the dynamically allocated buffers and to set
    01668 up the memory allocate/free callbacks and the context for the callbacks.
    01669 valuep and value_sz are ignored in this mode.
    01670 Related Functions
    01671 OCIDefineArrayOfStruct(), OCIDefineDynamic(), OCIDefineObject()
    01672
    01673
    01674
    01675
    01676 OCIDefineDynamic()
    01677 Name
    01678 OCI Define Dynamic Fetch Attributes
    01679 Purpose
    01680 This call is used to set the additional attributes required if the
    01681 OCI_DYNAMIC_FETCH mode was selected in OCIDefineByPos().
    01682 Syntax
    01683 sword OCIDefineDynamic( OCIDefine   *defnp,
    01684                       OCIError    *errhp,
    01685                       dvoid       *octxp,
    01686                       OCICallbackDefine (ocbfp)(
    01687                                   dvoid             *octxp,
    01688                                   OCIDefine         *defnp,
    01689                                   ub4               iter,
    01690                                   dvoid             **bufpp,
    01691                                   ub4               **alenpp,
    01692                                   ub1               *piecep,
    01693                                   dvoid             **indpp,
    01694                                   ub2               **rcodep)  );
    01695 Comments
    01696 This call is used to set the additional attributes required if the
    01697 OCI_DYNAMIC_FETCH mode has been selected in a call to
    01698 OCIDefineByPos().
    01699 When the OCI_DYNAMIC_FETCH mode is selected, buffers will be
    01700 dynamically allocated for REF, and named data type, values to receive the
    01701 data. The pointers to these buffers will be returned.
    01702 If OCI_DYNAMIC_FETCH mode was selected, and the call to
    01703 OCIDefineDynamic() is skipped, then the application can fetch data piecewise
    01704 using OCI calls.
    01705 For more information about OCI_DYNAMIC_FETCH mode, see the section
    01706 "Runtime Data Allocation and Piecewise Operations" on page 5-16.
    01707 Parameters
    01708 defnp (IN/OUT) - the handle to a define structure returned by a call to
    01709 OCIDefineByPos().
    01710 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    01711 diagnostic information in the event of an error.
    01712 octxp (IN) - points to a context for the callback function.
    01713 ocbfp (IN) - points to a callback function. This is invoked at runtime to get
    01714 a pointer to the buffer into which the fetched data or a piece of it will be
    01715 retreived. The callback also specifies the indicator, the return code and the
    01716 lengths of the data piece and indicator. The callback has the following
    01717 parameters:
    01718 octxp (IN) - a context pointer passed as an argument to all the callback
    01719 functions.
    01720 defnp (IN) - the define handle.
    01721 iter (IN) - which row of this current fetch.
    01722 bufpp (OUT) - returns a pointer to a buffer to store the column value, ie.
    01723 *bufp points to some appropriate storage for the column value.
    01724 alenpp (OUT) - returns a pointer to the length of the buffer. *alenpp
    01725 contains the size of the buffer after return from callback. Gets set to
    01726 actual data size after fetch.
    01727 piecep (IN/OUT) - returns a piece value, as follows:
    01728 The IN value can be OCI_ONE_PIECE, OCI_FIRST_PIECE or
    01729 OCI_NEXT_PIECE.
    01730 The OUT value can be OCI_ONE_PIECE if the IN value was
    01731 OCI_ONE_PIECE.
    01732 The OUT value can be OCI_ONE_PIECE or OCI_FIRST_PIECE if
    01733 the IN value was OCI_FIRST_PIECE.
    01734 The OUT value can only be OCI_NEXT_PIECE or
    01735 OCI_LAST_PIECE if the IN value was OCI_NEXT_PIECE.
    01736 indpp (IN) - indicator variable pointer
    01737 rcodep (IN) - return code variable pointer
    01738 Related Functions
    01739 OCIAttrGet()
    01740 OCIDefineObject()
    01741
    01742
    01743
    01744
    01745 OCIDefineObject()
    01746 Name
    01747 OCI Define Named Data Type attributes
    01748 Purpose
    01749 Sets up additional attributes necessary for a Named Data Type define.
    01750 Syntax
    01751 sword OCIDefineObject ( OCIDefine       *defnp,
    01752                       OCIError        *errhp,
    01753                       CONST OCIType   *type,
    01754                       dvoid           **pgvpp,
    01755                       ub4             *pvszsp,
    01756                       dvoid           **indpp,
    01757                       ub4             *indszp );
    01758 Comments
    01759 This call sets up additional attributes necessary for a Named Data Type define.
    01760 An error will be returned if this function is called when the OCI environment
    01761 has been initialized in non-Object mode.
    01762 This call takes as a paramter a type descriptor object (TDO) of datatype
    01763 OCIType for the named data type being defined.  The TDO can be retrieved
    01764 with a call to OCITypeByName().
    01765 See the description of OCIInitialize() on page 13 - 43 for more information
    01766 about initializing the OCI process environment.
    01767 Parameters
    01768 defnp (IN/OUT) - a define handle previously allocated in a call to
    01769 OCIDefineByPos().
    01770 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    01771 diagnostic information in the event of an error.
    01772 type (IN, optional) - points to the Type Descriptor Object (TDO) which
    01773 describes the type of the program variable. Only used for program variables
    01774 of type SQLT_NTY. This parameter is optional, and may be passed as NULL
    01775 if it is not being used.
    01776 pgvpp (IN/OUT) - points to a pointer to a program variable buffer. For an
    01777 array, pgvpp points to an array of pointers. Memory for the fetched named data
    01778 type instance(s) is dynamically allocated in the object cache. At the end of
    01779 the fetch when all the values have been received, pgvpp points to the
    01780 pointer(s) to these newly allocated named data type instance(s). The
    01781 application must call OCIObjectMarkDel() to deallocate the named data type
    01782 instance(s) when they are no longer needed.
    01783 pvszsp (IN/OUT) - points to the size of the program variable. For an array, it
    01784 is an array of ub4s. On return points to the size(s) of unpickled fetched
    01785 values.
    01786 indpp (IN/OUT) - points to a pointer to the program variable buffer
    01787 containing the parallel indicator structure. For an array, points to an array
    01788 of pointers. Memory is allocated to store the indicator structures in the
    01789 object cache. At the end of the fetch when all values have been received,
    01790 indpp points to the pointer(s) to these newly allocated indicator structure(s).
    01791 indszp (IN/OUT) - points to the size(s) of the indicator structure program
    01792 variable. For an array, it is an array of ub4s. On return points to the size(s)
    01793 of the unpickled fetched indicator values.
    01794 Related Functions
    01795 OCIAttrGet()
    01796
    01797
    01798
    01799 OCIDescAlloc()
    01800 Name
    01801 OCI Get DESCriptor or lob locator
    01802 Purpose
    01803 Allocates storage to hold certain data types. The descriptors can be used as
    01804 bind or define variables.
    01805 Syntax
    01806 sword OCIDescAlloc ( CONST dvoid   *parenth,
    01807                    dvoid         **descpp,
    01808                    ub4           type,
    01809                    size_t        xtramem_sz,
    01810                    dvoid         **usrmempp);
    01811 Comments
    01812 Returns a pointer to an allocated and initialized structure, corresponding to
    01813 the type specified in type. A non-NULL descriptor or LOB locator is returned
    01814 on success. No diagnostics are available on error.
    01815 This call returns OCI_SUCCESS if successful, or OCI_INVALID_HANDLE if
    01816 an out-of-memory error occurs.
    01817 Parameters
    01818 parenth (IN) - an environment handle.
    01819 descpp (OUT) - returns a descriptor or LOB locator of desired type.
    01820 type (IN) - specifies the type of descriptor or LOB locator to be allocated.
    01821 The specific types are:
    01822 OCI_DTYPE_SNAP - specifies generation of snapshot descriptor of C
    01823 type - OCISnapshot
    01824 OCI_DTYPE_LOB - specifies generation of a LOB data type locator of C
    01825 type - OCILobLocator
    01826 OCI_DTYPE_RSET - specifies generation of a descriptor of C type
    01827 OCIResult that references a result set (a number of rows as a result of a
    01828 query). This descriptor is bound to a bind variable of data type
    01829 SQLT_RSET (result set). The descriptor has to be converted into a
    01830 statement handle using a function - OCIResultSetToStmt() - which can
    01831 then be passed to OCIDefineByPos() and OCIStmtFetch() to retrieve the
    01832 rows of the result set.
    01833 OCI_DTYPE_ROWID - specifies generation of a ROWID descriptor of C
    01834 type OCIRowid.
    01835 OCI_DTYPE_COMPLEXOBJECTCOMP - specifies generation of a
    01836 complex object retrieval descriptor of C type
    01837 OCIComplexObjectComp.
    01838 xtramemsz (IN) - specifies an amount of user memory to be allocated for use
    01839 by the application.
    01840 usrmempp (OUT) - returns a pointer to the user memory of size xtramemsz
    01841 allocated by the call for the user.
    01842 Related Functions
    01843 OCIDescFree()
    01844
    01845
    01846
    01847
    01848 OCIDescFree()
    01849 Name
    01850 OCI Free DESCriptor
    01851 Purpose
    01852 Deallocates a previously allocated descriptor.
    01853 Syntax
    01854 sword OCIDescFree ( dvoid    *descp,
    01855                   ub4      type);
    01856 Comments
    01857 This call frees up storage associated with the descriptor, corresponding to the
    01858 type specified in type. Returns OCI_SUCCESS or OCI_INVALID_HANDLE.
    01859 All descriptors must be explicitly deallocated. OCI will not deallocate a
    01860 descriptor if the environment handle is deallocated.
    01861 Parameters
    01862 descp (IN) - an allocated descriptor.
    01863 type (IN) - specifies the type of storage to be freed. The specific types are:
    01864 OCI_DTYPE_SNAP - snapshot descriptor
    01865 OCI_DTYPE_LOB - a LOB data type descriptor
    01866 OCI_DTYPE_RSET - a descriptor that references a result set (a number
    01867 of rows as a result of a query).
    01868 OCI_DTYPE_ROWID - a ROWID descriptor
    01869 OCI_DTYPE_COMPLEXOBJECTCOMP - a complex object retrieval
    01870 descriptor
    01871 Related Functions
    01872 OCIDescAlloc()
    01873
    01874
    01875
    01876 OCIDescribeAny()
    01877 Name
    01878 OCI DeSCribe Any
    01879 Purpose
    01880 Describes existing schema objects.
    01881 Syntax
    01882 sword OCIDescribeAny ( OCISvcCtx     *svchp,
    01883                      OCIError      *errhp,
    01884                      dvoid         *objptr,
    01885                      ub4           objnm_len,
    01886                      ub1           objptr_typ,
    01887                      ub1           info_level,
    01888                      ub1           objtype,
    01889                      OCIDesc       *dschp );
    01890 Comments
    01891 This is a generic describe call that describes existing schema objects: tables,
    01892 views, synonyms, procedures, functions, packages, sequences, and types. As a
    01893 result of this call, the describe handle is populated with the object-specific
    01894 attributes which can be obtained through an OCIAttrGet() call.
    01895 An OCIParamGet() on the describe handle returns a parameter descriptor for a
    01896 specified position. Parameter positions begin with 1. Calling OCIAttrGet() on
    01897 the parameter descriptor returns the specific attributes of a stored procedure
    01898 or function parameter or a table column descriptor as the case may be.
    01899 These subsequent calls do not need an extra round trip to the server because
    01900 the entire schema object description cached on the client side by
    01901 OCIDescribeAny(). Calling OCIAttrGet() on the describe handle can also return
    01902 the total number of positions.
    01903 See the section "Describing" on page 2-33 for more information about describe
    01904 operations.
    01905 Parameters
    01906 TO BE UPDATED
    01907 svchp (IN/OUT) - a service context handle.
    01908 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    01909 diagnostic information in the event of an error.
    01910 objptr (IN) - the name of the object (a null-terminated string) to be
    01911 described. Only procedure or function names are valid when connected to an
    01912 Oracle7 Server.
    01913 objptr_len (IN) - the length of the string. Must be non-zero.
    01914 objptr_typ (IN) - Must be OCI_OTYPE_NAME, OCI_OTYPE_REF, or OCI_OTYPE_PTR.
    01915 info_level (IN) - reserved for future extensions. Pass OCI_DEFAULT.
    01916 objtype (IN/OUT) - object type.
    01917 dschp (IN/OUT) - a describe handle that is populated with describe
    01918 information about the object after the call.
    01919 Related Functions
    01920 OCIAttrGet()
    01921
    01922
    01923
    01924 OCIEnvCreate()
    01925 Name
    01926 OCI ENVironment CREATE
    01927 Purpose
    01928 This function creates and initializes an environment for the rest of
    01929 the OCI functions to work under.  This call is a replacement for both
    01930 the OCIInitialize and OCIEnvInit calls.
    01931 Syntax
    01932 sword OCIEnvCreate  ( OCIEnv        **envhpp,
    01933                       ub4           mode,
    01934                       CONST dvoid   *ctxp,
    01935                       CONST dvoid   *(*malocfp)
    01936                                     (dvoid *ctxp,
    01937                                         size_t size),
    01938                       CONST dvoid   *(*ralocfp)
    01939                                     (dvoid *ctxp,
    01940                                        dvoid *memptr,
    01941                                        size_t newsize),
    01942                       CONST void    (*mfreefp)
    01943                                     ( dvoid *ctxp,
    01944                                        dvoid *memptr))
    01945                       size_t    xtramemsz,
    01946                       dvoid     **usrmempp );
    01947
    01948 Comments
    01949 This call creates an environment for all the OCI calls using the modes
    01950 specified by the user. This call can be used instead of the two calls
    01951 OCIInitialize and OCIEnvInit. This function returns an environment handle
    01952 which is then used by the remaining OCI functions. There can be multiple
    01953 environments in OCI each with its own environment modes.  This function
    01954 also performs any process level initialization if required by any mode.
    01955 For example if the user wants to initialize an environment as OCI_THREADED,
    01956 then all libraries that are used by OCI are also initialized in the
    01957 threaded mode.
    01958
    01959 This call should be invoked before anny other OCI call and should be used
    01960 instead of the OCIInitialize and OCIEnvInit calls. This is the recommended
    01961 call, although OCIInitialize and OCIEnvInit calls will still be supported
    01962 for backward compatibility.
    01963
    01964 envpp (OUT) - a pointer to a handle to the environment.
    01965 mode (IN) - specifies initialization of the mode. The valid modes are:
    01966 OCI_DEFAULT - default mode.
    01967 OCI_THREADED - threaded environment. In this mode, internal data
    01968 structures are protected from concurrent accesses by multiple threads.
    01969 OCI_OBJECT - will use navigational object interface.
    01970 ctxp (IN) - user defined context for the memory call back routines.
    01971 malocfp (IN) - user-defined memory allocation function. If mode is
    01972 OCI_THREADED, this memory allocation routine must be thread safe.
    01973 ctxp - context pointer for the user-defined memory allocation function.
    01974 size - size of memory to be allocated by the user-defined memory
    01975 allocation function
    01976 ralocfp (IN) - user-defined memory re-allocation function. If mode is
    01977 OCI_THREADED, this memory allocation routine must be thread safe.
    01978 ctxp - context pointer for the user-defined memory reallocation
    01979 function.
    01980 memp - pointer to memory block
    01981 newsize - new size of memory to be allocated
    01982 mfreefp (IN) - user-defined memory free function. If mode is
    01983 OCI_THREADED, this memory free routine must be thread safe.
    01984 ctxp - context pointer for the user-defined memory free function.
    01985 memptr - pointer to memory to be freed
    01986 xtramemsz (IN) - specifies the amount of user memory to be allocated.
    01987 usrmempp (OUT) - returns a pointer to the user memory of size xtramemsz
    01988 allocated by the call for the user.
    01989
    01990 Example
    01991
    01992 Related Functions
    01993 OCIInitialize, OCIEnvInit
    01994
    01995 OCIEnvNlsCreate()
    01996 Name
    01997 OCI ENVironment CREATE with NLS info
    01998 Purpose
    01999 This function does almost everything OCIEnvCreate does, plus enabling setting
    02000 of charset and ncharset programmatically, except OCI_UTF16 mode.
    02001 Syntax
    02002 sword OCIEnvNlsCreate(OCIEnv        **envhpp,
    02003                       ub4           mode,
    02004                       dvoid         *ctxp,
    02005                       dvoid         *(*malocfp)
    02006                                     (dvoid *ctxp,
    02007                                         size_t size),
    02008                       dvoid         *(*ralocfp)
    02009                                     (dvoid *ctxp,
    02010                                        dvoid *memptr,
    02011                                        size_t newsize),
    02012                       void          (*mfreefp)
    02013                                     (dvoid *ctxp,
    02014                                        dvoid *memptr),
    02015                       size_t        xtramemsz,
    02016                       dvoid         **usrmempp,
    02017                       ub2           charset,
    02018                       ub2           ncharset)
    02019 Comments
    02020 The charset and ncharset must be both zero or non-zero.
    02021 The parameters have the same meaning as the ones in OCIEnvCreate().
    02022 When charset or ncharset is non-zero, the corresponding character set will
    02023 be used to replace the ones specified in NLS_LANG or NLS_NCHAR. Moreover,
    02024 OCI_UTF16ID is allowed to be set as charset and ncharset.
    02025 On the other hand, OCI_UTF16 mode is deprecated with this function.
    02026 Applications can achieve the same effects by setting
    02027 both charset and ncharset as OCI_UTF16ID.
    02028
    02029
    02030 OCIEnvInit()
    02031 Name
    02032 OCI INITialize environment
    02033 Purpose
    02034 This call initializes the OCI environment handle.
    02035 Syntax
    02036 sword OCIEnvInit ( OCIEnv    **envp,
    02037                  ub4       mode,
    02038                  size_t    xtramemsz,
    02039                  dvoid     **usrmempp );
    02040 Comments
    02041 Initializes the OCI environment handle. No changes are done on an initialized
    02042 handle. If OCI_ERROR or OCI_SUCCESS_WITH_INFO is returned, the
    02043 environment handle can be used to obtain ORACLE specific errors and
    02044 diagnostics.
    02045 This call is processed locally, without a server round-trip.
    02046 Parameters
    02047 envpp (OUT) - a pointer to a handle to the environment.
    02048 mode (IN) - specifies initialization of an environment mode. The only valid
    02049 mode is OCI_DEFAULT for default mode
    02050 xtramemsz (IN) - specifies the amount of user memory to be allocated.
    02051 usrmempp (OUT) - returns a pointer to the user memory of size xtramemsz
    02052 allocated by the call for the user.
    02053 Example
    02054 See the description of OCISessionBegin() on page 13-84 for an example showing
    02055 the use of OCIEnvInit().
    02056 Related Functions
    02057
    02058
    02059
    02060
    02061 OCIErrorGet()
    02062 Name
    02063 OCI Get Diagnostic Record
    02064 Purpose
    02065 Returns an error message in the buffer provided and an ORACLE error.
    02066 Syntax
    02067 sword OCIErrorGet ( dvoid      *hndlp,
    02068                   ub4        recordno,
    02069                   OraText       *sqlstate,
    02070                   ub4        *errcodep,
    02071                   OraText       *bufp,
    02072                   ub4        bufsiz,
    02073                   ub4        type );
    02074 Comments
    02075 Returns an error message in the buffer provided and an ORACLE error.
    02076 Currently does not support SQL state. This call can be called a multiple
    02077 number of times if there are more than one diagnostic record for an error.
    02078 The error handle is originally allocated with a call to OCIHandleAlloc().
    02079 Parameters
    02080 hndlp (IN) - the error handle, in most cases, or the environment handle (for
    02081 errors on OCIEnvInit(), OCIHandleAlloc()).
    02082 recordno (IN) - indicates the status record from which the application seeks
    02083 info. Starts from 1.
    02084 sqlstate (OUT) - Not supported in Version 8.0.
    02085 errcodep (OUT) - an ORACLE Error is returned.
    02086 bufp (OUT) - the error message text is returned.
    02087 bufsiz (IN) - the size of the buffer provide to get the error message.
    02088 type (IN) - the type of the handle.
    02089 Related Functions
    02090 OCIHandleAlloc()
    02091
    02092 OCIExtractInit
    02093 Name
    02094 OCI Extract Initialize
    02095 Purpose
    02096 This function initializes the parameter manager.
    02097 Syntax
    02098 sword OCIExtractInit(dvoid *hndl, OCIError *err);
    02099 Comments
    02100 It must be called before calling any other parameter manager routine. The NLS
    02101 information is stored inside the parameter manager context and used in
    02102 subsequent calls to OCIExtract routines.
    02103 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    02104 Parameters
    02105 hndl (IN/OUT) - The OCI environment or session handle.
    02106 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02107                err and this function returns OCI_ERROR. Diagnostic information
    02108                can be obtained by calling OCIErrorGet().
    02109 Related Functions
    02110 OCIExtractTerm()
    02111
    02112 OCIExtractTerm
    02113 Name
    02114 OCI Extract Terminate
    02115 Purpose
    02116 This function releases all dynamically allocated storage and may perform
    02117 other internal bookkeeping functions.
    02118 Syntax
    02119 sword OCIExtractTerm(dvoid *hndl, OCIError *err);
    02120 Comments
    02121 It must be called when the parameter manager is no longer being used.
    02122 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    02123 Parameters
    02124 hndl (IN/OUT) - The OCI environment or session handle.
    02125 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02126                err and this function returns OCI_ERROR. Diagnostic information
    02127                can be obtained by calling OCIErrorGet().
    02128 Related Functions
    02129 OCIExtractInit()
    02130
    02131 OCIExtractReset
    02132 Name
    02133 OCI Extract Reset
    02134 Purpose
    02135 The memory currently used for parameter storage, key definition storage, and
    02136 parameter value lists is freed and the structure is reinitialized.
    02137 Syntax
    02138 sword OCIExtractReset(dvoid *hndl, OCIError *err);
    02139 Comments
    02140 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    02141 Parameters
    02142 hndl (IN/OUT) - The OCI environment or session handle.
    02143 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02144                err and this function returns OCI_ERROR. Diagnostic information
    02145                can be obtained by calling OCIErrorGet().
    02146 Related Functions
    02147
    02148 OCIExtractSetNumKeys
    02149 Name
    02150 OCI Extract Set Number of Keys
    02151 Purpose
    02152 Informs the parameter manager of the number of keys that will be registered.
    02153 Syntax
    02154 sword OCIExtractSetNumKeys(dvoid *hndl, OCIError *err, uword numkeys);
    02155 Comments
    02156 This routine must be called prior to the first call of OCIExtractSetKey().
    02157 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    02158 Parameters
    02159 hndl (IN/OUT) - The OCI environment or session handle.
    02160 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02161                err and this function returns OCI_ERROR. Diagnostic information
    02162                can be obtained by calling OCIErrorGet().
    02163 numkeys (IN) - The number of keys that will be registered with
    02164                OCIExtractSetKey().
    02165 Related Functions
    02166 OCIExtractSetKey()
    02167
    02168 OCIExtractSetKey
    02169 Name
    02170 OCI Extract Set Key definition
    02171 Purpose
    02172 Registers information about a key with the parameter manager.
    02173 Syntax
    02174 sword OCIExtractSetKey(dvoid *hndl, OCIError *err, CONST OraText *name,
    02175                        ub1 type, ub4 flag, CONST dvoid *defval,
    02176                        CONST sb4 *intrange, CONST OraText *CONST *strlist);
    02177 Comments
    02178 This routine must be called after calling OCIExtractSetKey() and before
    02179 calling OCIExtractFromFile() or OCIExtractFromStr().
    02180 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    02181 Parameters
    02182 hndl (IN/OUT) - The OCI environment or session handle.
    02183 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02184                err and this function returns OCI_ERROR. Diagnostic information
    02185                can be obtained by calling OCIErrorGet().
    02186 name (IN) - The name of the key.
    02187 type (IN) - The type of the key (OCI_EXTRACT_TYPE_INTEGER,
    02188             OCI_EXTRACT_TYPE_OCINUM, OCI_EXTRACT_TYPE_STRING, or
    02189             OCI_EXTRACT_TYPE_BOOLEAN).
    02190 flag (IN) - Set to OCI_EXTRACT_MULTIPLE if the key can take multiple values
    02191             or 0 otherwise.
    02192 defval (IN) - Set to the default value for the key.  May be NULL if there is
    02193                no default.  A string default must be a (text*) type, an
    02194                integer default must be an (sb4*) type, and a boolean default
    02195                must be a (ub1*) type.
    02196 intrange (IN) - Starting and ending values for the allowable range of integer
    02197                 values.  May be NULL if the key is not an integer type or if
    02198                 all integer values are acceptable.
    02199 strlist (IN) - List of all acceptable text strings for the key.  May be NULL
    02200                if the key is not a string type or if all text values are
    02201                acceptable.
    02202 Related Functions
    02203 OCIExtractSetNumKeys()
    02204
    02205 OCIExtractFromFile
    02206 Name
    02207 OCI Extract parameters From File
    02208 Purpose
    02209 The keys and their values in the given file are processed.
    02210 Syntax
    02211 sword OCIExtractFromFile(dvoid *hndl, OCIError *err, ub4 flag,
    02212                          OraText *filename);
    02213 Comments
    02214 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    02215 Parameters
    02216 hndl (IN/OUT) - The OCI environment or session handle.
    02217 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02218                err and this function returns OCI_ERROR. Diagnostic information
    02219                can be obtained by calling OCIErrorGet().
    02220 flag (IN) - Zero or has one or more of the following bits set:
    02221            OCI_EXTRACT_CASE_SENSITIVE, OCI_EXTRACT_UNIQUE_ABBREVS, or
    02222            OCI_EXTRACT_APPEND_VALUES.
    02223 filename (IN) - Null-terminated filename string.
    02224 Related Functions
    02225
    02226 OCIExtractFromStr
    02227 Name
    02228 OCI Extract parameters From String
    02229 Purpose
    02230 The keys and their values in the given string are processed.
    02231 Syntax
    02232 sword OCIExtractFromStr(dvoid *hndl, OCIError *err, ub4 flag, OraText *input);
    02233 Comments
    02234 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    02235 Parameters
    02236 hndl (IN/OUT) - The OCI environment or session handle.
    02237 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02238                err and this function returns OCI_ERROR. Diagnostic information
    02239                can be obtained by calling OCIErrorGet().
    02240 flag (IN) - Zero or has one or more of the following bits set:
    02241            OCI_EXTRACT_CASE_SENSITIVE, OCI_EXTRACT_UNIQUE_ABBREVS, or
    02242            OCI_EXTRACT_APPEND_VALUES.
    02243 input (IN) - Null-terminated input string.
    02244 Related Functions
    02245
    02246 OCIExtractToInt
    02247 Name
    02248 OCI Extract To Integer
    02249 Purpose
    02250 Gets the integer value for the specified key.
    02251 Syntax
    02252 sword OCIExtractToInt(dvoid *hndl, OCIError *err, OraText *keyname,
    02253                       uword valno, sb4 *retval);
    02254 Comments
    02255 The valno'th value (starting with 0) is returned.
    02256 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR.
    02257 OCI_NO_DATA means that there is no valno'th value for this key.
    02258 Parameters
    02259 hndl (IN) - The OCI environment or session handle.
    02260 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02261                err and this function returns OCI_ERROR. Diagnostic information
    02262                can be obtained by calling OCIErrorGet().
    02263 keyname (IN) - Key name.
    02264 valno (IN) - Which value to get for this key.
    02265 retval (OUT) - The actual integer value.
    02266 Related Functions
    02267
    02268 OCIExtractToBool
    02269 Name
    02270 OCI Extract To Boolean
    02271 Purpose
    02272 Gets the boolean value for the specified key.
    02273 Syntax
    02274 sword OCIExtractToBool(dvoid *hndl, OCIError *err, OraText *keyname,
    02275                        uword valno, ub1 *retval);
    02276 Comments
    02277 The valno'th value (starting with 0) is returned.
    02278 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR.
    02279 OCI_NO_DATA means that there is no valno'th value for this key.
    02280 Parameters
    02281 hndl (IN) - The OCI environment or session handle.
    02282 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02283                err and this function returns OCI_ERROR. Diagnostic information
    02284                can be obtained by calling OCIErrorGet().
    02285 keyname (IN) - Key name.
    02286 valno (IN) - Which value to get for this key.
    02287 retval (OUT) - The actual boolean value.
    02288 Related Functions
    02289
    02290 OCIExtractToStr
    02291 Name
    02292 OCI Extract To String
    02293 Purpose
    02294 Gets the string value for the specified key.
    02295 Syntax
    02296 sword OCIExtractToStr(dvoid *hndl, OCIError *err, OraText *keyname,
    02297                       uword valno, OraText *retval, uword buflen);
    02298 Comments
    02299 The valno'th value (starting with 0) is returned.
    02300 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR.
    02301 OCI_NO_DATA means that there is no valno'th value for this key.
    02302 Parameters
    02303 hndl (IN) - The OCI environment or session handle.
    02304 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02305                err and this function returns OCI_ERROR. Diagnostic information
    02306                can be obtained by calling OCIErrorGet().
    02307 keyname (IN) - Key name.
    02308 valno (IN) - Which value to get for this key.
    02309 retval (OUT) - The actual null-terminated string value.
    02310 buflen (IN) - The length of the buffer for retval.
    02311 Related Functions
    02312
    02313 Note: The following OCIExtract functions are unavailable in this release
    02314
    02315 OCIExtractToOCINum
    02316 Name
    02317 OCI Extract To OCI Number
    02318 Purpose
    02319 Gets the OCINumber value for the specified key.
    02320 Syntax
    02321 sword OCIExtractToOCINum(dvoid *hndl, OCIError *err, OraText *keyname,
    02322                          uword valno, OCINumber *retval);
    02323 Comments
    02324 The valno'th value (starting with 0) is returned.
    02325 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, or OCI_ERROR.
    02326 OCI_NO_DATA means that there is no valno'th value for this key.
    02327 Parameters
    02328 hndl (IN) - The OCI environment or session handle.
    02329 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02330                err and this function returns OCI_ERROR. Diagnostic information
    02331                can be obtained by calling OCIErrorGet().
    02332 keyname (IN) - Key name.
    02333 valno (IN) - Which value to get for this key.
    02334 retval (OUT) - The actual OCINumber value.
    02335 Related Functions
    02336
    02337 OCIExtractToList
    02338 Name
    02339 OCI Extract To parameter List
    02340 Purpose
    02341 Generates a list of parameters from the parameter structures that are stored
    02342 in memory.
    02343 Syntax
    02344 sword OCIExtractToList(dvoid *hndl, OCIError *err, uword *numkeys);
    02345 Comments
    02346 Must be called before OCIExtractValues() is called.
    02347 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    02348 Parameters
    02349 hndl (IN) - The OCI environment or session handle.
    02350 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02351                err and this function returns OCI_ERROR. Diagnostic information
    02352                can be obtained by calling OCIErrorGet().
    02353 numkeys (OUT) - Number of distinct keys stored in memory.
    02354 Related Functions
    02355 OCIExtractFromList()
    02356
    02357 OCIExtractFromList
    02358 Name
    02359 OCI Extract From parameter List
    02360 Purpose
    02361 Generates a list of values for the a parameter in the parameter list.
    02362 Syntax
    02363 sword OCIExtractFromList(dvoid *hndl, OCIError *err, uword index,
    02364                          OraText *name, ub1 *type, uword *numvals,
    02365                          dvoid ***values);
    02366 Comments
    02367 Parameters are specified by an index. OCIExtractToList() must be called prior
    02368 to calling this routine to generate the parameter list from the parameter
    02369 structures that are stored in memory.
    02370 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    02371 Parameters
    02372 hndl (IN) - The OCI environment or session handle.
    02373 err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    02374                err and this function returns OCI_ERROR. Diagnostic information
    02375                can be obtained by calling OCIErrorGet().
    02376 name (OUT) - Name of the key for the current parameter.
    02377 type (OUT) - Type of the current parameter (OCI_EXTRACT_TYPE_STRING,
    02378              OCI_EXTRACT_TYPE_INTEGER, OCI_EXTRACT_TYPE_OCINUM, or
    02379              OCI_EXTRACT_TYPE_BOOLEAN)
    02380 numvals (OUT) - Number of values for this parameter.
    02381 values (OUT) - The values for this parameter.
    02382 Related Functions
    02383 OCIExtractToList()
    02384
    02385
    02386 ************************  OCIFileClose() ***********************************
    02387
    02388 Name
    02389  OCIFileClose - Oracle Call Interface FILE i/o CLOSE
    02390
    02391 Purpose
    02392  Close a previously opened file.
    02393
    02394 Syntax
    02395  sword OCIFileClose ( dvoid             *hndl,
    02396                       OCIError          *err,
    02397                       OCIFileObject     *filep )
    02398
    02399 Comments
    02400  This function will close a previously opened file. If the function succeeds
    02401  then OCI_SUCCESS will be returned, else OCI_ERROR.
    02402
    02403 Parameters
    02404  hndl  (IN) - the OCI environment or session handle.
    02405  err (OUT) - the OCI error handle
    02406  filep (IN) - the OCIFile file object
    02407
    02408 Related Functions
    02409  OCIFileOpen.
    02410
    02411
    02412
    02413 ********************* OCIFileExists() **************************************
    02414
    02415 Name
    02416  OCIFileExists - Oracle Call Interface FILE i/o EXIST
    02417
    02418 Purpose
    02419  Check to see if the file exists.
    02420
    02421 Syntax
    02422  sword OCIFileExists ( dvoid           *hndl,
    02423                       OCIError         *err,
    02424                       OraText          *filename,
    02425                       OraText          *path,
    02426                       ub1              *flag )
    02427
    02428 Comments
    02429  This function will set the flag to TRUE if the file exists else it will
    02430  be set to FALSE.
    02431  The function will return OCI_ERROR if any error is encountered, else
    02432  it will return OCI_ERROR.
    02433
    02434 Parameters
    02435  hndl(IN) - OCI environment or session handle
    02436  err(OUT) - OCI error handle
    02437  filename(IN) - filename
    02438  path(IN) - path of the file
    02439  flag(OUT) - whether the file exists or not
    02440
    02441 Related Functions.
    02442  None.
    02443
    02444
    02445  **************************** OCIFileFlush() ******************************
    02446
    02447
    02448 Name
    02449  OCIFileFlush - Oracle Call Interface File i/o FLUSH
    02450
    02451 Purpose
    02452  Flush the buffers associated with the file to the disk.
    02453
    02454 Syntax
    02455  sword OCIFileFlush ( dvoid             *hndl,
    02456                       OCIError          *err,
    02457                       OCIFileObject     *filep )
    02458
    02459 Comments
    02460  The function will return OCI_ERROR if any error is encountered, else
    02461  it will return OCI_ERROR.
    02462
    02463 Parameters
    02464  hndl (IN) - the OCI environment or session handle.
    02465  err (OUT) - the OCI error handle
    02466  filep (IN) - the OCIFile file object
    02467
    02468 Related Functions
    02469  OCIFileOpen, OCIFileWrite
    02470
    02471
    02472
    02473  *************************** OCIFileGetLength() ****************************
    02474
    02475 Name
    02476  OCIFileGetLength - Oracle Call Interface FILE i/o GET file LENGTH
    02477
    02478 Purpose
    02479  Get the length of a file.
    02480
    02481 Syntax
    02482  OCIFileGetLength(dvoid           *hndl,
    02483                   OCIError        *err,
    02484                   OraText         *filename,
    02485                   OraText         *path,
    02486                   ubig_ora        *lenp )
    02487
    02488 Comments
    02489  The length of the file will be returned in lenp.
    02490  The function will return OCI_ERROR if any error is encountered, else
    02491  it will return OCI_ERROR.
    02492
    02493 Parameters
    02494  hndl (IN) - the OCI environment or session handle.
    02495  err (OUT) - the OCI error handle.  If  there is an error, it is recorded
    02496  in err and this function returns OCI_ERROR.  Diagnostic information can be
    02497  obtained by calling OCIErrorGet().
    02498  filename (IN) - file name.
    02499  path (IN) - path of the file.
    02500  lenp (OUT) - On output, it is the length of the file in bytes.
    02501  is the number of bytes in the file.
    02502
    02503 Related Functions
    02504  None.
    02505
    02506
    02507
    02508 ******************************** OCIFileInit() *****************************
    02509
    02510 Name
    02511  OCIFileInit - Oracle Call Interface FILE i/o INITialize
    02512
    02513 Purpose
    02514  Initialize the OCI File I/O package and create the OCIFile context.
    02515
    02516 Syntax
    02517  sword OCIFileInit ( dvoid *hndl,
    02518                      OCIError *err)
    02519
    02520 Comments
    02521  This function should be called before any of the OCIFile functions are
    02522  used.
    02523  The function will return OCI_ERROR if any error is encountered, else
    02524  it will return OCI_ERROR.
    02525
    02526 Parameters
    02527  hndl(IN) - OCI environment or session handle.
    02528  err(OUT) - OCI error structure.
    02529
    02530 Related Functions
    02531  OCIFileTerm
    02532
    02533
    02534
    02535 ********************************* OCIFileOpen() *****************************
    02536
    02537 Name
    02538  OCIFileOpen - Oracle Call Interface File i/o OPEN
    02539
    02540 Purpose
    02541      Open a file.
    02542
    02543 Syntax
    02544  sword OCIFileOpen ( dvoid               *hndl,
    02545                      OCIError            *err,
    02546                      OCIFileObject      **filep,
    02547                      OraText             *filename,
    02548                      OraText             *path,
    02549                      ub4                  mode,
    02550                      ub4                  create,
    02551                      ub4                  type )
    02552
    02553 Comments
    02554  OCIFileOpen returns a handle to the open file in filep if the file is
    02555  successfully opened.
    02556  If one wants to use the standard file objects (stdin, stdout & stderr)
    02557  then OCIFileOpen whould be called with the type filed containing the
    02558  appropriate type (see the parameter type). If any of the standard files
    02559  are specified then filename, path, mode and create are ignored.
    02560  The function will return OCI_ERROR if any error is encountered, else
    02561  it will return OCI_ERROR.
    02562
    02563 Parameters
    02564  hndl (OUT) - the OCI environment or session handle.
    02565  err (OUT) - the OCI error handle.  If  there is an error, it is recorded
    02566  in err and this function returns OCI_ERROR.  Diagnostic information can be
    02567  obtained by calling OCIErrorGet().
    02568  filep (OUT) - the file object to be returned.
    02569  filename (IN) - file name (NULL terminated string).
    02570  path (IN) - path of the file (NULL terminated string).
    02571  mode - mode in which to open the file (valid modes are OCI_FILE_READONLY,
    02572  OCI_FILE_WRITEONLY, OCI_FILE_READ_WRITE).
    02573  create - should the file be created if it does not exist. Valid values
    02574  are:
    02575      OCI_FILE_TRUNCATE - create a file regardless of whether or not it exists.
    02576                         If the file already exists overwrite it.
    02577      OCI_FILE_EXIST - open it if it exists, else fail.
    02578      OCI_FILE_EXCL - fail if the file exists, else create.
    02579      OCI_FILE_CREATE - open the file if it exists, and create it if it doesn't.
    02580      OCI_FILE_APPEND - set the file pointer to the end of the file prior to
    02581                       writing(this flag can be OR'ed with OCI_FILE_EXIST or
    02582                       OCI_FILE_CREATE).
    02583 type - file type. Valid values are OCI_FILE_TEXT, OCI_FILE_BIN,
    02584        OCI_FILE_STDIN, OCI_FILE_STDOUT and OCI_FILE_STDERR.
    02585        If any of the standard files are specified then filename, path, mode
    02586        and create are ignored.
    02587
    02588 Related Functions.
    02589  OCIFileClose
    02590
    02591
    02592
    02593 ************************** OCIFileRead() ************************************
    02594
    02595 Name
    02596  OCIFileRead - Oracle Call Interface FILE i/o READ
    02597
    02598 Purpose
    02599  Read from a file into a buffer.
    02600
    02601 Syntax
    02602  sword OCIFileRead ( dvoid            *hndl,
    02603                      OCIError         *err,
    02604                      OCIFileObject    *filep,
    02605                      dvoid            *bufp,
    02606                      ub4               bufl,
    02607                      ub4              *bytesread )
    02608
    02609 Comments
    02610  Upto bufl bytes from the file will be read into bufp. The user should
    02611  allocate memory for the buffer.
    02612  The number of bytes read would be in bytesread.
    02613  The function will return OCI_ERROR if any error is encountered, else
    02614  it will return OCI_ERROR.
    02615
    02616 Parameters
    02617  hndl (IN) - the OCI environment or session handle.
    02618  err (OUT) - the OCI error handle.  If  there is an error, it is recorded
    02619  in err and this function returns OCI_ERROR.  Diagnostic information can be
    02620  obtained by calling OCIErrorGet().
    02621  filep (IN/OUT) - a File Object that uniquely references the file.
    02622  bufp (IN) - the pointer to a buffer into which the data will be read. The
    02623  length of the allocated memory is assumed to be bufl.
    02624  bufl - the length of the buffer in bytes.
    02625  bytesread (OUT) - the number of bytes read.
    02626
    02627 Related Functions
    02628  OCIFileOpen, OCIFileSeek, OCIFileWrite
    02629
    02630
    02631
    02632 ****************************** OCIFileSeek() ******************************
    02633
    02634 Name
    02635  OCIFileSeek - Oracle Call Interface FILE i/o SEEK
    02636
    02637 Purpose
    02638  Perfom a seek to a byte position.
    02639
    02640 Syntax
    02641  sword OCIFileSeek ( dvoid           *hndl,
    02642                      OCIError        *err,
    02643                      OCIFileObject   *filep,
    02644                      uword            origin,
    02645                      ubig_ora         offset,
    02646                      sb1              dir)
    02647
    02648 Comments
    02649  The function will return OCI_ERROR if any error is encountered, else
    02650  it will return OCI_ERROR.
    02651
    02652 Parameters
    02653  hndl (IN) - the OCI environment or session handle.
    02654  err (OUT) - the OCI error handle.  If  there is an error, it is recorded
    02655  in err and this function returns OCI_ERROR.  Diagnostic information can be
    02656  obtained by calling OCIErrorGet().
    02657  filep (IN/OUT) - a file handle that uniquely references the file.
    02658  origin - The starting point we want to seek from. NOTE: The starting
    02659  point may be OCI_FILE_SEEK_BEGINNING (beginning), OCI_FILE_SEEK_CURRENT
    02660  (current position), or OCI_FILE_SEEK_END (end of file).
    02661  offset - The number of bytes from the origin we want to start reading from.
    02662  dir - The direction we want to go from the origin. NOTE: The direction
    02663  can be either OCI_FILE_FORWARD or OCI_FILE_BACKWARD.
    02664
    02665 Related Function
    02666  OCIFileOpen, OCIFileRead, OCIFileWrite
    02667
    02668
    02669
    02670 *************************** OCIFileTerm() **********************************
    02671
    02672 Name
    02673  OCIFileTerm - Oracle Call Interface FILE i/o TERMinate
    02674
    02675 Purpose
    02676  Terminate the OCI File I/O package and destroy the OCI File context.
    02677
    02678 Syntax
    02679  sword OCIFileTerm ( dvoid *hndl,
    02680                      OCIError *err )
    02681
    02682 Comments
    02683  After this function has been called no OCIFile function should be used.
    02684  The function will return OCI_ERROR if any error is encountered, else
    02685  it will return OCI_ERROR.
    02686
    02687 Parameters
    02688  hndl(IN) - OCI environment or session handle.
    02689  err(OUT) - OCI error structure.
    02690
    02691 Related Functions
    02692  OCIFileInit
    02693
    02694
    02695 ********************************* OCIFileWrite() ****************************
    02696
    02697 Name
    02698  OCIFileWrite - Oracle Call Interface FILE i/o WRITE
    02699
    02700 Purpose
    02701   Write data from buffer into a file.
    02702
    02703 Syntax
    02704  sword OCIFileWrite ( dvoid            *hndl,
    02705                       OCIError         *err,
    02706                       OCIFileObject    *filep,
    02707                       dvoid            *bufp,
    02708                       ub4               buflen
    02709                       ub4              *byteswritten )
    02710
    02711 Comments
    02712  The number of bytes written will be in *byteswritten.
    02713  The function will return OCI_ERROR if any error is encountered, else
    02714  it will return OCI_ERROR.
    02715
    02716 Parameters
    02717  hndl (IN) - the OCI environment or session handle.
    02718  err (OUT) - the OCI error handle.  If  there is an error, it is recorded
    02719  in err and this function returns OCI_ERROR.  Diagnostic information can be
    02720  obtained by calling OCIErrorGet().
    02721  filep (IN/OUT) - a file handle that uniquely references the file.
    02722  bufp (IN) - the pointer to a buffer from which the data will be written.
    02723  The length of the allocated memory is assumed to be the value passed
    02724  in bufl.
    02725  bufl - the length of the buffer in bytes.
    02726  byteswritten (OUT) - the number of bytes written.
    02727
    02728 Related Functions
    02729  OCIFileOpen, OCIFileSeek, OCIFileRead
    02730
    02731
    02732
    02733
    02734
    02735 OCIHandleAlloc()
    02736 Name
    02737 OCI Get HaNDLe
    02738 Purpose
    02739 This call returns a pointer to an allocated and initialized handle.
    02740 Syntax
    02741 sword OCIHandleAlloc ( CONST dvoid   *parenth,
    02742                      dvoid         **hndlpp,
    02743                      ub4           type,
    02744                      size_t        xtramem_sz,
    02745                      dvoid         **usrmempp);
    02746 Comments
    02747 Returns a pointer to an allocated and initialized structure, corresponding to
    02748 the type specified in type. A non-NULL handle is returned on success. Bind
    02749 handle and define handles are allocated with respect to a statement handle. All
    02750 other handles are allocated with respect to an environment handle which is
    02751 passed in as a parent handle.
    02752 No diagnostics are available on error. This call returns OCI_SUCCESS if
    02753 successful, or OCI_INVALID_HANDLE if an out-of-memory error occurs.
    02754 Handles must be allocated using OCIHandleAlloc() before they can be passed
    02755 into an OCI call.
    02756 Parameters
    02757 parenth (IN) - an environment or a statement handle.
    02758 hndlpp (OUT) - returns a handle to a handle type.
    02759 type (IN) - specifies the type of handle to be allocated. The specific types
    02760 are:
    02761 OCI_HTYPE_ERROR - specifies generation of an error report handle of
    02762 C type OCIError
    02763 OCI_HTYPE_SVCCTX - specifies generation of a service context handle
    02764 of C type OCISvcCtx
    02765 OCI_HTYPE_STMT - specifies generation of a statement (application
    02766 request) handle of C type OCIStmt
    02767 OCI_HTYPE_BIND - specifies generation of a bind information handle
    02768 of C type OCIBind
    02769 OCI_HTYPE_DEFINE - specifies generation of a column definition
    02770 handle of C type OCIDefine
    02771 OCI_HTYPE_DESCRIBE  - specifies generation of a select list
    02772 description handle of C type OCIDesc
    02773 OCI_HTYPE_SERVER - specifies generation of a server context handle
    02774 of C type OCIServer
    02775 OCI_HTYPE_SESSION - specifies generation of an authentication
    02776 context handle of C type OCISession
    02777 OCI_HTYPE_TRANS - specifies generation of a transaction context
    02778 handle of C type OCITrans
    02779 OCI_HTYPE_COMPLEXOBJECT - specifies generation of a complex
    02780 object retrieval handle of C type OCIComplexObject
    02781 OCI_HTYPE_SECURITY - specifies generation of a security handle of C
    02782 type OCISecurity
    02783 xtramem_sz (IN) - specifies an amount of user memory to be allocated.
    02784 usrmempp (OUT) - returns a pointer to the user memory of size xtramemsz
    02785 allocated by the call for the user.
    02786 Related Functions
    02787 OCIHandleFree()
    02788
    02789
    02790
    02791 OCIHandleFree()
    02792 Name
    02793 OCI Free HaNDLe
    02794 Purpose
    02795 This call explicitly deallocates a handle.
    02796 Syntax
    02797 sword OCIHandleFree ( dvoid     *hndlp,
    02798                     ub4       type);
    02799 Comments
    02800 This call frees up storage associated with a handle, corresponding to the type
    02801 specified in the type parameter.
    02802 This call returns either OCI_SUCCESS or OCI_INVALID_HANDLE.
    02803 All handles must be explicitly deallocated. OCI will not deallocate a child
    02804 handle if the parent is deallocated.
    02805 Parameters
    02806 hndlp (IN) - an opaque pointer to some storage.
    02807 type (IN) - specifies the type of storage to be allocated. The specific types
    02808 are:
    02809 OCI_HTYPE_ENV - an environment handle
    02810 OCI_HTYPE_ERROR - an error report handle
    02811 OCI_HTYPE_SVCCTX - a service context handle
    02812 OCI_HTYPE_STMT - a statement (application request) handle
    02813 OCI_HTYPE_BIND - a bind information handle
    02814 OCI_HTYPE_DEFINE - a column definition handle
    02815 OCI_HTYPE_DESCRIBE  - a select list description handle
    02816 OCI_HTYPE_SERVER - a server handle
    02817 OCI_HTYPE_SESSION - a user authentication handle
    02818 OCI_HTYPE_TRANS - a transaction handle
    02819 OCI_HTYPE_COMPLEXOBJECT - a complex object retrieval handle
    02820 OCI_HTYPE_SECURITY - a security handle
    02821 Related Functions
    02822 OCIHandleAlloc()
    02823
    02824
    02825
    02826
    02827 OCIInitialize()
    02828 Name
    02829 OCI Process Initialize
    02830 Purpose
    02831 Initializes the OCI process environment.
    02832 Syntax
    02833 sword OCIInitialize ( ub4           mode,
    02834                     CONST dvoid   *ctxp,
    02835                     CONST dvoid   *(*malocfp)
    02836                                   ( dvoid *ctxp,
    02837                                     size_t size ),
    02838                     CONST dvoid   *(*ralocfp)
    02839                                   ( dvoid *ctxp,
    02840                                     dvoid *memp,
    02841                                     size_t newsize ),
    02842                     CONST void    (*mfreefp)
    02843                                   ( dvoid *ctxp,
    02844                                     dvoid *memptr ));
    02845 Comments
    02846 This call initializes the OCI process environment.
    02847 OCIInitialize() must be invoked before any other OCI call.
    02848 Parameters
    02849 mode (IN) - specifies initialization of the mode. The valid modes are:
    02850 OCI_DEFAULT - default mode.
    02851 OCI_THREADED - threaded environment. In this mode, internal data
    02852 structures are protected from concurrent accesses by multiple threads.
    02853 OCI_OBJECT - will use navigational object interface.
    02854 ctxp (IN) - user defined context for the memory call back routines.
    02855 malocfp (IN) - user-defined memory allocation function. If mode is
    02856 OCI_THREADED, this memory allocation routine must be thread safe.
    02857 ctxp - context pointer for the user-defined memory allocation function.
    02858 size - size of memory to be allocated by the user-defined memory
    02859 allocation function
    02860 ralocfp (IN) - user-defined memory re-allocation function. If mode is
    02861 OCI_THREADED, this memory allocation routine must be thread safe.
    02862 ctxp - context pointer for the user-defined memory reallocation
    02863 function.
    02864 memp - pointer to memory block
    02865 newsize - new size of memory to be allocated
    02866 mfreefp (IN) - user-defined memory free function. If mode is
    02867 OCI_THREADED, this memory free routine must be thread safe.
    02868 ctxp - context pointer for the user-defined memory free function.
    02869 memptr - pointer to memory to be freed
    02870 Example
    02871 See the description of OCIStmtPrepare() on page 13-96 for an example showing
    02872 the use of OCIInitialize().
    02873 Related Functions
    02874
    02875 -------------------------------OCITerminate------------------------------------
    02876
    02877 OCITerminate()
    02878 Name
    02879 OCI process Terminate
    02880 Purpose
    02881 Do cleanup before process termination
    02882 Syntax
    02883 sword OCITerminate (ub4 mode);
    02884
    02885 Comments
    02886 This call performs  OCI related clean up before the OCI process terminates.
    02887 If the process is running in shared mode then the OCI process is disconnected
    02888 from the shared memory subsystem.
    02889
    02890 OCITerminate() should be the last OCI call in any process.
    02891
    02892 Parameters
    02893 mode (IN) - specifies different termination modes.
    02894
    02895 OCI_DEFAULT - default mode.
    02896
    02897 Example
    02898
    02899 Related Functions
    02900 OCIInitialize()
    02901
    02902 ---------------------- OCIIntervalAssign ---------------------------------
    02903 sword OCIIntervalAssign(dvoid *hndl, OCIError *err,
    02904                     CONST OCIInterval *inpinter, OCIInterval *outinter );
    02905
    02906   DESCRIPTION
    02907     Copies one interval to another to create a replica
    02908   PARAMETERS
    02909      hndl (IN) - Session/Env handle.
    02910     err (IN/OUT) - error handle. If there is an error, it is
    02911                 recorded in 'err' and this function returns OCI_ERROR.
    02912                 The error recorded in 'err' can be retrieved by calling
    02913                 OCIErrorGet().
    02914     (IN)  inpinter - Input Interval
    02915     (OUT) outinter - Output Interval
    02916   RETURNS
    02917      OCI_INVALID_HANDLE if 'err' is NULL.
    02918      OCI_SUCCESS otherwise
    02919
    02920  ---------------------- OCIIntervalCheck ------------------------------------
    02921 sword OCIIntervalCheck(dvoid *hndl, OCIError *err, CONST OCIInterval *interval,
    02922                          ub4 *valid );
    02923
    02924   DESCRIPTION
    02925     Checks the validity of an interval
    02926   PARAMETERS
    02927      hndl (IN) - Session/Env handle.
    02928     err (IN/OUT) - error handle. If there is an error, it is
    02929                 recorded in 'err' and this function returns OCI_ERROR.
    02930                 The error recorded in 'err' can be retrieved by calling
    02931                 OCIErrorGet().
    02932     (IN)  interval - Interval to be checked
    02933     (OUT) valid     - Zero if the interval is valid, else returns an Ored
    02934         combination of the following codes.
    02935
    02936    Macro name                   Bit number      Error
    02937    ----------                   ----------      -----
    02938    OCI_INTER_INVALID_DAY         0x1           Bad day
    02939    OCI_INTER_DAY_BELOW_VALID     0x2           Bad DAy Low/high bit (1=low)
    02940    OCI_INTER_INVALID_MONTH       0x4           Bad MOnth
    02941    OCI_INTER_MONTH_BELOW_VALID   0x8           Bad MOnth Low/high bit (1=low)
    02942    OCI_INTER_INVALID_YEAR        0x10          Bad YeaR
    02943    OCI_INTER_YEAR_BELOW_VALID    0x20          Bad YeaR Low/high bit (1=low)
    02944    OCI_INTER_INVALID_HOUR        0x40          Bad HouR
    02945    OCI_INTER_HOUR_BELOW_VALID    0x80          Bad HouR Low/high bit (1=low)
    02946    OCI_INTER_INVALID_MINUTE      0x100         Bad MiNute
    02947    OCI_INTER_MINUTE_BELOW_VALID  0x200         Bad MiNute Low/high bit(1=low)
    02948    OCI_INTER_INVALID_SECOND      0x400         Bad SeCond
    02949    OCI_INTER_SECOND_BELOW_VALID  0x800         bad second Low/high bit(1=low)
    02950    OCI_INTER_INVALID_FRACSEC     0x1000        Bad Fractional second
    02951    OCI_INTER_FRACSEC_BELOW_VALID 0x2000        Bad fractional second Low/High
    02952
    02953
    02954   RETURNS
    02955     OCI_SUCCESS if interval is okay
    02956     OCI_INVALID_HANDLE if 'err' is NULL.
    02957
    02958  ---------------------- OCIIntervalCompare -----------------------------------
    02959 sword OCIIntervalCompare(dvoid *hndl, OCIError *err, OCIInterval *inter1,
    02960                         OCIInterval *inter2, sword *result );
    02961
    02962   DESCRIPTION
    02963         Compares two intervals, returns 0 if equal, -1 if inter1 < inter2,
    02964         1 if inter1 > inter2
    02965   PARAMETERS
    02966      hndl (IN) - Session/Env handle.
    02967      err (IN/OUT) - error handle. If there is an error, it is
    02968                 recorded in 'err' and this function returns OCI_ERROR.
    02969                 The error recorded in 'err' can be retrieved by calling
    02970                 OCIErrorGet().
    02971      inter1  (IN)   - Interval to be compared
    02972      inter2  (IN)   - Interval to be compared
    02973      result  (OUT)  -   comparison result, 0 if equal, -1 if inter1 < inter2,
    02974                         1 if inter1 > inter2
    02975
    02976   RETURNS
    02977      OCI_SUCCESS on success
    02978      OCI_INVALID_HANDLE if 'err' is NULL.
    02979      OCI_ERROR if
    02980         the two input datetimes are not mutually comparable.
    02981
    02982 ---------------------- OCIIntervalDivide ------------------------------------
    02983 sword OCIIntervalDivide(dvoid *hndl, OCIError *err, OCIInterval *dividend,
    02984                 OCINumber *divisor, OCIInterval *result );
    02985
    02986   DESCRIPTION
    02987      Divides an interval by an Oracle Number to produce an interval
    02988   PARAMETERS
    02989         hndl (IN) - Session/Env handle.
    02990      err (IN/OUT) - error handle. If there is an error, it is
    02991                 recorded in 'err' and this function returns OCI_ERROR.
    02992                 The error recorded in 'err' can be retrieved by calling
    02993                 OCIErrorGet().
    02994      dividend  (IN)   - Interval to be divided
    02995      divisor   (IN)   - Oracle Number dividing `dividend'
    02996      result    (OUT)  - resulting interval (dividend / divisor)
    02997   RETURNS
    02998      OCI_SUCCESS on success
    02999      OCI_INVALID_HANDLE if 'err' is NULL.
    03000
    03001  ---------------------- OCIIntervalFromNumber --------------------
    03002 sword OCIIntervalFromNumber(dvoid *hndl, OCIError *err,
    03003                OCIInterval *inter, OCINumber *number);
    03004   DESCRIPTION
    03005     Converts an interval to an Oracle Number
    03006   PARAMETERS
    03007      hndl (IN) - Session/Env handle.
    03008     err (IN/OUT) - error handle. If there is an error, it is
    03009                 recorded in 'err' and this function returns OCI_ERROR.
    03010                 The error recorded in 'err' can be retrieved by calling
    03011                 OCIErrorGet().
    03012     (OUT)  interval - Interval to be converted
    03013     (IN) number - Oracle number result  (in years for YEARMONTH interval
    03014                      and in days for DAYSECOND)
    03015   RETURNS
    03016     OCI_SUCCESS on success
    03017     OCI_INVALID_HANDLE if 'err' is NULL.
    03018     OCI_ERROR on error.
    03019   NOTES
    03020     Fractional portions of the date (for instance, minutes and seconds if
    03021     the unit chosen is hours) will be included in the Oracle number produced.
    03022     Excess precision will be truncated.
    03023
    03024  ---------------------- OCIIntervalFromText ---------------------------------
    03025 sword OCIIntervalFromText( dvoid *hndl, OCIError *err, CONST OraText *inpstr,
    03026                 size_t str_len, OCIInterval *result );
    03027
    03028   DESCRIPTION
    03029     Given an interval string produce the interval represented by the string.
    03030     The type of the interval is the type of the 'result' descriptor.
    03031   PARAMETERS
    03032
    03033      hndl (IN) - Session/Env handle.
    03034      err (IN/OUT) - error handle. If there is an error, it is
    03035                 recorded in 'err' and this function returns OCI_ERROR.
    03036                 The error recorded in 'err' can be retrieved by calling
    03037                 OCIErrorGet().
    03038     (IN)  inpstr - Input string
    03039     (IN)  str_len - Length of input string
    03040     (OUT) result - Resultant interval
    03041   RETURNS
    03042     OCI_SUCCESS on success
    03043     OCI_INVALID_HANDLE if 'err' is NULL.
    03044     OCI_ERROR if
    03045         there are too many fields in the literal string
    03046         the year is out of range (-4713 to 9999)
    03047         if the month is out of range (1 to 12)
    03048         if the day of month is out of range (1 to 28...31)
    03049         if hour is not in range (0 to 23)
    03050         if hour is not in range (0 to 11)
    03051         if minute is not in range (0 to 59)
    03052         if seconds in minute not in range (0 to 59)
    03053         if seconds in day not in range (0 to 86399)
    03054         if the interval is invalid
    03055
    03056
    03057  ---------------------- OCIIntervalGetDaySecond --------------------
    03058
    03059   DESCRIPTION
    03060      Gets values of day second interval
    03061   PARAMETERS
    03062         hndl (IN) - Session/Env handle.
    03063         err (IN/OUT) - error handle. If there is an error, it is
    03064                 recorded in 'err' and this function returns OCI_ERROR.
    03065                 The error recorded in 'err' can be retrieved by calling
    03066                 OCIErrorGet().
    03067         day     (OUT) - number of days
    03068         hour    (OUT) - number of hours
    03069         min     (OUT) - number of mins
    03070         sec     (OUT) - number of secs
    03071         fsec    (OUT) - number of fractional seconds
    03072         result     (IN)  - resulting interval
    03073   RETURNS
    03074         OCI_SUCCESS on success
    03075         OCI_INVALID_HANDLE if 'err' is NULL.
    03076
    03077
    03078  ---------------------- OCIIntervalGetYearMonth --------------------
    03079
    03080   DESCRIPTION
    03081      Gets year month from an interval
    03082   PARAMETERS
    03083         hndl (IN) - Session/Env handle.
    03084         err (IN/OUT) - error handle. If there is an error, it is
    03085                 recorded in 'err' and this function returns OCI_ERROR.
    03086                 The error recorded in 'err' can be retrieved by calling
    03087                 OCIErrorGet().
    03088         year    (OUT)   - year value
    03089         month   (OUT)   - month value
    03090         result     (IN)  - resulting interval
    03091   RETURNS
    03092         OCI_SUCCESS on success
    03093         OCI_INVALID_HANDLE if 'err' is NULL.
    03094
    03095
    03096
    03097 -------------------------- OCIIntervalAdd ------------------------------
    03098 sword OCIIntervalAdd(dvoid *hndl, OCIError *err, OCIInterval *addend1,
    03099                         OCIInterval *addend2, OCIInterval *result );
    03100 NAME OCIIntervalAdd - Adds two intervals
    03101 PARAMETERS
    03102 hndl (IN) - Session/Env handle.
    03103 err (IN/OUT) - error handle. If there is an error, it is
    03104                 recorded in 'err' and this function returns OCI_ERROR.
    03105                 The error recorded in 'err' can be retrieved by calling
    03106                 OCIErrorGet().
    03107 addend1  (IN)   - Interval to be added
    03108 addend2  (IN)   - Interval to be added
    03109 result   (OUT)  - resulting interval (addend1 + addend2)
    03110 DESCRIPTION
    03111      Adds two intervals to produce a resulting interval
    03112 RETURNS
    03113      OCI_SUCCESS on success
    03114      OCI_ERROR if:
    03115         the two input intervals are not mutually comparable.
    03116         the resulting year would go above SB4MAXVAL
    03117         the resulting year would go below SB4MINVAL
    03118      OCI_INVALID_HANDLE if 'err' is NULL.
    03119 NOTES
    03120      The two input intervals must be mutually comparable
    03121
    03122  ---------------------- OCIIntervalSubtract -------------------------------
    03123 sword OCIIntervalSubtract(dvoid *hndl, OCIError *err, OCIInterval *minuend,
    03124                             OCIInterval *subtrahend, OCIInterval *result );
    03125 NAME - OCIIntervalSubtract - subtracts two intervals
    03126 PARAMETERS
    03127 hndl (IN) - Session/Env handle.
    03128 err (IN/OUT) - error handle. If there is an error, it is
    03129                 recorded in 'err' and this function returns OCI_ERROR.
    03130                 The error recorded in 'err' can be retrieved by calling
    03131                 OCIErrorGet().
    03132 minuend    (IN)   - interval to be subtracted from
    03133 subtrahend (IN)   - interval subtracted from minuend
    03134 result     (OUT)  - resulting interval (minuend - subtrahend)
    03135 DESCRIPTION
    03136      Subtracts two intervals and stores the result in an interval
    03137 RETURNS
    03138         OCI_SUCCESS on success
    03139         OCI_INVALID_HANDLE if 'err' is NULL.
    03140         OCI_ERROR if:
    03141            the two input intervals are not mutually comparable.
    03142            the resulting leading field would go below SB4MINVAL
    03143            the resulting leading field would go above SB4MAXVAL
    03144
    03145 ---------------------- OCIIntervalMultiply ---------------------------------
    03146 sword OCIIntervalMultiply(dvoid *hndl, OCIError *err, CONST OCIInterval *inter,
    03147                         OCINumber *nfactor, OCIInterval *result );
    03148
    03149   DESCRIPTION
    03150      Multiplies an interval by an Oracle Number to produce an interval
    03151   PARAMETERS
    03152         hndl (IN) - Session/Env handle.
    03153      err (IN/OUT) - error handle. If there is an error, it is
    03154                 recorded in 'err' and this function returns OCI_ERROR.
    03155                 The error recorded in 'err' can be retrieved by calling
    03156                 OCIErrorGet().
    03157      inter  (IN)   - Interval to be multiplied
    03158      nfactor  (IN)   - Oracle Number to be multiplied
    03159      result   (OUT)  - resulting interval (ifactor * nfactor)
    03160   RETURNS
    03161      OCI_SUCCESS on success
    03162      OCI_INVALID_HANDLE if 'err' is NULL.
    03163      OCI_ERROR if:
    03164         the resulting year would go above SB4MAXVAL
    03165         the resulting year would go below SB4MINVAL
    03166
    03167
    03168  ---------------------- OCIIntervalSetDaySecond --------------------
    03169
    03170   DESCRIPTION
    03171      Sets day second interval
    03172   PARAMETERS
    03173         hndl (IN) - Session/Env handle.
    03174         err (IN/OUT) - error handle. If there is an error, it is
    03175                 recorded in 'err' and this function returns OCI_ERROR.
    03176                 The error recorded in 'err' can be retrieved by calling
    03177                 OCIErrorGet().
    03178         day     (IN) - number of days
    03179         hour    (IN) - number of hours
    03180         min     (IN) - number of mins
    03181         sec     (IN) - number of secs
    03182         fsec    (IN) - number of fractional seconds
    03183         result     (OUT)  - resulting interval
    03184   RETURNS
    03185         OCI_SUCCESS on success
    03186         OCI_INVALID_HANDLE if 'err' is NULL.
    03187
    03188
    03189  ---------------------- OCIIntervalSetYearMonth --------------------
    03190
    03191   DESCRIPTION
    03192      Sets year month interval
    03193   PARAMETERS
    03194         hndl (IN) - Session/Env handle.
    03195         err (IN/OUT) - error handle. If there is an error, it is
    03196                 recorded in 'err' and this function returns OCI_ERROR.
    03197                 The error recorded in 'err' can be retrieved by calling
    03198                 OCIErrorGet().
    03199         year    (IN)   - year value
    03200         month   (IN)   - month value
    03201         result     (OUT)  - resulting interval
    03202   RETURNS
    03203         OCI_SUCCESS on success
    03204         OCI_INVALID_HANDLE if 'err' is NULL.
    03205
    03206
    03207 ----------------------- OCIIntervalToNumber ---------------------------------
    03208 sword OCIIntervalToNumber(dvoid *hndl, OCIError *err, CONST OCIInterval *inter,
    03209                           OCINumber *number);
    03210
    03211   DESCRIPTION
    03212     Converts an interval to an Oracle Number
    03213   PARAMETERS
    03214      hndl (IN) - Session/Env handle.
    03215     err (IN/OUT) - error handle. If there is an error, it is
    03216                 recorded in 'err' and this function returns OCI_ERROR.
    03217                 The error recorded in 'err' can be retrieved by calling
    03218                 OCIErrorGet().
    03219     (IN)  inter - Interval to be converted
    03220     (OUT) number - Oracle number result  (in years for YEARMONTH interval
    03221                      and in days for DAYSECOND)
    03222   RETURNS
    03223     OCI_INVALID_HANDLE if 'err' is NULL.
    03224     OCI_SUCCESS on success
    03225   NOTES
    03226     Fractional portions of the date (for instance, minutes and seconds if
    03227     the unit chosen is hours) will be included in the Oracle number produced.
    03228     Excess precision will be truncated.
    03229
    03230 ------------------------------- OCIIntervalToText -------------------------
    03231 sword OCIIntervalToText( dvoid *hndl, OCIError *err, CONST OCIInterval *inter,
    03232                         ub1 lfprec, ub1 fsprec, OraText *buffer,
    03233                         size_t buflen, size_t *resultlen );
    03234
    03235   DESCRIPTION
    03236     Given an interval, produces a string representing the interval.
    03237   PARAMETERS
    03238      hndl (IN) - Session/Env handle.
    03239     err (IN/OUT) - error handle. If there is an error, it is
    03240                 recorded in 'err' and this function returns OCI_ERROR.
    03241                 The error recorded in 'err' can be retrieved by calling
    03242                 OCIErrorGet().
    03243     (IN)  inter - Interval to be converted
    03244     (IN)  lfprec  - Leading field precision. Number of digits used to
    03245                 represent the leading field.
    03246     (IN)  fsprec  - Fractional second precision of the interval. Number of
    03247                 digits used to represent the fractional seconds.
    03248     (OUT) buffer - buffer to hold result
    03249     (IN)  buflen - length of above buffer
    03250     (OUT) resultlen - length of result placed into buffer
    03251
    03252   RETURNS
    03253     OCI_SUCCESS on success
    03254     OCI_INVALID_HANDLE if 'err' is NULL.
    03255     OCI_ERROR
    03256         if the buffer is not large enough to hold the result
    03257   NOTES
    03258     The interval literal will be output as `year' or `[year-]month' for
    03259     YEAR-MONTH intervals and as `seconds' or `minutes[:seconds]' or
    03260     `hours[:minutes[:seconds]]' or `days[ hours[:minutes[:seconds]]]' for
    03261     DAY-TIME intervals (where optional fields are surrounded by brackets).
    03262
    03263  ---------------------- OCIIntervalFromTZ --------------------
    03264 sword OCIIntervalFromTZ(dvoid *hndl, OCIError *err, CONST oratext *inpstring,
    03265                         size_t str_len, OCIInterval *result);
    03266
    03267   DESCRIPTION
    03268     Retuns an OCI_DTYPE_INTERVAL_DS OCIInterval with the region id (if
    03269     the region is specified in the input string) set and the current
    03270     absolute offset or an absolut offset with the region id set to 0.
    03271   PARAMETERS
    03272     hndl (IN) - Session/Env handle.
    03273     err (IN/OUT) - error handle. If there is an error, it is
    03274                 recorded in 'err' and this function returns OCI_ERROR.
    03275                 The error recorded in 'err' can be retrieved by calling
    03276                 OCIErrorGet().
    03277     inpstring (IN) - pointer to the input string
    03278     str_len (IN) - inpstring length
    03279     result - Output Interval
    03280   RETURNS
    03281      OCI_SUCCESS on success
    03282      OCI_INVALID_HANDLE if 'err' is NULL.
    03283      OCI_ERROR on error
    03284         Bad interval type
    03285         Timezone errors
    03286   NOTES
    03287      The input string must be of the form [+/-]TZH:TZM or 'TZR [TZD]'
    03288
    03289  ----------------------- OCIKerbAttrSet ---------------------
    03290 sword OCIKerbAttrSet(OCISession *trgthndlp, ub4 auth_mode,
    03291                      ub1 *ftgt_ticket, ub4 ftgt_ticket_len,
    03292                      ub1 *ftgt_sesskey, ub4 ftgt_sesskey_len,
    03293                      ub2 ftgt_keytype, ub4 ftgt_ticket_flags,
    03294                      sb4 ftgt_auth_time, sb4 ftgt_start_time,
    03295                      sb4 ftgt_end_time, sb4 ftgt_renew_time,
    03296                      text *ftgt_principal, ub4 ftgt_principal_len,
    03297                      text *ftgt_realm, ub4 ftgt_realm_len,
    03298                      OCIError *errhp);
    03299
    03300   DESCRIPTION
    03301     This call sets the attributes required for Kerberos authentication
    03302     on the user handle.
    03303
    03304   PARAMETERS
    03305     trgthndlp (IN) - The pointer to a user handle.
    03306     auth_mode (IN) - Indicates what type of Kerberos credentials should
    03307                     be set. Options are:
    03308
    03309                     OCI_KERBCRED_PROXY
    03310                                          - Set Kerberos credentials for use with
    03311                                            proxy authentication.
    03312                     OCI_KERBCRED_CLIENT_IDENTIFIER
    03313                                          - Set Kerberos credentials for use
    03314                                            with secure client identifier.
    03315
    03316     ftgt_ticket (IN) - Forwardable Ticket Granting Ticket (FTGT).
    03317     ftgt_ticket_len (IN) - Length of FTGT.
    03318     ftgt_sesskey(IN) - Session Key associated with FTGT.
    03319     ftgt_sesskey_len (IN) - Length of session key.
    03320     ftgt_keytype (IN) -  Type of encryption key used to encrypt FTGT.
    03321     ftgt_ticket_flags (IN) - Flags associated with  encryption of FTGT.
    03322     ftgt_auth_time (IN) - Authentication time compatible with that in FTGT.
    03323     ftgt_start_time (IN) - Start time compatible with that indicated in FTGT.
    03324     ftgt_end_time (IN) - End time compatible with that indicated in FTGT.
    03325     ftgt_renew_time (IN) - Renew time compatible with that indicated in FTGT.
    03326     ftgt_principal (IN) - Client principal name from FTGT.
    03327     ftgt_principal_len (IN) - Length of client principal name.
    03328     ftgt_realm (IN) - Client realm name from FTGT.
    03329     ftgt_realm_len (IN) - Client realm name length.
    03330     errhp (IN/OUT) - error handle. If there is an error, it is
    03331                 recorded in 'err' and this function returns OCI_ERROR.
    03332                 The error recorded in 'err' can be retrieved by calling
    03333                 OCIErrorGet().
    03334   RETURNS
    03335      OCI_SUCCESS on success
    03336      OCI_ERROR on error
    03337   NOTES
    03338
    03339 OCILdaToSvcCtx()
    03340 Name
    03341 OCI toggle version 7 Lda_Def to SerVice context handle
    03342 Purpose
    03343 Converts a V7 Lda_Def to a V8 service context handle.
    03344 Syntax
    03345 sword OCILdaToSvcCtx ( OCISvcCtx  **svchpp,
    03346                      OCIError   *errhp,
    03347                      Lda_Def    *ldap );
    03348 Comments
    03349 Converts a V7 Lda_Def to a V8 service context handle. The action of this call
    03350 can be reversed by passing the resulting service context handle to the
    03351 OCISvcCtxToLda() function.
    03352 Parameters
    03353 svchpp (IN/OUT) - the service context handle.
    03354 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03355 diagnostic information in the event of an error.
    03356 ldap (IN/OUT) - the V7 logon data area returned by OCISvcCtxToLda() from
    03357 this service context.
    03358 Related Functions
    03359 OCISvcCtxToLda()
    03360
    03361
    03362
    03363
    03364 OCILobAppend()
    03365
    03366 Name
    03367 OCI Lob APpend
    03368
    03369 Purpose
    03370 Appends a LOB value at the end of another LOB.
    03371
    03372 Syntax
    03373 sword OCILobAppend ( OCISvcCtx        *svchp,
    03374                    OCIError         *errhp,
    03375                    OCILobLocator    *dst_locp,
    03376                    OCILobLocator    *src_locp );
    03377 Comments
    03378 Appends a LOB value at the end of LOB. The data is
    03379 copied from the source to the destination at the end of the destination. The
    03380 source and the destination must already exist. The destination LOB is
    03381 extended to accommodate the newly written data.
    03382
    03383 It is an error to extend the destination LOB beyond the maximum length
    03384 allowed or to try to copy from a NULL LOB.
    03385
    03386 Parameters
    03387 svchp (IN) - the service context handle.
    03388 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03389 diagnostic information in the event of an error.
    03390 dst_locp (IN/OUT) - a locator uniquely referencing the destination LOB.
    03391 src_locp (IN/OUT) - a locator uniquely referencing the source LOB.
    03392
    03393 Related Functions
    03394 OCILobTrim()
    03395 OCIErrorGet()
    03396 OCILobWrite()
    03397 OCILobCopy()
    03398
    03399
    03400
    03401 OCILobAssign()
    03402
    03403 Name
    03404 OCI Lob ASsiGn
    03405
    03406 Purpose
    03407 Assigns one LOB/FILE locator to another.
    03408
    03409 Syntax
    03410 sword OCILobAssign ( OCIEnv                *envhp,
    03411                      OCIError              *errhp,
    03412                      CONST OCILobLocator   *src_locp,
    03413                      OCILobLocator         **dst_locpp );
    03414
    03415 Comments
    03416 Assign source locator to destination locator.  After the assignment, both
    03417 locators refer to the same LOB data.  For internal LOBs, the source locator's
    03418 LOB data gets copied to the destination locator's LOB data only when the
    03419 destination locator gets stored in the table.  Therefore, issuing a flush of
    03420 the object containing the destination locator will copy the LOB data. For
    03421 FILEs only the locator that refers to the OS file is copied to the table. The
    03422 OS file is not copied.
    03423 Note: The only difference between this and OCILobLocatorAssign is that this
    03424 takes an environment handle whereas OCILobLocatorAssign takes an OCI service
    03425 handle
    03426
    03427 Parameters
    03428 envhp (IN/OUT) - OCI environment handle initialized in object mode.
    03429 errhp (IN/OUT) - The OCI error handle. If there is an error, it is recorded
    03430 in errhp and this function returns OCI_ERROR. Diagnostic information can be
    03431 obtained by calling OCIErrorGet().
    03432 src_locp (IN) - LOB locator to copy from.
    03433 dst_locpp (IN/OUT) - LOB locator to copy to.  The caller must allocate space
    03434 for the OCILobLocator by calling OCIDescriptorAlloc().
    03435
    03436 See also
    03437 OCIErrorGet()
    03438 OCILobIsEqual()
    03439 OCILobLocatorIsInit()
    03440 OCILobLocatorAssign()
    03441
    03442
    03443 OCILobCharSetForm()
    03444
    03445 Name
    03446 OCI Lob Get Character Set Form
    03447
    03448 Purpose
    03449 Gets the LOB locator's character set fpr,, if any.
    03450
    03451 Syntax
    03452 sword OCILobCharSetForm ( OCIEnv                    *envhp,
    03453                           OCIError                  *errhp,
    03454                           CONST OCILobLocator       *locp,
    03455                           ub1                       *csfrm );
    03456
    03457 Comments
    03458 Returns the character set form of the input LOB locator in the csfrm output
    03459 parameter.
    03460
    03461 Parameters
    03462 envhp (IN/OUT) - OCI environment handle initialized in object mode.
    03463 errhp (IN/OUT) - error handle. The OCI error handle. If there is an error, it
    03464 is recorded in err and this function returns OCI_ERROR. Diagnostic
    03465 information can be obtained by calling OCIErrorGet().
    03466 locp (IN) - LOB locator for which to get the character set form.
    03467 csfrm(OUT) - character set form of the input LOB locator.  If the input
    03468 locator is for a BLOB or a BFILE, csfrm is set to 0 since there is no concept
    03469 of a character set for binary LOBs/FILEs.  The caller must allocate space for
    03470 the csfrm (ub1) and not write into the space.
    03471 See also
    03472 OCIErrorGet(), OCILobCharSetId(), OCILobLocatorIsInit
    03473
    03474
    03475
    03476 OCILobCharSetId()
    03477
    03478 Name
    03479 OCI Lob get Character Set IDentifier
    03480
    03481 Purpose
    03482 Gets the LOB locator's character set ID, if any.
    03483
    03484 Syntax
    03485 sword OCILobCharSetId ( OCIEnv                    *envhp,
    03486                         OCIError                  *errhp,
    03487                         CONST OCILobLocator       *locp,
    03488                         ub2                       *csid );
    03489
    03490 Comments
    03491 Returns the character set ID of the input LOB locator in the cid output
    03492 parameter.
    03493
    03494 Parameters
    03495 envhp (IN/OUT) - OCI environment handle initialized in object mode.
    03496 errhp (IN/OUT) - error handle. The OCI error handle. If there is an error, it
    03497 is recorded in err and this function returns OCI_ERROR. Diagnostic
    03498 information can be obtained by calling OCIErrorGet().
    03499 locp (IN) - LOB locator for which to get the character set ID.
    03500 csid (OUT) - character set ID of the input LOB locator.  If the input locator
    03501 is for a BLOB or a BFILE, csid is set to 0 since there is no concept of a
    03502 character set for binary LOBs/FILEs.  The caller must allocate space for the
    03503 character set id of type ub2 and not write into the space.
    03504
    03505 See also
    03506 OCIErrorGet(), OCILobCharSetForm(), OCILobLocatorIsInit()
    03507
    03508
    03509
    03510 OCILobCopy()
    03511
    03512 Name
    03513 OCI Lob Copy
    03514
    03515 Purpose
    03516 Copies a portion of a LOB value into another LOB value.
    03517
    03518 Syntax
    03519 sword OCILobCopy ( OCISvcCtx        *svchp,
    03520                    OCIError         *errhp,
    03521                    OCILobLocator    *dst_locp,
    03522                    OCILobLocator    *src_locp,
    03523                    ub4              amount,
    03524                    ub4              dst_offset,
    03525                    ub4              src_offset );
    03526
    03527 Comments
    03528 Copies a portion of a LOB value into another LOB as specified. The data
    03529 is copied from the source to the destination. The source (src_locp) and the
    03530 destination (dlopb) LOBs must already exist.
    03531 If the data already exists at the destination's start position, it is
    03532 overwritten with the source data. If the destination's start position is
    03533 beyond the end of the current data, a hole is created from the end of the data
    03534 to the beginning of the newly written data from the source. The destination
    03535 LOB is extended to accommodate the newly written data if it extends
    03536 beyond the current length of the destination LOB.
    03537 It is an error to extend the destination LOB beyond the maximum length
    03538 allowed or to try to copy from a NULL LOB.
    03539 Parameters
    03540 svchp (IN) - the service context handle.
    03541 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03542 diagnostic information in the event of an error.
    03543 dst_locp (IN/OUT) - a locator uniquely referencing the destination LOB.
    03544 src_locp (IN/OUT) - a locator uniquely referencing the source LOB.
    03545 amount (IN) - the number of character or bytes, as appropriate, to be copied.
    03546 dst_offset (IN) - this is the absolute offset for the destination LOB.
    03547 For character LOBs it is the number of characters from the beginning of the
    03548 LOB at which to begin writing. For binary LOBs it is the number of bytes from
    03549 the beginning of the lob from which to begin reading. The offset starts at 1.
    03550 src_offset (IN) - this is the absolute offset for the source LOB.
    03551 For character LOBs it is the number of characters from the beginning of the
    03552 LOB, for binary LOBs it is the number of bytes. Starts at 1.
    03553
    03554 See Also
    03555 OCIErrorGet(), OCILobAppend(), OCILobWrite(), OCILobTrim()
    03556
    03557 OCILobCreateTemporary()
    03558
    03559 Name
    03560 OCI Lob Create Temporary
    03561
    03562 Purpose
    03563 Create a Temporary Lob
    03564
    03565 Syntax
    03566 sword OCILobCreateTemporary(OCISvcCtx          *svchp,
    03567                             OCIError           *errhp,
    03568                             OCILobLocator      *locp,
    03569                             ub2                 csid,
    03570                             ub1                 csfrm,
    03571                             ub1                 lobtype,
    03572                             boolean             cache,
    03573                             OCIDuration         duration);
    03574
    03575
    03576 Comments
    03577 svchp (IN) - the service context handle.
    03578 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03579 diagnostic information in the event of an error.
    03580 locp (IN/OUT) - a locator which points to the temporary Lob
    03581 csid (IN) - the character set id
    03582 csfrm(IN) - the character set form
    03583 lobtype (IN) - the lob type - one of the three constants OCI_TEMP_BLOB,
    03584                OCI_TEMP_CLOB and OCI_TEMP_NCLOB
    03585 cache(IN)-  TRUE if the temporary LOB goes through the cache; FALSE, if not.
    03586 duration(IN)- duration of the temporary LOB; Can be a valid duration id or one
    03587               of the values: OCI_DURATION_SESSION, OCI_DURATION_CALL
    03588               Note: OCI_DURATION_TRANSACTION is NOT supported in 8.1
    03589 Related functions
    03590 OCILobFreeTemporary()
    03591 OCILobIsTemporary()
    03592
    03593 OCILobDisableBuffering()
    03594
    03595 Name
    03596 OCI Lob Disable Buffering
    03597
    03598 Purpose
    03599 Disable lob buffering for the input locator.
    03600
    03601
    03602 Syntax
    03603 sword OCILobDisableBuffering ( OCISvcCtx      *svchp,
    03604                                OCIError       *errhp,
    03605                                OCILobLocator  *locp);
    03606
    03607 Comments
    03608
    03609 Disable lob buffering for the input locator.  The next time data is
    03610 read/written from/to the lob through the input locator, the lob
    03611 buffering subsystem is *not* used.  Note that this call does *not*
    03612 implicitly flush the changes made in the buffering subsystem.  The
    03613 user must explicitly call OCILobFlushBuffer() to do this.
    03614
    03615 Parameters
    03616 svchp (IN) - the service context handle.
    03617 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03618 diagnostic information in the event of an error.
    03619 locp (IN/OUT) - a locator uniquely referencing the LOB.
    03620
    03621 Related Functions
    03622 OCILobEnableBuffering()
    03623 OCIErrorGet()
    03624 OCILobFlushBuffer()
    03625
    03626
    03627
    03628
    03629 OCILobEnableBuffering()
    03630
    03631 Name
    03632 OCI Lob Enable Buffering
    03633
    03634 Purpose
    03635 Enable lob buffering for the input locator.
    03636
    03637
    03638 Syntax
    03639 sword OCILobEnableBuffering ( OCISvcCtx      *svchp,
    03640                               OCIError       *errhp,
    03641                               OCILobLocator  *locp);
    03642
    03643 Comments
    03644
    03645 Enable lob buffering for the input locator.  The next time data is
    03646 read/written from/to the lob through the input locator, the lob
    03647 buffering subsystem is used.
    03648
    03649 Once lob buffering is enabled for a locator, if that locator is passed to
    03650 one of the following routines, an error is returned:
    03651         OCILobCopy, OCILobAppend, OCILobErase, OCILobGetLength, OCILobTrim
    03652
    03653 Parameters
    03654 svchp (IN) - the service context handle.
    03655 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03656 diagnostic information in the event of an error.
    03657 locp (IN/OUT) - a locator uniquely referencing the LOB.
    03658
    03659 Related Functions
    03660 OCILobDisableBuffering()
    03661 OCIErrorGet()
    03662 OCILobWrite()
    03663 OCILobRead()
    03664 OCILobFlushBuffer()
    03665
    03666
    03667
    03668
    03669 OCILobErase()
    03670
    03671 Name
    03672 OCI Lob ERase
    03673
    03674 Purpose
    03675 Erases a specified portion of the LOB data starting at a specified offset.
    03676
    03677 Syntax
    03678 sword OCILobErase ( OCISvcCtx       *svchp,
    03679                   OCIError        *errhp,
    03680                   OCILobLocator   *locp,
    03681                   ub4             *amount,
    03682                   ub4             offset );
    03683
    03684 Comments
    03685 Erases a specified portion of the LOB data starting at a specified offset.
    03686 The actual number of characters/bytes erased is returned. The actual number
    03687 of characters/bytes and the requested number of characters/bytes will differ
    03688 if the end of the LOB data is reached before erasing the requested number of
    03689 characters/bytes.
    03690 If a section of data from the middle of the LOB data is erased, a hole is
    03691 created. When data from that hole is read, 0's are returned. If the LOB is
    03692 NULL, this routine will indicate that 0 characters/bytes were erased.
    03693
    03694 Parameters
    03695 svchp (IN) - the service context handle.
    03696 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03697 diagnostic information in the event of an error.
    03698 locp (IN/OUT) - the LOB for which to erase a section of data.
    03699 amount (IN/OUT) - On IN, the number of characters/bytes to erase. On OUT,
    03700 the actual number of characters/bytes erased.
    03701 offset (IN) - absolute offset from the beginning of the LOB data from which
    03702 to start erasing data. Starts at 1.
    03703
    03704 See Also
    03705 OCIErrorGet(), OCILobRead(), OCILobWrite()
    03706
    03707 OCILobOpen()
    03708
    03709 Name
    03710 OCI Lob Open
    03711
    03712 Purpose
    03713 Opens an internal or external Lob.
    03714
    03715 Syntax
    03716 sword OCILobOpen( OCISvcCtx        *svchp,
    03717                   OCIError         *errhp,
    03718                   OCILobLocator    *locp,
    03719                   ub1               mode );
    03720
    03721 Comments
    03722 It is an error if the same lob is opened more than once in
    03723 the same transaction. Lobs are opened implicitly if they are
    03724 not opened before using them. A LOB has to be closed before
    03725 the transaction commits else the transaction is rolled back.
    03726 Open locators are closed if the transaction aborts. Multiple
    03727 users can open the same lob on different locators.
    03728 Parameters
    03729 svchp (IN) - the service context handle.
    03730 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03731 diagnostic information in the event of an error.
    03732 locp (IN/OUT) - locator points to the LOB to be opened
    03733 mode (IN) - mode in which to open the lob. The valid modes are
    03734 read-only - OCI_FILE_READONLY, read-write - OCI_FILE_READWRITE
    03735
    03736 OCILobClose()
    03737
    03738 Name
    03739 OCI Lob Close
    03740
    03741 Purpose
    03742 Closes an open internal or external Lob.
    03743
    03744 Syntax
    03745 sword OCILobClose( OCISvcCtx        *svchp,
    03746                    OCIError         *errhp,
    03747                    OCILobLocator    *locp );
    03748
    03749
    03750 Comments
    03751 It is an error if the lob is not open at this time. All LOBs
    03752 that have been opened in a transaction have to be closed
    03753 before the transaction commits, else the transaction gets
    03754 rolled back.
    03755
    03756 Parameters
    03757 svchp (IN) - the service context handle.
    03758 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03759 diagnostic information in the event of an error.
    03760 locp  (IN)  - A locator that was opened using OCILobOpen()
    03761
    03762
    03763 OCILobFileClose()
    03764
    03765 Name
    03766 OCI Lob File CLoSe
    03767
    03768 Purpose
    03769 Closes a previously opened FILE.
    03770
    03771 Syntax
    03772 sword OCILobFileClose ( OCISvcCtx            *svchp,
    03773                         OCIError             *errhp,
    03774                         OCILobLocator        *filep );
    03775
    03776 Comments
    03777 Closes a previously opened FILE. It is an error if this function is called for
    03778 an internal LOB. No error is returned if the FILE exists but is not opened.
    03779 Parameters
    03780 svchp (IN) - the service context handle.
    03781 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03782 diagnostic information in the event of an error.
    03783 filep (IN/OUT) - a pointer to a FILE locator to be closed.
    03784
    03785 See Also
    03786 OCIErrorGet(), OCILobFileOpen(), OCILobFileCloseAll(), OCILobFileIsOpen(),
    03787 OCILobFileExists(), CREATE DIRECTORY DDL
    03788
    03789
    03790
    03791
    03792 OCILobFileCloseAll()
    03793
    03794 Name
    03795 OCI LOB FILE Close All
    03796
    03797 Purpose
    03798 Closes all open FILEs on a given service context.
    03799
    03800 Syntax
    03801 sword OCILobFileCLoseAll ( OCISvcCtx *svchp,
    03802                            OCIError  *errhp );
    03803
    03804 Comments
    03805 Closes all open FILEs on a given service context.
    03806
    03807 Parameters
    03808 svchp (IN) - the service context handle.
    03809 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03810 diagnostic information in the event of an error.
    03811
    03812 See also
    03813 OCILobFileClose(),
    03814 OCIErrorGet(), OCILobFileOpen(), OCILobFileIsOpen(),
    03815 OCILobFileExists(), CREATE DIRECTORY DDL
    03816
    03817
    03818
    03819
    03820 OCILobFileExists()
    03821
    03822 Name
    03823 OCI LOB FILE exists
    03824
    03825 Purpose
    03826 Tests to see if the FILE exists on the server
    03827
    03828 Syntax
    03829 sword OCILobFileExists ( OCISvcCtx     *svchp,
    03830                          OCIError      *errhp,
    03831                          OCILobLocator *filep,
    03832                          boolean       *flag );
    03833
    03834 Comments
    03835 Checks to see if a FILE exists for on the server.
    03836
    03837 Parameters
    03838 svchp (IN) - the OCI service context handle.
    03839 errhp (IN/OUT) - error handle. The OCI error handle. If there is an error,
    03840 it is recorded in err and this function returns OCI_ERROR. Diagnostic
    03841 information can be obtained by calling OCIErrorGet().
    03842 filep (IN) - pointer to the FILE locator that refers to the file.
    03843 flag (OUT) - returns TRUE if the FILE exists; FALSE if it does not.
    03844
    03845 See also
    03846 OCIErrorGet, CREATE DIRECTORY (DDL)
    03847
    03848
    03849
    03850
    03851 OCILobFileGetName()
    03852
    03853 Name
    03854 OCI LOB FILE Get file Name
    03855
    03856 Purpose
    03857 Gets the FILE locator's directory alias and file name.
    03858
    03859 Syntax
    03860 sword OCILobFileGetName ( OCIEnv                   *envhp,
    03861                           OCIError                 *errhp,
    03862                           CONST OCILobLocator      *filep,
    03863                           OraText                     *dir_alias,
    03864                           ub2                      *d_length,
    03865                           OraText                     *filename,
    03866                           ub2                      *f_length );
    03867
    03868 Comments
    03869 Returns the directory alias and file name associated with this file locator.
    03870
    03871 Parameters
    03872 envhp (IN/OUT) - OCI environment handle initialized in object mode.
    03873 errhp (IN/OUT) -The OCI error handle. If there is an error, it is recorded in
    03874 errhp and this function returns OCI_ERROR. Diagnostic information can be
    03875 obtained by calling OCIErrorGet().
    03876 filep (IN) - FILE locator for which to get the directory alias and file name.
    03877 dir_alias (OUT) - buffer into which the directory alias name is placed. The
    03878 caller must allocate enough space for the directory alias name and must not
    03879 write into the space.
    03880 d_length (IN/OUT)
    03881         - IN: length of the input dir_alias string;
    03882         - OUT: length of the returned dir_alias string.
    03883 filename (OUT) - buffer into which the file name is placed. The caller must
    03884 allocate enough space for the file name and must not write into the space.
    03885 f_length (IN/OUT)
    03886         - IN: length of the input filename string;
    03887          - OUT: lenght of the returned filename string.
    03888
    03889 See also
    03890 OCILobFileSetName(), OCIErrorGet()
    03891
    03892
    03893
    03894
    03895 OCILobFileIsOpen()
    03896
    03897 Name
    03898 OCI LOB FILE Is Open?
    03899
    03900 Purpose
    03901 Tests to see if the FILE is open
    03902
    03903 Syntax
    03904 sword OCILobFileIsOpen ( OCISvcCtx *svchp,
    03905                          OCIError  *errhp,
    03906                          OCILobLocator *filep,
    03907                          boolean       *flag );
    03908
    03909 Comments
    03910 Checks to see if the FILE on the server is open for a given LobLocator.
    03911
    03912 Parameters
    03913 svchp (IN) - the OCI service context handle.
    03914 errhp (IN/OUT) - error handle. The OCI error handle. If there is an error, it
    03915 is recorded in err and this function returns OCI_ERROR. Diagnostic
    03916 information can be obtained by calling OCIErrorGet().
    03917 filep (IN) - pointer to the FILE locator being examined. If the input file
    03918 locator was never passed to OCILobFileOpen(), the file is considered not to
    03919 be opened by this locator. However, a different locator may have opened the
    03920 file. More than one file opens can be performed on the same file using
    03921 different locators.
    03922 flag (OUT) - returns TRUE if the FILE is opened using this locator; FALSE if
    03923 it is not.
    03924
    03925 See also
    03926 OCIErrorGet, OCILobFileOpen, OCILobFileClose, OCILobFileCloseAll, CREATE
    03927 DIRECTORY SQL command
    03928
    03929
    03930 OCILobFileOpen()
    03931
    03932 Name
    03933 OCI LOB FILE open
    03934
    03935 Purpose
    03936 Opens a FILE for read-only access
    03937
    03938 Syntax
    03939 sword OCILobFileOpen ( OCISvcCtx            *svchp,
    03940                      OCIError             *errhp,
    03941                      OCILobLocator        *filep,
    03942                      ub1                  mode );
    03943
    03944 Comments
    03945 Opens a FILE. The FILE can be opened for read-only access only. FILEs may not
    03946 be written to throough ORACLE.
    03947
    03948 Parameters
    03949 svchp (IN) - the service context handle.
    03950 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    03951 diagnostic information in the event of an error.
    03952 filep (IN/OUT) - the FILE to open. Error if the locator does not refer to a
    03953 FILE.
    03954 mode (IN) - mode in which to open the file. The only valid mode is
    03955 read-only - OCI_FILE_READONLY.
    03956
    03957 See Also
    03958 OCILobFileClose, OCIErrorGet, OCILobFileCloseAll, OCILobFileIsOpen,
    03959 OCILobFileSetName, CREATE DIRECTORY
    03960
    03961
    03962
    03963
    03964 OCILobFileSetName()
    03965
    03966 Name
    03967 OCI Lob File Set NaMe
    03968
    03969 Purpose
    03970 Sets directory alias and file name in the FILE locator.
    03971
    03972 Syntax
    03973 sword OCILobFileSetName ( OCIEnv             *envhp,
    03974                           OCIError           *errhp,
    03975                           OCILobLocator      **filepp,
    03976                           OraText               *dir_alias,
    03977                           ub2                d_length,
    03978                           OraText               *filename,
    03979                           ub2                f_length );
    03980 Comments
    03981 Sets the directory alias and file name in the LOB file locator.
    03982 Parameters
    03983 envhp (IN/OUT) - OCI environment handle initialized in object mode.
    03984 errhp (IN/OUT) - The OCI error handle. If there is an error, it is recorded
    03985 in errhp and this function returns OCI_ERROR. Diagnostic information can be
    03986 obtained by calling OCIErrorGet().
    03987 filepp (IN/OUT) - FILE locator for which to set the directory alias name.
    03988 The caller must have already allocated space for the locator by calling
    03989 OCIDescriptorAlloc().
    03990 dir_alias (IN) - buffer that contains the directory alias name to set in the
    03991 locator.
    03992 d_length (IN) - length of the input dir_alias parameter.
    03993 filename (IN) - buffer that contains the file name is placed.
    03994 f_length (IN) - length of the input filename parameter.
    03995 See also
    03996 OCILobFileGetName, OCIErrorGet, CREATE DIRECTORY
    03997
    03998
    03999
    04000
    04001 OCILobFlushBuffer()
    04002
    04003 Name
    04004 OCI Lob Flush all Buffers for this lob.
    04005
    04006 Purpose
    04007 Flush/write all buffers for this lob to the server.
    04008
    04009
    04010 Syntax
    04011 sword OCILobFlushBuffer ( OCISvcCtx       *svchp,
    04012                           OCIError        *errhp,
    04013                           OCILobLocator   *locp,
    04014                           ub4              flag);
    04015
    04016 Comments
    04017
    04018 Flushes to the server, changes made to the buffering subsystem that
    04019 are associated with the lob referenced by the input locator.  This
    04020 routine will actually write the data in the buffer to the lob in
    04021 the database.  Lob buffering must have already been enabled for the
    04022 input lob locator.
    04023
    04024 This routine, by default, does not free the buffer resources for
    04025 reallocation to another buffered LOB operation. However, if you
    04026 want to free the buffer explicitly, you can set the flag parameter
    04027 to OCI_LOB_BUFFER_FREE.
    04028
    04029 Parameters
    04030 svchp (IN/OUT) - the service context handle.
    04031 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04032 diagnostic information in the event of an error.
    04033 locp (IN/OUT) - a locator uniquely referencing the LOB.
    04034 flag    (IN)     - to indicate if the buffer resources need to be freed
    04035                    after a flush. Default value is OCI_LOB_BUFFER_NOFREE.
    04036                    Set it to OCI_LOB_BUFFER_FREE if you want the buffer
    04037                    resources to be freed.
    04038 Related Functions
    04039 OCILobEnableBuffering()
    04040 OCILobDisableBuffering()
    04041 OCIErrorGet()
    04042 OCILobWrite()
    04043 OCILobRead()
    04044
    04045
    04046 OCILobFreeTemporary()
    04047
    04048 Name
    04049 OCI Lob Free Temporary
    04050
    04051 Purpose
    04052 Free a temporary LOB
    04053
    04054 Syntax
    04055 sword OCILobFreeTemporary(OCISvcCtx          *svchp,
    04056                           OCIError           *errhp,
    04057                           OCILobLocator      *locp);
    04058
    04059 Comments
    04060   Frees the contents of the temporary Lob this locator is pointing to. Note
    04061   that the locator itself is not freed until a OCIDescriptorFree is done.
    04062
    04063 Parameters
    04064 svchp (IN/OUT) - the service context handle.
    04065 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04066 diagnostic information in the event of an error.
    04067 locp (IN/OUT) - a locator uniquely referencing the LOB
    04068
    04069 Related functions
    04070 OCILobCreateTemporary()
    04071 OCILobIsTemporary()
    04072
    04073
    04074 Name
    04075 OCI Lob/File Get Chunk Size
    04076
    04077 Purpose
    04078 When creating the table, the user can specify the chunking factor, which can
    04079 be a multiple of Oracle blocks. This corresponds to the chunk size used by the
    04080 LOB data layer when accessing/modifying the LOB value. Part of the chunk is
    04081 used to store system-related information and the rest stores the LOB value.
    04082 This function returns the amount of space used in the LOB chunk to store
    04083 the LOB value.
    04084
    04085 Syntax
    04086 sword OCILobGetChunkSize ( OCISvcCtx      *svchp,
    04087                            OCIError       *errhp,
    04088                            OCILobLocator  *locp,
    04089                            ub4            *chunksizep );
    04090
    04091 Comments
    04092  Performance will be improved if the user issues read/write
    04093 requests using a multiple of this chunk size. For writes, there is an added
    04094 benefit since LOB chunks are versioned and, if all writes are done on chunk
    04095 basis, no extra/excess versioning is done nor duplicated. Users could batch
    04096 up the write until they have enough for a chunk instead of issuing several
    04097 write calls for the same chunk.
    04098
    04099 Parameters
    04100 svchp (IN) - the service context handle.
    04101 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04102 diagnostic information in the event of an error.
    04103 locp (IN/OUT) - a LOB locator that uniquely references the LOB. For internal
    04104 LOBs, this locator must be a locator that was obtained from the server
    04105 specified by svchp. For FILEs, this locator can be initialized by a Select or
    04106 OCILobFileSetName.
    04107 chunksizep (OUT) - On output, it is the length of the LOB if not NULL - for
    04108 character LOBs it is the number of characters, for binary LOBs it is the
    04109 number of bytes in the LOB.
    04110
    04111 Related Functions
    04112
    04113 OCILobGetLength()
    04114
    04115 Name
    04116 OCI Lob/File Length
    04117
    04118 Purpose
    04119 Gets the length of a LOB/FILE.
    04120
    04121 Syntax
    04122 sword OCILobGetLength ( OCISvcCtx      *svchp,
    04123                         OCIError       *errhp,
    04124                         OCILobLocator  *locp,
    04125                         ub4            *lenp );
    04126
    04127 Comments
    04128 Gets the length of a LOB/FILE. If the LOB/FILE is NULL, the length is
    04129 undefined.
    04130
    04131 Parameters
    04132 svchp (IN) - the service context handle.
    04133 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04134 diagnostic information in the event of an error.
    04135 locp (IN/OUT) - a LOB locator that uniquely references the LOB. For internal
    04136 LOBs, this locator must be a locator that was obtained from the server
    04137 specified by svchp. For FILEs, this locator can be initialized by a Select or
    04138 OCILobFileSetName.
    04139 lenp (OUT) - On output, it is the length of the LOB if not NULL - for
    04140 character LOBs it is the number of characters, for binary LOBs it is the
    04141 number of bytes in the LOB.
    04142
    04143 Related Functions
    04144 OCIErrorGet, OCIFileSetName
    04145
    04146
    04147
    04148 OCILobIsEqual()
    04149
    04150 Name
    04151
    04152 OCI Lob Is Equal
    04153
    04154 Purpose
    04155 Compares two LOB locators for equality.
    04156
    04157 Syntax
    04158 sword OCILobIsEqual ( OCIEnv                  *envhp,
    04159                       CONST OCILobLocator     *x,
    04160                       CONST OCILobLocator     *y,
    04161                       boolean                 *is_equal );
    04162
    04163 Comments
    04164 Compares the given LOB locators for equality.  Two LOB locators are equal if
    04165 and only if they both refer to the same LOB data.
    04166 Two NULL locators are considered not equal by this function.
    04167 Parameters
    04168 envhp (IN) - the OCI environment handle.
    04169 x (IN) - LOB locator to compare.
    04170 y (IN) - LOB locator to compare.
    04171 is_equal (OUT) - TRUE, if the LOB locators are equal; FALSE if they are not.
    04172
    04173 See also
    04174 OCILobAssign, OCILobLocatorIsInit
    04175 OCILobLocatorAssign,
    04176 OCILobIsOpen()
    04177
    04178 Name
    04179
    04180 OCI Lob Is Open
    04181 sword OCILobIsOpen(svchp, errhp, locp, flag)
    04182 OCISvcCtx     *svchp;
    04183 OCIError      *errhp;
    04184 OCILobLocator *locp;
    04185 boolean       *flag;
    04186
    04187 Comments
    04188    Checks if the LOB locator was opened before. flag is set to TRUE
    04189    if opened; FALSE otherwise
    04190
    04191
    04192 Parameters
    04193 svchp (IN) - the service context handle.
    04194 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04195 diagnostic information in the event of an error.
    04196 locp (IN) - the locator to test for temporary LOB
    04197 flag(OUT) - TRUE, if the LOB locator points to is open
    04198                     FALSE, if not.
    04199
    04200 OCILobIsTemporary()
    04201
    04202 Name
    04203
    04204 OCI Lob Is Temporary
    04205
    04206 Purpose
    04207   Tests if this locator points to a temporary LOB
    04208
    04209 Syntax
    04210 sword OCILobIsTemporary(OCIEnv            *envhp,
    04211                         OCIError          *errhp,
    04212                         OCILobLocator     *locp,
    04213                         boolean           *is_temporary);
    04214
    04215 Comments
    04216 Tests the locator to determine if it points to a temporary LOB.
    04217 If so, is_temporary is set to TRUE. If not, is_temporary is set
    04218 to FALSE.
    04219
    04220 Parameters
    04221 envhp (IN) - the environment handle.
    04222 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04223 diagnostic information in the event of an error.
    04224 locp (IN) - the locator to test for temporary LOB
    04225 is_temporary(OUT) - TRUE, if the LOB locator points to a temporary LOB;
    04226                     FALSE, if not.
    04227
    04228 See Also
    04229 OCILobCreateTemporary, OCILobFreeTemporary
    04230
    04231
    04232 OCILobLoadFromFile()
    04233
    04234 Name
    04235 OCI Lob Load From File
    04236
    04237 Purpose
    04238 Load/copy all or a portion of the file into an internal LOB.
    04239
    04240 Syntax
    04241 sword OCILobLoadFromFile ( OCISvcCtx        *svchp,
    04242                            OCIError         *errhp,
    04243                            OCILobLocator    *dst_locp,
    04244                            OCILobLocator    *src_filep,
    04245                            ub4              amount,
    04246                            ub4              dst_offset,
    04247                            ub4              src_offset );
    04248
    04249 Comments
    04250 Loads/copies a portion or all of a file value into an internal LOB as
    04251 specified.  The data is copied from the source file to the destination
    04252 internal LOB (BLOB/CLOB).  No character set conversions are performed
    04253 when copying the bfile data to a clob/nclob.  The bfile data must already
    04254 be in the same character set as the clob/nclob in the database.  No
    04255 error checking is performed to verify this.
    04256 The source (src_filep) and the destination (dst_locp) LOBs must already exist.
    04257 If the data already exists at the destination's start position, it is
    04258 overwritten with the source data. If the destination's start position is
    04259 beyond the end of the current data, a hole is created from the end of the data
    04260 to the beginning of the newly written data from the source. The destination
    04261 LOB is extended to accommodate the newly written data if it extends
    04262 beyond the current length of the destination LOB.
    04263 It is an error to extend the destination LOB beyond the maximum length
    04264 allowed or to try to copy from a NULL LOB.
    04265 Parameters
    04266 svchp (IN) - the service context handle.
    04267 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04268 diagnostic information in the event of an error.
    04269 dst_locp (IN/OUT) - a locator uniquely referencing the destination internal
    04270 LOB which may be of type blob, clob, or nclob.
    04271 src_filep (IN/OUT) - a locator uniquely referencing the source BFILE.
    04272 amount (IN) - the number of bytes to be copied.
    04273 dst_offset (IN) - this is the absolute offset for the destination LOB.
    04274 For character LOBs it is the number of characters from the beginning of the
    04275 LOB at which to begin writing. For binary LOBs it is the number of bytes from
    04276 the beginning of the lob from which to begin reading. The offset starts at 1.
    04277 src_offset (IN) - this is the absolute offset for the source BFILE.  It is
    04278 the number of bytes from the beginning of the LOB.  The offset starts at 1.
    04279
    04280 See Also
    04281 OCIErrorGet(), OCILobAppend(), OCILobWrite(), OCILobTrim(), OCILobCopy()
    04282
    04283 OCILobLocatorAssign()
    04284
    04285 Name
    04286 OCI Lob LOCATOR ASsiGn
    04287
    04288 Purpose
    04289 Assigns one LOB/FILE locator to another.
    04290
    04291 Syntax
    04292 sword OCILobLocatorAssign ( OCISvcCtx             *svchp,
    04293                             OCIError              *errhp,
    04294                             CONST OCILobLocator   *src_locp,
    04295                             OCILobLocator         **dst_locpp );
    04296
    04297 Comments
    04298 Assign source locator to destination locator.  After the assignment, both
    04299 locators refer to the same LOB data.  For internal LOBs, the source locator's
    04300 LOB data gets copied to the destination locator's LOB data only when the
    04301 destination locator gets stored in the table.  Therefore, issuing a flush of
    04302 the object containing the destination locator will copy the LOB data. For
    04303 FILEs only the locator that refers to the OS file is copied to the table. The
    04304 OS file is not copied.
    04305 Note : the only difference between this and OCILobAssign is that this takes
    04306 a OCI service handle pointer instead of a OCI environment handle pointer
    04307
    04308 Parameters
    04309 svchp (IN/OUT) - OCI service handle initialized in object mode.
    04310 errhp (IN/OUT) - The OCI error handle. If there is an error, it is recorded
    04311 in errhp and this function returns OCI_ERROR. Diagnostic information can be
    04312 obtained by calling OCIErrorGet().
    04313 src_locp (IN) - LOB locator to copy from.
    04314 dst_locpp (IN/OUT) - LOB locator to copy to.  The caller must allocate space
    04315 for the OCILobLocator by calling OCIDescriptorAlloc().
    04316
    04317 See also
    04318 OCIErrorGet()
    04319 OCILobIsEqual()
    04320 OCILobLocatorIsInit()
    04321 OCILobAssign()
    04322
    04323
    04324
    04325
    04326 OCILobLocatorIsInit()
    04327
    04328 Name
    04329 OCI LOB locator is initialized?
    04330
    04331 Purpose
    04332 Tests to see if a given LOB locator is initialized.
    04333
    04334 Syntax
    04335 sword OCILobLocatorIsInit ( OCIEnv   *envhp,
    04336                             OCIError *errhp,
    04337                             CONST OCILobLocator *locp,
    04338                             boolean *is_initialized );
    04339
    04340 Comments
    04341 Tests to see if a given LOB locator is initialized.
    04342
    04343 Parameters
    04344 envhp (IN/OUT) - OCI environment handle initialized in object mode.
    04345 errhp (IN/OUT) - error handle. The OCI error handle. If there is an error, it
    04346 is recorded in err and this function returns OCI_ERROR. Diagnostic
    04347 information can be obtained by calling OCIErrorGet().
    04348 locp (IN) - the LOB locator being tested
    04349 is_initialized (OUT) - returns TRUE if the given LOB locator is initialized;
    04350 FALSE if it is not.
    04351
    04352 See also
    04353 OCIErrorGet, OCILobIsEqual
    04354
    04355
    04356
    04357
    04358 OCILobRead()
    04359
    04360 Name
    04361 OCI Lob/File ReaD
    04362
    04363 Purpose
    04364 Reads a portion of a LOB/FILE as specified by the call into a buffer.
    04365
    04366 Syntax
    04367 sword OCILobRead ( OCISvcCtx       *svchp,
    04368                    OCIError        *errhp,
    04369                    OCILobLocator   *locp,
    04370                    ub4             offset,
    04371                    ub4             *amtp,
    04372                    dvoid           *bufp,
    04373                    ub4             bufl,
    04374                    dvoid           *ctxp,
    04375                    OCICallbackLobRead cbfp,
    04376                    ub2             csid,
    04377                    ub1             csfrm );
    04378
    04379 Comments
    04380 Reads a portion of a LOB/FILE as specified by the call into a buffer. Data
    04381 read from a hole is returned as 0s. It is an error to try to read from a NULL
    04382 LOB/FILE. The OS FILE must already exist on the server and must have been
    04383 opened using the input locator. Oracle must hav epermission to read the OS
    04384 file and user must have read permission on the directory object.
    04385
    04386 Parameters
    04387 svchp (IN/OUT) - the service context handle.
    04388 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04389 diagnostic information in the event of an error.
    04390 locp (IN/OUT) - a LOB locator that uniquely references a LOB.
    04391 offset (IN) - On input, it is the absolute offset, for character LOBs in the
    04392 number of characters from the beginning of the LOB, for binary LOBs it is the
    04393 number of bytes. Starts from 1.
    04394 amtp (IN/OUT) - On input, the number of character or bytes to be read. On
    04395 output, the actual number of bytes or characters read.
    04396 If the amount of bytes to be read is larger than the buffer length it is
    04397 assumed that the LOB is being read in a streamed mode. On input if this value
    04398 is 0, then the data shall be read in streamed mode from the LOB until the end
    04399 of LOB. If the data is read in pieces, *amtp always contains the length of
    04400 the last piece read.  If a callback function is defined, then this callback
    04401 function will be invoked each time bufl bytes are read off the pipe. Each
    04402 piece will be written into bufp.
    04403 If the callback function is not defined, then OCI_NEED_DATA error code will
    04404 be returned. The application must invoke the LOB read over and over again to
    04405 read more pieces of the LOB until the OCI_NEED_DATA error code is not
    04406 returned. The buffer pointer and the length can be different in each call
    04407 if the pieces are being read into different sizes and location.
    04408 bufp (IN) - the pointer to a buffer into which the piece will be read. The
    04409 length of the allocated memory is assumed to be bufl.
    04410 bufl (IN) - the length of the buffer in octets.
    04411 ctxp (IN) - the context for the call back function. Can be NULL.
    04412 cbfp (IN) - a callback that may be registered to be called for each piece. If
    04413 this is NULL, then OCI_NEED_DATA will be returned for each piece.
    04414 The callback function must return OCI_CONTINUE for the read to continue.
    04415 If any other error code is returned, the LOB read is aborted.
    04416   ctxp (IN) - the context for the call back function. Can be NULL.
    04417   bufp (IN) - a buffer pointer for the piece.
    04418   len (IN) - the length of length of current piece in bufp.
    04419   piece (IN) - which piece - OCI_FIRST_PIECE, OCI_NEXT_PIECE or
    04420   OCI_LAST_PIECE.
    04421 csid - the character set ID of the buffer data
    04422 csfrm - the character set form of the buffer data
    04423
    04424 Related Functions
    04425 OCIErrorGet, OCILobWrite, OCILobFileOpen, OCILobFileSetName, CREATE DIRECTORY
    04426
    04427
    04428
    04429
    04430 OCILobTrim()
    04431
    04432 Name
    04433
    04434 OCI Lob  Trim
    04435
    04436 Purpose
    04437 Trims the lob value to a shorter length
    04438
    04439 Syntax
    04440 sword OCILobTrim ( OCISvcCtx       *svchp,
    04441                  OCIError        *errhp,
    04442                  OCILobLocator   *locp,
    04443                  ub4             newlen );
    04444
    04445 Comments
    04446 Truncates LOB data to a specified shorter length.
    04447
    04448 Parameters
    04449 svchp (IN) - the service context handle.
    04450 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04451 diagnostic information in the event of an error.
    04452 locp (IN/OUT) - a LOB locator that uniquely references the LOB. This locator
    04453 must be a locator that was obtained from the server specified by svchp.
    04454 newlen (IN) - the new length of the LOB data, which must be less than or equal
    04455 to the current length.
    04456
    04457 Related Functions
    04458 OCIErrorGet, OCILobWrite, OCiLobErase, OCILobAppend, OCILobCopy
    04459
    04460
    04461
    04462
    04463
    04464 OCILobWrite()
    04465
    04466 Name
    04467 OCI Lob Write
    04468
    04469 Purpose
    04470 Writes a buffer into a LOB
    04471
    04472 Syntax
    04473 sword OCILobWrite ( OCISvcCtx       *svchp,
    04474                     OCIError        *errhp,
    04475                     OCILobLocator   *locp,
    04476                     ub4             offset,
    04477                     ub4             *amtp,
    04478                     dvoid           *bufp,
    04479                     ub4             buflen,
    04480                     ub1             piece,
    04481                     dvoid           *ctxp,
    04482                     OCICallbackLobWrite   (cbfp)
    04483                                     (
    04484                                     dvoid    *ctxp,
    04485                                     dvoid    *bufp,
    04486                                     ub4      *lenp,
    04487                                     ub1      *piecep )
    04488                     ub2             csid
    04489                     ub1             csfrm );
    04490
    04491
    04492 Comments
    04493 Writes a buffer into a LOB as specified. If LOB data already exists
    04494 it is overwritten with the data stored in the buffer.
    04495 The buffer can be written to the LOB in a single piece with this call, or
    04496 it can be provided piecewise using callbacks or a standard polling method.
    04497 If this value of the piece parameter is OCI_FIRST_PIECE, data must be
    04498 provided through callbacks or polling.
    04499 If a callback function is defined in the cbfp parameter, then this callback
    04500 function will be invoked to get the next piece after a piece is written to
    04501 the pipe. Each piece will be written from bufp.
    04502 If no callback function is defined, then OCILobWrite() returns the
    04503 OCI_NEED_DATA error code. The application must all OCILobWrite() again
    04504 to write more pieces of the LOB. In this mode, the buffer pointer and the
    04505 length can be different in each call if the pieces are of different sizes and
    04506 from different locations. A piece value of OCI_LAST_PIECE terminates the
    04507 piecewise write.
    04508
    04509 Parameters
    04510 svchp (IN/OUT) - the service context handle.
    04511 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04512 diagnostic information in the event of an error.
    04513 locp (IN/OUT) - a LOB locator that uniquely references a LOB.
    04514 offset (IN) - On input, it is the absolute offset, for character LOBs in
    04515 the number of characters from the beginning of the LOB, for binary LOBs it
    04516 is the number of bytes. Starts at 1.
    04517 bufp (IN) - the pointer to a buffer from which the piece will be written. The
    04518 length of the allocated memory is assumed to be the value passed in bufl.
    04519 Even if the data is being written in pieces, bufp must contain the first
    04520 piece of the LOB when this call is invoked.
    04521 bufl (IN) - the length of the buffer in bytes.
    04522 Note: This parameter assumes an 8-bit byte. If your platform uses a
    04523 longer byte, the value of bufl must be adjusted accordingly.
    04524 piece (IN) - which piece of the buffer is being written. The default value for
    04525 this parameter is OCI_ONE_PIECE, indicating the buffer will be written in a
    04526 single piece.
    04527 The following other values are also possible for piecewise or callback mode:
    04528 OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.
    04529 amtp (IN/OUT) - On input, takes the number of character or bytes to be
    04530 written. On output, returns the actual number of bytes or characters written.
    04531 If the data is written in pieces, *amtp will contain the total length of the
    04532 pieces written at the end of the call (last piece written) and is undefined in
    04533 between.
    04534 (Note it is different from the piecewise read case)
    04535 ctxp (IN) - the context for the call back function. Can be NULL.
    04536 cbfp (IN) - a callback that may be registered to be called for each piece in
    04537 a piecewise write. If this is NULL, the standard polling method will be used.
    04538 The callback function must return OCI_CONTINUE for the write to continue.
    04539 If any other error code is returned, the LOB write is aborted. The
    04540 callback takes the following parameters:
    04541   ctxp (IN) - the context for the call back function. Can be NULL.
    04542   bufp (IN/OUT) - a buffer pointer for the piece.
    04543   lenp (IN/OUT) - the length of the buffer (in octets) and the length of
    04544   current piece in bufp (out octets).
    04545   piecep (OUT) - which piece - OCI_NEXT_PIECE or OCI_LAST_PIECE.
    04546 csid - the character set ID of the buffer data
    04547 csfrm - the character set form of the buffer data
    04548 Related Functions
    04549
    04550 OCILobWriteAppend()
    04551
    04552 Name
    04553 OCI Lob Write Append
    04554
    04555 Purpose
    04556 Writes data to the end of a LOB value. This call provides the ability
    04557 to get the length of the data and append it to the end of the LOB in
    04558 a single round trip to the server.
    04559
    04560 Syntax
    04561 sword OCILobWriteAppend ( OCISvcCtx       *svchp,
    04562                     OCIError        *errhp,
    04563                     OCILobLocator   *locp,
    04564                     ub4             *amtp,
    04565                     dvoid           *bufp,
    04566                     ub4             buflen,
    04567                     ub1             piece,
    04568                     dvoid           *ctxp,
    04569                     OCICallbackLobWrite   (cbfp)
    04570                                     (
    04571                                     dvoid    *ctxp,
    04572                                     dvoid    *bufp,
    04573                                     ub4      *lenp,
    04574                                     ub1      *piecep )
    04575                     ub2             csid
    04576                     ub1             csfrm );
    04577
    04578
    04579 Comments
    04580 Writes a buffer to the end of a LOB as specified. If LOB data already exists
    04581 it is overwritten with the data stored in the buffer.
    04582 The buffer can be written to the LOB in a single piece with this call, or
    04583 it can be provided piecewise using callbacks or a standard polling method.
    04584 If this value of the piece parameter is OCI_FIRST_PIECE, data must be
    04585 provided through callbacks or polling.
    04586 If a callback function is defined in the cbfp parameter, then this callback
    04587 function will be invoked to get the next piece after a piece is written to the
    04588 pipe. Each piece will be written from bufp.
    04589 If no callback function is defined, then OCILobWriteAppend() returns the
    04590 OCI_NEED_DATA error code. The application must all OCILobWriteAppend() again
    04591 to write more pieces of the LOB. In this mode, the buffer pointer and the
    04592 length can be different in each call if the pieces are of different sizes and
    04593 from different locations. A piece value of OCI_LAST_PIECE terminates the
    04594 piecewise write.
    04595
    04596 Parameters
    04597 svchp (IN/OUT) - the service context handle.
    04598 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04599 diagnostic information in the event of an error.
    04600 locp (IN/OUT) - a LOB locator that uniquely references a LOB.
    04601 bufp (IN) - the pointer to a buffer from which the piece will be written. The
    04602 length of the allocated memory is assumed to be the value passed in bufl. Even
    04603 if the data is being written in pieces, bufp must contain the first piece of
    04604 the LOB when this call is invoked.
    04605 bufl (IN) - the length of the buffer in bytes.
    04606 Note: This parameter assumes an 8-bit byte. If your platform uses a
    04607 longer byte, the value of bufl must be adjusted accordingly.
    04608 piece (IN) - which piece of the buffer is being written. The default value for
    04609 this parameter is OCI_ONE_PIECE, indicating the buffer will be written in a
    04610 single piece.
    04611 The following other values are also possible for piecewise or callback mode:
    04612 OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.
    04613 amtp (IN/OUT) - On input, takes the number of character or bytes to be
    04614 written. On output, returns the actual number of bytes or characters written.
    04615 If the data is written in pieces, *amtp will contain the total length of the
    04616 pieces written at the end of the call (last piece written) and is undefined in
    04617 between.
    04618 (Note it is different from the piecewise read case)
    04619 ctxp (IN) - the context for the call back function. Can be NULL.
    04620 cbfp (IN) - a callback that may be registered to be called for each piece in a
    04621 piecewise write. If this is NULL, the standard polling method will be used.
    04622 The callback function must return OCI_CONTINUE for the write to continue.
    04623 If any other error code is returned, the LOB write is aborted. The
    04624 callback takes the following parameters:
    04625   ctxp (IN) - the context for the call back function. Can be NULL.
    04626   bufp (IN/OUT) - a buffer pointer for the piece.
    04627   lenp (IN/OUT) - the length of the buffer (in octets) and the length of
    04628   current piece in bufp (out octets).
    04629   piecep (OUT) - which piece - OCI_NEXT_PIECE or OCI_LAST_PIECE.
    04630 csid - the character set ID of the buffer data
    04631 csfrm - the character set form of the buffer data
    04632 Related Functions
    04633
    04634
    04635
    04636
    04637 OCILobGetStorageLimit()
    04638
    04639 Name
    04640 OCI Lob Get Storage Limit
    04641
    04642 Purpose
    04643 To get the maximum Length of a LOB in bytes that can be stored in the database.
    04644
    04645 Syntax
    04646 sword OCILobGetStorageLimit ( OCISvcCtx       *svchp,
    04647                     OCIError        *errhp,
    04648                     OCILobLocator   *locp,
    04649                     oraub8          *limitp);
    04650
    04651
    04652 Comments
    04653 With unlimited size LOB support the limit for a LOB is no longer restricted to 4GB.
    04654 This interface should be used to get the actual limit for storing data for a specific
    04655 LOB locator. Note that if the compatibality is set to 9.2 or older the limit would still
    04656 be 4GB.
    04657
    04658 Parameters
    04659 svchp (IN/OUT) - the service context handle.
    04660 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04661 diagnostic information in the event of an error.
    04662 locp (IN/OUT) - a LOB locator that uniquely references a LOB.
    04663 limitp (OUT)  - The storage limit for a LOB in bytes.
    04664 Related Functions
    04665
    04666
    04667
    04668
    04669 OCILogoff()
    04670 Name
    04671 OCI simplified Logoff
    04672 Purpose
    04673 This function is used to terminate a session created with OCILogon() or
    04674 OCILogon2().
    04675 Syntax
    04676 sword OCILogoff ( OCISvcCtx      *svchp
    04677                    OCIError       *errhp );
    04678 Comments
    04679 This call is used to terminate a session which was created with OCILogon() or
    04680 OCILogon2().
    04681 This call implicitly deallocates the server, authentication, and service
    04682 context handles.
    04683 Note: For more information on logging on and off in an application,
    04684 refer to the section "Application Initialization, Connection, and
    04685 Authorization" on page 2-16.
    04686 Parameters
    04687 svchp (IN) - the service context handle which was used in the call to
    04688 OCILogon() or OCILogon2().
    04689 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04690 diagnostic information in the event of an error.
    04691 See Also
    04692 OCILogon(), OCILogon2().
    04693
    04694
    04695
    04696
    04697
    04698
    04699 OCILogon()
    04700 Name
    04701 OCI Service Context Logon
    04702 Purpose
    04703 This function is used to create a simple logon session.
    04704 Syntax
    04705 sword OCILogon ( OCIEnv          *envhp,
    04706                        OCIError        *errhp,
    04707                        OCISvcCtx       *svchp,
    04708                        CONST OraText      *username,
    04709                        ub4             uname_len,
    04710                        CONST OraText      *password,
    04711                        ub4             passwd_len,
    04712                        CONST OraText      *dbname,
    04713                        ub4             dbname_len );
    04714 Comments
    04715 This function is used to create a simple logon session for an application.
    04716 Note: Users requiring more complex session (e.g., TP monitor
    04717 applications) should refer to the section "Application Initialization,
    04718 Connection, and Authorization" on page 2-16.
    04719 This call allocates the error and service context handles which are passed to
    04720 it. This call also implicitly allocates server and authentication handles
    04721 associated with the session.  These handles can be retrieved by calling
    04722 OCIAttrGet() on the service context handle.
    04723 Parameters
    04724 envhp (IN) - the OCI environment handle.
    04725 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04726 diagnostic information in the event of an error.
    04727 svchp (OUT) - the service context pointer.
    04728 username (IN) - the username.
    04729 uname_len (IN) - the length of username.
    04730 password (IN) - the user's password.
    04731 passwd_len (IN) - the length of password.
    04732 dbname (IN) - the name of the database to connect to.
    04733 dbname_len (IN) - the length of dbname.
    04734 See Also
    04735 OCILogoff()
    04736
    04737
    04738
    04739
    04740
    04741 OCILogon2()
    04742 Name
    04743 OCI Service Context Logon
    04744 Purpose
    04745 This function is used to create a logon session in connection pooling mode.
    04746 Syntax
    04747 sword OCILogon2 ( OCIEnv          *envhp,
    04748                        OCIError        *errhp,
    04749                        OCISvcCtx       **svchp,
    04750                        CONST OraText      *username,
    04751                        ub4             uname_len,
    04752                        CONST OraText      *password,
    04753                        ub4             passwd_len,
    04754                        CONST OraText      *dbname,
    04755                        ub4             dbname_len,
    04756                        ub4             mode);
    04757 Comments
    04758 This function is used to create a simple logon session for an application in
    04759 Connection Pooling mode. The valid values for mode are currently OCI_POOL and
    04760 OCI_DEFAULT. Call to this function with OCI_DEFAULT mode is equivalent to
    04761 OCILogon() call.
    04762 This call allocates the error and service context handles which are passed to
    04763 it. This call also implicitly allocates server and authentication handles
    04764 associated with the session.  These handles can be retrieved by calling
    04765 OCIAttrGet() on the service context handle. This call assumes that
    04766 OCIConnectionPoolCreate() has already been called for the same dbname.
    04767 Parameters
    04768 envhp (IN) - the OCI environment handle.
    04769 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04770 diagnostic information in the event of an error.
    04771 svchp (OUT) - the service context pointer.
    04772 username (IN) - the username.
    04773 uname_len (IN) - the length of username.
    04774 password (IN) - the user's password. If this is null, it is assumed that a
    04775                 proxy session has to be created and the required grants on
    04776                 the database are already done.
    04777 passwd_len (IN) - the length of password.
    04778 dbname (IN) - the name of the database to connect to.
    04779 dbname_len (IN) - the length of dbname.
    04780 mode (IN) - the mode for doing the server attach. Should be OCI_POOL for
    04781             using Connection Pooling.
    04782
    04783
    04784 See Also
    04785 OCILogoff()
    04786
    04787
    04788
    04789
    04790
    04791 OCIMemoryFree()
    04792 Name
    04793 OCI FREE Memory
    04794 Purpose
    04795 Frees up storage associated with the pointer.
    04796 Syntax
    04797 void OCIMemoryFree ( CONST OCIStmt   *stmhp,
    04798                      dvoid           *memptr);
    04799 Comments
    04800 Frees up dynamically allocated data pointers associated with the pointer using
    04801 either the default memory free function or the registered memory free
    04802 function, as the case may be.
    04803 A user-defined memory free function can be registered during the initial call
    04804 to OCIInitialize().
    04805 This call is always successful.
    04806 Parameters
    04807 stmhp (IN) - statement handle which returned this data buffer.
    04808 memptr (IN) - pointer to data allocated by the client library.
    04809 Related Functions
    04810 OCIInitialize()
    04811
    04812
    04813
    04814
    04815
    04816 OCIParamGet()
    04817 Name
    04818 OCI Get PARaMeter
    04819 Purpose
    04820 Returns a descriptor of a parameter specified by position in the describe
    04821 handle or statement handle.
    04822 Syntax
    04823 sword OCIParamGet ( CONST dvoid       *hndlp,
    04824                   ub4         htype,
    04825                   OCIError    *errhp,
    04826                   dvoid    **parmdpp,
    04827                   ub4         pos );
    04828 Comments
    04829 This call returns a descriptor of a parameter specified by position in the
    04830 describe handle or statement handle. Parameter descriptors are always
    04831 allocated internally by the OCI library. They are read-only.
    04832 OCI_NO_DATA may be returned if there are no parameter descriptors for this
    04833 position.
    04834 See Appendix B for more detailed information about parameter descriptor
    04835 attributes.
    04836 Parameters
    04837 hndlp (IN) - a statement handle or describe handle. The OCIParamGet()
    04838 function will return a parameter descriptor for this handle.
    04839 htype (IN) - the type of the handle passed in the handle parameter. Valid
    04840 types are OCI_HTYPE_DESCRIBE, for a describe handle OCI_HTYPE_STMT, for a
    04841 statement handle
    04842 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04843 diagnostic information in the event of an error.
    04844 parmdpp (OUT) - a descriptor of the parameter at the position given in the pos
    04845 parameter.
    04846 pos (IN) - position number in the statement handle or describe handle. A
    04847 parameter descriptor will be returned for this position.
    04848 Note: OCI_NO_DATA may be returned if there are no parameter
    04849 descriptors for this position.
    04850 Related Functions
    04851 OCIAttrGet(), OCIAttrSet()
    04852
    04853
    04854
    04855
    04856
    04857 OCIParamSet()
    04858 Name
    04859 OCI Parameter Set in handle
    04860 Purpose
    04861 Used to set a complex object retrieval descriptor into a complex object
    04862 retrieval handle.
    04863 Syntax
    04864 sword   OCIParamGet ( dvoid *hndlp,
    04865                        ub4 htyp,
    04866                       OCIError *errhp,
    04867                       CONST dvoid *dscp,
    04868                       ub4 dtyp,
    04869                       ub4 pos );
    04870 Comments
    04871 This call sets a given complex object retrieval descriptor into a complex
    04872 object retrieval handle.
    04873 The handle must have been previously allocated using OCIHandleAlloc(), and
    04874 the descriptor must have been previously allocated using OCIDescAlloc().
    04875 Attributes of the descriptor are set using OCIAttrSet().
    04876 Parameters
    04877 hndlp (IN/OUT) - handle pointer.
    04878 htype (IN) - handle type.
    04879 errhp (IN/OUT) - error handle.
    04880 dscp (IN) - complex object retrieval descriptor pointer.
    04881 dtyp (IN) -
    04882 pos (IN) - position number.
    04883 See Also
    04884
    04885
    04886
    04887
    04888
    04889 OCIPasswordChange()
    04890 Name
    04891 OCI Change PassWord
    04892 Purpose
    04893 This call allows the password of an account to be changed.
    04894 Syntax
    04895 sword OCIPasswordChange ( OCISvcCtx     *svchp,
    04896                         OCIError      *errhp,
    04897                         CONST OraText    *user_name,
    04898                         ub4           usernm_len,
    04899                         CONST OraText    *opasswd,
    04900                         ub4           opasswd_len,
    04901                         CONST OraText    *npasswd,
    04902                         sb4           npasswd_len,
    04903                         ub4           mode);
    04904 Comments
    04905 This call allows the password of an account to be changed. This call is
    04906 similar to OCISessionBegin() with the following differences:
    04907 If the user authentication is already established, it authenticates
    04908 the account using the old password and then changes the
    04909 password to the new password
    04910 If the user authentication is not established, it establishes a user
    04911 authentication and authenticates the account using the old
    04912 password, then changes the password to the new password.
    04913 This call is useful when the password of an account is expired and
    04914 OCISessionBegin() returns an error or warning which indicates that the
    04915 password has expired.
    04916 Parameters
    04917 svchp (IN/OUT) - a handle to a service context. The service context handle
    04918 must be initialized and have a server context handle associated with it.
    04919 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    04920 diagnostic information in the event of an error.
    04921 user_name (IN) - specifies the user name. It points to a character string,
    04922 whose length is specified in usernm_len. This parameter must be NULL if the
    04923 service context has been initialized with an authentication handle.
    04924 usernm_len (IN) - the length of the user name string specified in user_name.
    04925 For a valid user name string, usernm_len must be non-zero.
    04926 opasswd (IN) - specifies the user's old password. It points to a character
    04927 string, whose length is specified in opasswd_len .
    04928 opasswd_len (IN) - the length of the old password string specified in opasswd.
    04929 For a valid password string, opasswd_len must be non-zero.
    04930 npasswd (IN) - specifies the user's new password. It points to a character
    04931 string, whose length is specified in npasswd_len which must be non-zero for a
    04932 valid password string. If the password complexity verification routine is
    04933 specified in the user's profile to verify the new password's complexity, the
    04934 new password must meet the complexity requirements of the verification
    04935 function.
    04936 npasswd_len (IN)  - then length of the new password string specified in
    04937 npasswd. For a valid password string, npasswd_len must be non-zero.
    04938 mode - pass as OCI_DEFAULT.
    04939 Related Functions
    04940 OCISessionBegin()
    04941
    04942
    04943 ----------------------------------OCIReset------------------------------------
    04944
    04945
    04946 OCIReset()
    04947 Name
    04948 OCI Reset
    04949 Purpose
    04950 Resets the interrupted asynchronous operation and protocol. Must be called
    04951 if a OCIBreak call had been issued while a non-blocking operation was in
    04952 progress.
    04953 Syntax
    04954 sword OCIReset ( dvoid      *hndlp,
    04955                  OCIError   *errhp);
    04956 Comments
    04957 This call is called in non-blocking mode ONLY. Resets the interrupted
    04958 asynchronous operation and protocol. Must be called if a OCIBreak call
    04959 had been issued while a non-blocking operation was in progress.
    04960 Parameters
    04961 hndlp (IN) - the service context handle or the server context handle.
    04962 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    04963 diagnostic information in the event of an error.
    04964 Related Functions
    04965
    04966
    04967 OCIResultSetToStmt()
    04968 Name
    04969 OCI convert Result Set to Statement Handle
    04970 Purpose
    04971 Converts a descriptor to statement handle for fetching rows.
    04972 Syntax
    04973 sword OCIResultSetToStmt ( OCIResult     *rsetdp,
    04974                          OCIError      *errhp );
    04975 Comments
    04976 Converts a descriptor to statement handle for fetching rows.
    04977 A result set descriptor can be allocated with a call to OCIDescAlloc().
    04978 Parameters
    04979 rsetdp (IN/OUT) - a result set descriptor pointer.
    04980 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    04981 diagnostic information in the event of an error.
    04982 Related Functions
    04983 OCIDescAlloc()
    04984
    04985
    04986
    04987
    04988 OCIServerAttach()
    04989 Name
    04990 OCI ATtaCH to server
    04991 Purpose
    04992 Creates an access path to a data source for OCI operations.
    04993 Syntax
    04994 sword OCIServerAttach ( OCIServer    *srvhp,
    04995                       OCIError     *errhp,
    04996                       CONST OraText   *dblink,
    04997                       sb4          dblink_len,
    04998                       ub4          mode);
    04999 Comments
    05000 This call is used to create an association between an OCI application and a
    05001 particular server.
    05002 This call initializes a server context handle, which must have been previously
    05003 allocated with a call to OCIHandleAlloc().
    05004 The server context handle initialized by this call can be associated with a
    05005 service context through a call to OCIAttrSet(). Once that association has been
    05006 made, OCI operations can be performed against the server.
    05007 If an application is operating against multiple servers, multiple server
    05008 context handles can be maintained. OCI operations are performed against
    05009 whichever server context is currently associated with the service context.
    05010 Parameters
    05011 srvhp (IN/OUT) - an uninitialized server context handle, which gets
    05012 initialized by this call. Passing in an initialized server handle causes an
    05013 error.
    05014 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    05015 diagnostic information in the event of an error.
    05016 dblink (IN) - specifies the database (server) to use. This parameter points to
    05017 a character string which specifies a connect string or a service point. If the
    05018 connect string is NULL, then this call attaches to the default host. The length
    05019 of connstr is specified in connstr_len. The connstr pointer may be freed by the
    05020 caller on return.
    05021 dblink_len (IN) - the length of the string pointed to by connstr. For a valid
    05022 connect string name or alias, connstr_len must be non-zero.
    05023 mode (IN) - specifies the various modes of operation.  For release 8.0, pass as
    05024 OCI_DEFAULT - in this mode, calls made to the server on this server context
    05025 are made in blocking mode.
    05026 Example
    05027 See the description of OCIStmtPrepare() on page 13-96 for an example showing
    05028 the use of OCIServerAttach().
    05029 Related Functions
    05030 OCIServerDetach()
    05031
    05032
    05033
    05034 OCIServerDetach()
    05035 Name
    05036 OCI DeTaCH server
    05037 Purpose
    05038 Deletes an access to a data source for OCI operations.
    05039 Syntax
    05040 sword OCIServerDetach ( OCIServer   *svrhp,
    05041                       OCIError    *errhp,
    05042                       ub4         mode);
    05043 Comments
    05044 This call deletes an access to data source for OCI operations, which was
    05045 established by a call to OCIServerAttach().
    05046 Parameters
    05047 srvhp (IN) - a handle to an initialized server context, which gets reset to
    05048 uninitialized state. The handle is not de-allocated.
    05049 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    05050 diagnostic information in the event of an error.
    05051 mode (IN) - specifies the various modes of operation. The only valid mode is
    05052 OCI_DEFAULT for the default mode.
    05053 Related Functions
    05054 OCIServerAttach()
    05055
    05056
    05057
    05058 OCIServerVersion()
    05059 Name
    05060 OCI VERSion
    05061 Purpose
    05062 Returns the version string of the Oracle server.
    05063 Syntax
    05064 sword OCIServerVersion ( dvoid        *hndlp,
    05065                        OCIError     *errhp,
    05066                        OraText         *bufp,
    05067                        ub4          bufsz
    05068                        ub1          hndltype );
    05069 Comments
    05070 This call returns the version string of the Oracle server.
    05071 For example, the following might be returned as the version string if your
    05072 application is running against a 7.3.2 server:
    05073 Oracle7 Server Release 7.3.2.0.0 - Production Release
    05074 PL/SQL Release 2.3.2.0.0 - Production
    05075 CORE Version 3.5.2.0.0 - Production
    05076 TNS for SEQUENT DYNIX/ptx: Version 2.3.2.0.0 - Production
    05077 NLSRTL Version 3.2.2.0.0 - Production
    05078
    05079 Parameters
    05080 hndlp (IN) - the service context handle or the server context handle.
    05081 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    05082 diagnostic information in the event of an error.
    05083 bufp (IN) - the buffer in which the version information is returned.
    05084 bufsz (IN) - the length of the buffer.
    05085 hndltype (IN) - the type of handle passed to the function.
    05086 Related Functions
    05087
    05088
    05089
    05090
    05091
    05092 OCISessionBegin()
    05093 Name
    05094 OCI Session Begin and authenticate user
    05095 Purpose
    05096 Creates a user authentication and begins a user session for a given server.
    05097 Syntax
    05098 sword OCISessionBegin ( OCISvcCtx     *svchp,
    05099                       OCIError      *errhp,
    05100                       OCISession    *usrhp,
    05101                       ub4           credt,
    05102                       ub4           mode);
    05103
    05104 Comments
    05105 For Oracle8, OCISessionBegin() must be called for any given server handle
    05106 before requests can be made against it. Also, OCISessionBegin() only supports
    05107 authenticating the user for access to the Oracle server specified by the
    05108 server handle in the service context. In other words, after OCIServerAttach()
    05109 is called to initialize a server handle, OCISessionBegin() must be called to
    05110 authenticate the user for that given server.
    05111 When OCISessionBegin() is called for the first time for the given server
    05112 handle, the initialized authentication handle is called a primary
    05113 authentication context. A primary authentication context may not be created
    05114 with the OCI_MIGRATE mode. Also, only one primary authentication context can
    05115 be created for a given server handle and the primary authentication context c
    05116 an only ever be used with that server handle. If the primary authentication
    05117 context is set in a service handle with a different server handle, then an
    05118 error will result.
    05119 After OCISessionBegin() has been called for the server handle, and the primary
    05120 authentication context is set in the service handle, OCISessionBegin() may be
    05121 called again to initialize another authentication handle with different (or
    05122 the same) credentials. When OCISessionBegin() is called with a service handle
    05123 set with a primary authentication context, the returned authentication context
    05124 in authp is called a user authentication context. As many user authentication
    05125 contexts may be initialized as desired.
    05126 User authentication contexts may be created with the OCI_MIGRATE mode.
    05127 If the OCI_MIGRATE mode is not specified, then the user authentication
    05128 context can only ever be used with the same server handle set in svchp. If
    05129 OCI_MIGRATE mode is specified, then the user authentication may be set
    05130 with different server handles. However, the user authentication context is
    05131 restricted to use with only server handles which resolve to the same database
    05132 instance and that have equivalent primary authentication contexts. Equivalent
    05133 authentication contexts are those which were authenticated as the same
    05134 database user.
    05135 OCI_SYSDBA, OCI_SYSOPER, and OCI_PRELIM_AUTH may only be used
    05136 with a primary authentication context.
    05137 To provide credentials for a call to OCISessionBegin(), one of two methods are
    05138 supported. The first is to provide a valid username and password pair for
    05139 database authentication in the user authentication handle passed to
    05140 OCISessionBegin(). This involves using OCIAttrSet() to set the
    05141 OCI_ATTR_USERNAME and OCI_ATTR_PASSWORD attributes on the
    05142 authentication handle. Then OCISessionBegin() is called with
    05143 OCI_CRED_RDBMS.
    05144 Note: When the authentication handle is terminated using
    05145 OCISessionEnd(), the username and password attributes remain
    05146 unchanged and thus can be re-used in a future call to OCISessionBegin().
    05147 Otherwise, they must be reset to new values before the next
    05148 OCISessionBegin() call.
    05149 The second type of credentials supported are external credentials. No
    05150 attributes need to be set on the authentication handle before calling
    05151 OCISessionBegin(). The credential type is OCI_CRED_EXT. This is equivalent
    05152 to the Oracle7 `connect /' syntax. If values have been set for
    05153 OCI_ATTR_USERNAME and OCI_ATTR_PASSWORD, then these are
    05154 ignored if OCI_CRED_EXT is used.
    05155 Parameters
    05156 svchp (IN) - a handle to a service context. There must be a valid server
    05157 handle set in svchp.
    05158 errhp (IN) - an error handle to the retrieve diagnostic information.
    05159 usrhp (IN/OUT) - a handle to an authentication context, which is initialized
    05160 by this call.
    05161 credt (IN) - specifies the type of credentials to use for authentication.
    05162 Valid values for credt are:
    05163 OCI_CRED_RDBMS - authenticate using a database username and
    05164 password pair as credentials. The attributes OCI_ATTR_USERNAME
    05165 and OCI_ATTR_PASSWORD should be set on the authentication
    05166 context before this call.
    05167 OCI_CRED_EXT - authenticate using external credentials. No username
    05168 or password is provided.
    05169 mode (IN) - specifies the various modes of operation. Valid modes are:
    05170 OCI_DEFAULT - in this mode, the authentication context returned may
    05171 only ever be set with the same server context specified in svchp. This
    05172 establishes the primary authentication context.
    05173 OCI_MIGRATE - in this mode, the new authentication context may be
    05174 set in a service handle with a different server handle. This mode
    05175 establishes the user authentication context.
    05176 OCI_SYSDBA - in this mode, the user is authenticated for SYSDBA
    05177 access.
    05178 OCI_SYSOPER - in this mode, the user is authenticated for SYSOPER
    05179 access.
    05180 OCI_PRELIM_AUTH - this mode may only be used with OCI_SYSDBA
    05181 or OCI_SYSOPER to authenticate for certain administration tasks.
    05182 Related Functions
    05183 OCISessionEnd()
    05184
    05185
    05186
    05187
    05188
    05189
    05190 OCISessionEnd()
    05191 Name
    05192 OCI Terminate user Authentication Context
    05193 Purpose
    05194 Terminates a user authentication context created by OCISessionBegin()
    05195 Syntax
    05196 sword OCISessionEnd ( OCISvcCtx       *svchp,
    05197                     OCIError        *errhp,
    05198                     OCISession      *usrhp,
    05199                     ub4             mode);
    05200
    05201 Comments
    05202 The user security context associated with the service context is invalidated
    05203 by this call. Storage for the authentication context is not freed. The
    05204 transaction specified by the service context is implicitly committed. The
    05205 transaction handle, if explicitly allocated, may be freed if not being used.
    05206 Resources allocated on the server for this user are freed.
    05207 The authentication handle may be reused in a new call to OCISessionBegin().
    05208 Parameters
    05209 svchp (IN/OUT) - the service context handle. There must be a valid server
    05210 handle and user authentication handle associated with svchp.
    05211 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    05212 diagnostic information in the event of an error.
    05213 usrhp (IN) - de-authenticate this user. If this parameter is passed as NULL,
    05214 the user in the service context handle is de-authenticated.
    05215 mode (IN) - the only valid mode is OCI_DEFAULT.
    05216 Example
    05217 In this example, an authentication context is destroyed.
    05218 Related Functions
    05219 OCISessionBegin()
    05220
    05221
    05222
    05223
    05224 OCIStmtExecute()
    05225 Name
    05226 OCI EXECute
    05227 Purpose
    05228 This call associates an application request with a server.
    05229 Syntax
    05230 sword OCIStmtExecute ( OCISvcCtx           *svchp,
    05231                      OCIStmt             *stmtp,
    05232                      OCIError            *errhp,
    05233                      ub4                 iters,
    05234                      ub4                 rowoff,
    05235                      CONST OCISnapshot   *snap_in,
    05236                      OCISnapshot         *snap_out,
    05237                      ub4                 mode );
    05238 Comments
    05239 This function  is used to execute a prepared SQL statement.
    05240 Using an execute call, the application associates a request with a server. On
    05241 success, OCI_SUCCESS is returned.
    05242 If a SELECT statement is executed, the description of the select list follows
    05243 implicitly as a response. This description is buffered on the client side for
    05244 describes, fetches and define type conversions. Hence it is optimal to
    05245 describe a select list only after an execute.
    05246 Also for SELECT statements, some results are available implicitly. Rows will
    05247 be received and buffered at the end of the execute. For queries with small row
    05248 count, a prefetch causes memory to be released in the server if the end of
    05249 fetch is reached, an optimization that may result in memory usage reduction.
    05250 Set attribute call has been defined to set the number of rows to be prefetched
    05251 per result set.
    05252 For SELECT statements, at the end of the execute, the statement handle
    05253 implicitly maintains a reference to the service context on which it is
    05254 executed. It is the user's responsibility to maintain the integrity of the
    05255 service context. If the attributes of a service context is changed for
    05256 executing some operations on this service context, the service context must
    05257 be restored to have the same attributes, that a statement was executed with,
    05258 prior to a fetch on the statement handle. The implicit reference is maintained
    05259 until the statement handle is freed or the fetch is cancelled or an end of
    05260 fetch condition is reached.
    05261 Note: If output variables are defined for a SELECT statement before a
    05262 call to OCIStmtExecute(), the number of rows specified by iters will be
    05263 fetched directly into the defined output buffers and additional rows
    05264 equivalent to the prefetch count will be prefetched. If there are no
    05265 additional rows, then the fetch is complete without calling
    05266 OCIStmtFetch().
    05267 The execute call will return errors if the statement has bind data types that
    05268 are not supported in an Oracle7 server.
    05269 Parameters
    05270 svchp (IN/OUT) - service context handle.
    05271 stmtp (IN/OUT) - an statement handle - defines the statement and the
    05272 associated data to be executed at the server. It is invalid to pass in a
    05273 statement handle that has bind of data types only supported in release 8.0
    05274 when srvchp points to an Oracle7 server.
    05275 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    05276 diagnostic information in the event of an error. If the statement is being
    05277 batched and it is successful, then this handle will contain this particular
    05278 statement execution specific errors returned from the server when the batch is
    05279 flushed.
    05280 iters (IN) - the number of times this statement is executed for non-Select
    05281 statements. For Select statements, if iters is non-zero, then defines must
    05282 have been done for the statement handle. The execution fetches iters rows into
    05283 these predefined buffers and prefetches more rows depending upon the prefetch
    05284 row count. This function returns an error if iters=0 for non-SELECT
    05285 statements.
    05286 rowoff (IN) - the index from which the data in an array bind is relevant for
    05287 this multiple row execution.
    05288 snap_in (IN) - this parameter is optional. if supplied, must point to a
    05289 snapshot descriptor of type OCI_DTYPE_SNAP.  The contents of this descriptor
    05290 must be obtained from the snap_out parameter of a previous call.  The
    05291 descriptor is ignored if the SQL is not a SELECT.  This facility allows
    05292 multiple service contexts to ORACLE to see the same consistent snapshot of the
    05293 database's committed data.  However, uncommitted data in one context is not
    05294 visible to another context even using the same snapshot.
    05295 snap_out (OUT) - this parameter optional. if supplied, must point to a
    05296 descriptor of type OCI_DTYPE_SNAP. This descriptor is filled in with an
    05297 opaque representation which is the current ORACLE "system change
    05298 number" suitable as a snap_in input to a subsequent call to OCIStmtExecute().
    05299 This descriptor should not be used any longer than necessary in order to avoid
    05300 "snapshot too old" errors.
    05301 mode (IN) - The modes are:
    05302 If OCI_DEFAULT_MODE, the default mode, is selected, the request is
    05303 immediately executed. Error handle contains diagnostics on error if any.
    05304 OCI_EXACT_FETCH - if the statement is a SQL SELECT, this mode is
    05305 only valid if the application has set the prefetch row count prior to this
    05306 call. In this mode, the OCI library will get up to the number of rows
    05307 specified (i.e., prefetch row count plus iters). If the number of rows
    05308 returned by the query is greater than this value, OCI_ERROR will be
    05309 returned with ORA-01422 as the implementation specific error in a
    05310 diagnostic record. If the number of rows returned by the query is
    05311 smaller than the prefetch row count, OCI_SUCCESS_WITH_INFO will
    05312 be returned with ORA-01403 as the implementation specific error. The
    05313 prefetch buffer size is ignored and the OCI library tries to allocate all the
    05314 space required to contain the prefetched rows. The exact fetch semantics
    05315 apply to only the top level rows. No more rows can be fetched for this
    05316 query at the end of the call.
    05317 OCI_KEEP_FETCH_STATE - the result set rows (not yet fetched) of this
    05318 statement executed in this transaction will be maintained when the
    05319 transaction is detached for migration. By default, a query is cancelled
    05320 when a transaction is detached for migration. This mode is the default
    05321 mode when connected to a V7 server.
    05322 Related Functions
    05323 OCIStmtPrepare()
    05324
    05325
    05326
    05327
    05328
    05329 OCIStmtFetch()
    05330 Name
    05331 OCI FetCH
    05332 Purpose
    05333 Fetches rows from a query.
    05334 Syntax
    05335 sword OCIStmtFetch ( OCIStmt     *stmtp,
    05336                    OCIError    *errhp,
    05337                    ub4         nrows,
    05338                    ub2         orientation,
    05339                    ub4         mode);
    05340 Comments
    05341 The fetch call is a local call, if prefetched rows suffice. However, this is
    05342 transparent to the application. If LOB columns are being read, LOB locators
    05343 are fetched for subsequent LOB operations to be performed on these locators.
    05344 Prefetching is turned off if LONG columns are involved.
    05345 A fetch with nrows set to 0 rows effectively cancels the fetch for this
    05346 statement.
    05347 Parameters
    05348 stmtp (IN) - a statement (application request) handle.
    05349 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    05350 diagnostic information in the event of an error.
    05351 nrows (IN) - number of rows to be fetched from the current position.
    05352 orientation (IN) - for release 8.0, the only acceptable value is
    05353 OCI_FETCH_NEXT, which is also the default value.
    05354 mode (IN) - for release 8.0, beta-1, the following mode is defined.
    05355 OCI_DEFAULT - default mode
    05356 OCI_EOF_FETCH - indicates that it is the last fetch from the result set.
    05357 If nrows is non-zero, setting this mode effectively cancels fetching after
    05358 retrieving nrows, otherwise it cancels fetching immediately.
    05359 Related Functions
    05360 OCIAttrGet()
    05361
    05362 OCIStmtFetch2()
    05363 Name
    05364 OCI FetCH2
    05365 Purpose
    05366 Fetches rows from a query.
    05367 Syntax
    05368 sword OCIStmtFetch2 ( OCIStmt     *stmtp,
    05369                    OCIError    *errhp,
    05370                    ub4         nrows,
    05371                    ub2         orientation,
    05372                    ub4         scrollOffset,
    05373                    ub4         mode);
    05374 Comments
    05375 The fetch call works similar to the OCIStmtFetch call with the
    05376 addition of the fetchOffset parameter. It can be used on any
    05377 statement handle, whether it is scrollable or not. For a
    05378 non-scrollable statement handle, the only acceptable value
    05379 will be OCI_FETCH_NEXT, and the fetchOffset parameter will be
    05380 ignored. Applications are encouraged to use this new call.
    05381
    05382 A fetchOffset with OCI_FETCH_RELATIVE is equivalent to
    05383 OCI_FETCH_CURRENT with a value of 0, is equivalent to
    05384 OCI_FETCH_NEXT with a value of 1, and equivalent to
    05385 OCI_FETCH_PRIOR with a value of -1. Note that the range of
    05386 accessible rows is [1,OCI_ATTR_ROW_COUNT] beyond which an
    05387 error could be raised if sufficient rows do not exist in
    05388
    05389 The fetch call is a local call, if prefetched rows suffice. However, this is
    05390 transparent to the application. If LOB columns are being read, LOB locators
    05391 are fetched for subsequent LOB operations to be performed on these locators.
    05392 Prefetching is turned off if LONG columns are involved.
    05393 A fetch with nrows set to 0 rows effectively cancels the fetch for this
    05394 statement.
    05395 Parameters
    05396 stmtp (IN) - a statement (application request) handle.
    05397 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    05398 diagnostic information in the event of an error.
    05399 nrows (IN) - number of rows to be fetched from the current position.
    05400 It defaults to 1 for orientation OCI_FETCH_LAST.
    05401 orientation (IN) -  The acceptable values are as follows, with
    05402 OCI_FETCH_NEXT being the default value.
    05403 OCI_FETCH_CURRENT gets the current row,
    05404 OCI_FETCH_NEXT gets the next row from the current position,
    05405 OCI_FETCH_FIRST gets the first row in the result set,
    05406 OCI_FETCH_LAST gets the last row in the result set,
    05407 OCI_FETCH_PRIOR gets the previous row from the current row in the result set,
    05408 OCI_FETCH_ABSOLUTE will fetch the row number (specified by fetchOffset
    05409 parameter) in the result set using absolute positioning,
    05410 OCI_FETCH_RELATIVE will fetch the row number (specified by fetchOffset
    05411 parameter) in the result set using relative positioning.
    05412 scrollOffset(IN) - offset used with the OCI_FETCH_ABSOLUTE and
    05413 OCI_FETCH_RELATIVE orientation parameters only. It specify
    05414 the new current position for scrollable result set. It is
    05415 ignored for non-scrollable result sets.
    05416 mode (IN) - for release 8.0, beta-1, the following mode is defined.
    05417 OCI_DEFAULT - default mode
    05418 OCI_EOF_FETCH - indicates that it is the last fetch from the result set.
    05419 If nrows is non-zero, setting this mode effectively cancels fetching after
    05420 retrieving nrows, otherwise it cancels fetching immediately.
    05421 Related Functions
    05422 OCIAttrGet()
    05423
    05424
    05425
    05426 OCIStmtGetPieceInfo()
    05427 Name
    05428 OCI Get Piece Information
    05429 Purpose
    05430 Returns piece information for a piecewise operation.
    05431 Syntax
    05432 sword OCIStmtGetPieceInfo( CONST OCIStmt  *stmtp,
    05433                          OCIError       *errhp,
    05434                          dvoid          **hndlpp,
    05435                          ub4            *typep,
    05436                          ub1            *in_outp,
    05437                          ub4            *iterp,
    05438                          ub4            *idxp,
    05439                          ub1            *piecep );
    05440
    05441 Comments
    05442 When an execute/fetch call returns OCI_NEED_DATA to get/return a
    05443 dynamic bind/define value or piece, OCIStmtGetPieceInfo() returns the
    05444 relevant information: bind/define handle, iteration or index number and
    05445 which piece.
    05446 See the section "Runtime Data Allocation and Piecewise Operations" on page
    05447 5-16 for more information about using OCIStmtGetPieceInfo().
    05448 Parameters
    05449 stmtp (IN) - the statement when executed returned OCI_NEED_DATA.
    05450 errhp (OUT) - an error handle which can be passed to OCIErrorGet() for
    05451 diagnostic information in the event of an error.
    05452 hndlpp (OUT) - returns a pointer to the bind or define handle of the bind or
    05453 define whose runtime data is required or is being provided.
    05454 typep (OUT) - the type of the handle pointed to by hndlpp: OCI_HTYPE_BIND
    05455 (for a bind handle) or OCI_HTYPE_DEFINE (for a define handle).
    05456 in_outp (OUT) - returns OCI_PARAM_IN if the data is required for an IN bind
    05457 value. Returns OCI_PARAM_OUT if the data is available as an OUT bind
    05458 variable or a define position value.
    05459 iterp (OUT) - returns the row number of a multiple row operation.
    05460 idxp (OUT) - the index of an array element of a PL/SQL array bind operation.
    05461 piecep (OUT) - returns one of the following defined values -
    05462 OCI_ONE_PIECE, OCI_FIRST_PIECE, OCI_NEXT_PIECE and
    05463 OCI_LAST_PIECE. The default value is always OCI_ONE_PIECE.
    05464 Related Functions
    05465 OCIAttrGet(), OCIAttrGet(), OCIStmtExecute(), OCIStmtFetch(),
    05466 OCIStmtSetPieceInfo()
    05467
    05468
    05469
    05470
    05471 OCIStmtPrepare()
    05472 Name
    05473 OCI Statement REQuest
    05474 Purpose
    05475 This call defines the SQL/PLSQL statement to be executed.
    05476 Syntax
    05477 sword OCIStmtPrepare ( OCIStmt      *stmtp,
    05478                      OCIError     *errhp,
    05479                      CONST OraText   *stmt,
    05480                      ub4          stmt_len,
    05481                      ub4          language,
    05482                      ub4          mode);
    05483 Comments
    05484 This call is used to prepare a SQL or PL/SQL statement for execution. The
    05485 OCIStmtPrepare() call defines an application request.
    05486 This is a purely local call. Data values for this statement initialized in
    05487 subsequent bind calls will be stored in a bind handle which will hang off this
    05488 statement handle.
    05489 This call does not create an association between this statement handle and any
    05490 particular server.
    05491 See the section "Preparing Statements" on page 2-21 for more information
    05492 about using this call.
    05493 Parameters
    05494 stmtp (IN) - a statement handle.
    05495 errhp (IN) - an error handle to retrieve diagnostic information.
    05496 stmt (IN) - SQL or PL/SQL statement to be executed. Must be a null-terminated
    05497 string. The pointer to the OraText of the statement must be available as long
    05498 as the statement is executed.
    05499 stmt_len (IN) - length of the statement. Must not be zero.
    05500 language (IN) - V7, V8, or native syntax. Possible values are:
    05501 OCI_V7_SYNTAX - V7 ORACLE parsing syntax
    05502 OCI_V8_SYNTAX - V8 ORACLE parsing syntax
    05503 OCI_NTV_SYNTAX - syntax depending upon the version of the server.
    05504 mode (IN) - the only defined mode is OCI_DEFAULT for default mode.
    05505 Example
    05506 This example demonstrates the use of OCIStmtPrepare(), as well as the OCI
    05507 application initialization calls.
    05508 Related Functions
    05509 OCIAttrGet(), OCIStmtExecute()
    05510
    05511
    05512 OCIStmtPrepare2()
    05513 Name
    05514 OCI Statement REQuest with (a) early binding to svchp and/or
    05515 (b) stmt caching
    05516 Purpose
    05517 This call defines the SQL/PLSQL statement to be executed.
    05518 Syntax
    05519 sword OCIStmtPrepare2 ( OCISvcCtx *svchp,
    05520                      OCIStmt      **stmtp,
    05521                      OCIError     *errhp,
    05522                      CONST OraText   *stmt,
    05523                      ub4          stmt_len,
    05524                      CONST OraText *key,
    05525                      ub4          key_len,
    05526                      ub4          language,
    05527                      ub4          mode);
    05528 Comments
    05529 This call is used to prepare a SQL or PL/SQL statement for execution. The
    05530 OCIStmtPrepare() call defines an application request.
    05531 This is a purely local call. Data values for this statement initialized in
    05532 subsequent bind calls will be stored in a bind handle which will hang off this
    05533 statement handle.
    05534 This call creates an association between the statement handle and a service
    05535 context. It differs from OCIStmtPrepare in that respect.It also supports
    05536 stmt caching. The stmt will automatically be cached if the authp of the stmt
    05537 has enabled stmt caching.
    05538 Parameters
    05539 svchp (IN) - the service context handle that contains the session that
    05540              this stmt handle belongs to.
    05541 stmtp (OUT) - an unallocated stmt handle must be pased in. An allocated
    05542               and prepared  statement handle will be returned.
    05543 errhp (IN) - an error handle to retrieve diagnostic information.
    05544 stmt (IN) - SQL or PL/SQL statement to be executed. Must be a null-
    05545             terminated string. The pointer to the OraText of the statement
    05546             must be available as long as the statement is executed.
    05547 stmt_len (IN) - length of the statement. Must not be zero.
    05548 key (IN) - This is only Valid for OCI Stmt Caching. It indicates the
    05549            key to search with. It thus optimizes the search in the cache.
    05550 key_len (IN) - the length of the key. This, too, is onlly valid for stmt
    05551                caching.
    05552 language (IN) - V7, V8, or native syntax. Possible values are:
    05553 OCI_V7_SYNTAX - V7 ORACLE parsing syntax
    05554 OCI_V8_SYNTAX - V8 ORACLE parsing syntax
    05555 OCI_NTV_SYNTAX - syntax depending upon the version of the server.
    05556 mode (IN) - the defined modes are OCI_DEFAULT and OCI_PREP2_CACHE_SEARCHONLY.
    05557 Example
    05558 Related Functions
    05559 OCIStmtExecute(), OCIStmtRelease()
    05560
    05561
    05562 OCIStmtRelease()
    05563 Name
    05564 OCI Statement Release. This call is used to relesae the stmt that
    05565 was retreived using OCIStmtPrepare2(). If the stmt is release
    05566 using this call, OCIHandleFree() must not be called on the stmt
    05567 handle.
    05568 Purpose
    05569 This call releases the statement obtained by OCIStmtPrepare2
    05570 Syntax
    05571 sword OCIStmtRelease ( OCIStmt      *stmtp,
    05572                      OCIError     *errhp,
    05573                      cONST OraText *key,
    05574                      ub4          key_len,
    05575                      ub4          mode);
    05576 Comments
    05577 This call is used to release a handle obtained via OCIStmtPrepare2().
    05578 It also frees the memory associated with the handle.
    05579 This is a purely local call.
    05580 Parameters
    05581 stmtp (IN/OUT) - The statement handle to be released/freed.
    05582 errhp (IN) - an error handle to retrieve diagnostic information.
    05583 key (IN) - This is only Valid for OCI Stmt Caching. It indicates the
    05584            key to tag the stmt with.
    05585 key_len (IN) - the length of the key. This, too, is only valid for stmt
    05586                caching.
    05587 mode (IN) - the defined modes are OCI_DEFAULT for default mode and
    05588             OCI_STRLS_CACHE_DELETE (only used for Stmt Caching).
    05589 Example
    05590 Related Functions
    05591 OCIStmtExecute(), OCIStmtPrepare2()
    05592
    05593
    05594 OCIStmtSetPieceInfo()
    05595 Name
    05596 OCI Set Piece Information
    05597 Purpose
    05598 Sets piece information for a piecewise operation.
    05599 Syntax
    05600 sword OCIStmtSetPieceInfo ( dvoid             *hndlp,
    05601                           ub4               type,
    05602                           OCIError          *errhp,
    05603                           CONST dvoid       *bufp,
    05604                           ub4               *alenp,
    05605                           ub1               piece,
    05606                           CONST dvoid       *indp,
    05607                           ub2               *rcodep );
    05608 Comments
    05609 When an execute call returns OCI_NEED_DATA to get a dynamic IN/OUT
    05610 bind value or piece, OCIStmtSetPieceInfo() sets the piece information: the
    05611 buffer, the length, the indicator and which piece is currently being processed.
    05612 For more information about using OCIStmtSetPieceInfo() see the section
    05613 "Runtime Data Allocation and Piecewise Operations" on page 5-16.
    05614 Parameters
    05615 hndlp (IN/OUT) - the bind/define handle.
    05616 type (IN) - type of the handle.
    05617 errhp (OUT) - an error handle which can be passed to OCIErrorGet() for
    05618 diagnostic information in the event of an error.
    05619 bufp (IN/OUT) - bufp is a pointer to a storage containing the data value or
    05620 the piece when it is an IN bind variable, otherwise bufp is a pointer to
    05621 storage for getting a piece or a value for OUT binds and define variables. For
    05622 named data types or REFs, a pointer to the object or REF is returned.
    05623 alenp (IN/OUT) - the length of the piece or the value.
    05624 piece (IN) - the piece parameter. The following are valid values:
    05625 OCI_ONE_PIECE, OCI_FIRST_PIECE, OCI_NEXT_PIECE, or
    05626 OCI_LAST_PIECE.
    05627 The default value is OCI_ONE_PIECE. This parameter is used for IN bind
    05628 variables only.
    05629 indp (IN/OUT) - indicator. A pointer to a sb2 value or pointer to an indicator
    05630 structure for named data types (SQLT_NTY) and REFs (SQLT_REF), i.e., *indp
    05631 is either an sb2 or a dvoid * depending upon the data type.
    05632 rcodep (IN/OUT) - return code.
    05633 Related Functions
    05634 OCIAttrGet(), OCIAttrGet(), OCIStmtExecute(), OCIStmtFetch(),
    05635 OCIStmtGetPieceInfo()
    05636
    05637
    05638 OCIFormatInit
    05639 Name
    05640 OCIFormat Package Initialize
    05641 Purpose
    05642 Initializes the OCIFormat package.
    05643 Syntax
    05644 sword OCIFormatInit(dvoid *hndl, OCIError *err);
    05645 Comments
    05646 This routine must be called before calling any other OCIFormat routine.
    05647 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    05648 Parameters
    05649 hndl (IN/OUT) - OCI environment or session handle
    05650 err (IN/OUT) - OCI error handle
    05651 Related Functions
    05652 OCIFormatTerm()
    05653
    05654
    05655 OCIFormatString
    05656 Name
    05657 OCIFormat Package Format String
    05658 Purpose
    05659 Writes a text string into the supplied text buffer using the argument
    05660 list submitted to it and in accordance with the format string given.
    05661 Syntax
    05662 sword OCIFormatString(dvoid *hndl, OCIError *err, OraText *buffer,
    05663                       sbig_ora bufferLength, sbig_ora *returnLength,
    05664                       CONST OraText *formatString, ...);
    05665 Comments
    05666 The first call to this routine must be preceded by a call to the
    05667 OCIFormatInit routine that initializes the OCIFormat package
    05668 for use.  When this routine is no longer needed then terminate
    05669 the OCIFormat package by a call to the OCIFormatTerm routine.
    05670 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    05671 Parameters
    05672 hndl         (IN/OUT) - OCI environment or session handle
    05673 err          (IN/OUT) - OCI error handle
    05674 buffer       (OUT)    - text buffer for the string
    05675 bufferLength (IN)     - length of the text buffer
    05676 returnLength (OUT)    - length of the formatted string
    05677 formatString (IN)     - format specification string
    05678 ...          (IN)     - variable argument list
    05679 Related Functions
    05680
    05681
    05682 OCIFormatTerm
    05683 Name
    05684 OCIFormat Package Terminate
    05685 Purpose
    05686 Terminates the OCIFormat package.
    05687 Syntax
    05688 sword OCIFormatTerm(dvoid *hndl, OCIError *err);
    05689 Comments
    05690 It must be called after the OCIFormat package is no longer being used.
    05691 Returns OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    05692 Parameters
    05693 hndl (IN/OUT) - OCI environment or session handle
    05694 err (IN/OUT) - OCI error handle
    05695 Related Functions
    05696 OCIFormatInit()
    05697
    05698
    05699 OCIFormatTUb1
    05700 Name
    05701 OCIFormat Package ub1 Type
    05702 Purpose
    05703 Return the type value for the ub1 type.
    05704 Syntax
    05705 sword OCIFormatTUb1(void);
    05706 Comments
    05707 None
    05708 Parameters
    05709 None
    05710 Related Functions
    05711 None
    05712
    05713
    05714 OCIFormatTUb2
    05715 Name
    05716 OCIFormat Package ub2 Type
    05717 Purpose
    05718 Return the type value for the ub2 type.
    05719 Syntax
    05720 sword OCIFormatTUb2(void);
    05721 Comments
    05722 None
    05723 Parameters
    05724 None
    05725 Related Functions
    05726 None
    05727
    05728
    05729 OCIFormatTUb4
    05730 Name
    05731 OCIFormat Package ub4 Type
    05732 Purpose
    05733 Return the type value for the ub4 type.
    05734 Syntax
    05735 sword OCIFormatTUb4(void);
    05736 Comments
    05737 None
    05738 Parameters
    05739 None
    05740 Related Functions
    05741 None
    05742
    05743
    05744 OCIFormatTUword
    05745 Name
    05746 OCIFormat Package uword Type
    05747 Purpose
    05748 Return the type value for the uword type.
    05749 Syntax
    05750 sword OCIFormatTUword(void);
    05751 Comments
    05752 None
    05753 Parameters
    05754 None
    05755 Related Functions
    05756 None
    05757
    05758
    05759 OCIFormatTUbig_ora
    05760 Name
    05761 OCIFormat Package ubig_ora Type
    05762 Purpose
    05763 Return the type value for the ubig_ora type.
    05764 Syntax
    05765 sword OCIFormatTUbig_ora(void);
    05766 Comments
    05767 None
    05768 Parameters
    05769 None
    05770 Related Functions
    05771 None
    05772
    05773
    05774 OCIFormatTSb1
    05775 Name
    05776 OCIFormat Package sb1 Type
    05777 Purpose
    05778 Return the type value for the sb1 type.
    05779 Syntax
    05780 sword OCIFormatTSb1(void);
    05781 Comments
    05782 None
    05783 Parameters
    05784 None
    05785 Related Functions
    05786 None
    05787
    05788
    05789 OCIFormatTSb2
    05790 Name
    05791 OCIFormat Package sb2 Type
    05792 Purpose
    05793 Return the type value for the sb2 type.
    05794 Syntax
    05795 sword OCIFormatTSb2(void);
    05796 Comments
    05797 None
    05798 Parameters
    05799 None
    05800 Related Functions
    05801 None
    05802
    05803
    05804 OCIFormatTSb4
    05805 Name
    05806 OCIFormat Package sb4 Type
    05807 Purpose
    05808 Return the type value for the sb4 type.
    05809 Syntax
    05810 sword OCIFormatTSb4(void);
    05811 Comments
    05812 None
    05813 Parameters
    05814 None
    05815 Related Functions
    05816 None
    05817
    05818
    05819 OCIFormatTSword
    05820 Name
    05821 OCIFormat Package sword Type
    05822 Purpose
    05823 Return the type value for the sword type.
    05824 Syntax
    05825 sword OCIFormatTSword(void);
    05826 Comments
    05827 None
    05828 Parameters
    05829 None
    05830 Related Functions
    05831 None
    05832
    05833
    05834 OCIFormatTSbig_ora
    05835 Name
    05836 OCIFormat Package sbig_ora Type
    05837 Purpose
    05838 Return the type value for the sbig_ora type.
    05839 Syntax
    05840 sword OCIFormatTSbig_ora(void);
    05841 Comments
    05842 None
    05843 Parameters
    05844 None
    05845 Related Functions
    05846 None
    05847
    05848
    05849 OCIFormatTEb1
    05850 Name
    05851 OCIFormat Package eb1 Type
    05852 Purpose
    05853 Return the type value for the eb1 type.
    05854 Syntax
    05855 sword OCIFormatTEb1(void);
    05856 Comments
    05857 None
    05858 Parameters
    05859 None
    05860 Related Functions
    05861 None
    05862
    05863
    05864 OCIFormatTEb2
    05865 Name
    05866 OCIFormat Package eb2 Type
    05867 Purpose
    05868 Return the type value for the eb2 type.
    05869 Syntax
    05870 sword OCIFormatTEb2(void);
    05871 Comments
    05872 None
    05873 Parameters
    05874 None
    05875 Related Functions
    05876 None
    05877
    05878
    05879 OCIFormatTEb4
    05880 Name
    05881 OCIFormat Package eb4 Type
    05882 Purpose
    05883 Return the type value for the eb4 type.
    05884 Syntax
    05885 sword OCIFormatTEb4(void);
    05886 Comments
    05887 None
    05888 Parameters
    05889 None
    05890 Related Functions
    05891 None
    05892
    05893
    05894 OCIFormatTEword
    05895 Name
    05896 OCIFormat Package eword Type
    05897 Purpose
    05898 Return the type value for the eword type.
    05899 Syntax
    05900 sword OCIFormatTEword(void);
    05901 Comments
    05902 None
    05903 Parameters
    05904 None
    05905 Related Functions
    05906 None
    05907
    05908
    05909 OCIFormatTChar
    05910 Name
    05911 OCIFormat Package text Type
    05912 Purpose
    05913 Return the type value for the text type.
    05914 Syntax
    05915 sword OCIFormatTChar(void);
    05916 Comments
    05917 None
    05918 Parameters
    05919 None
    05920 Related Functions
    05921 None
    05922
    05923
    05924 OCIFormatTText
    05925 Name
    05926 OCIFormat Package *text Type
    05927 Purpose
    05928 Return the type value for the *text type.
    05929 Syntax
    05930 sword OCIFormatTText(void);
    05931 Comments
    05932 None
    05933 Parameters
    05934 None
    05935 Related Functions
    05936 None
    05937
    05938
    05939 OCIFormatTDouble
    05940 Name
    05941 OCIFormat Package double Type
    05942 Purpose
    05943 Return the type value for the double type.
    05944 Syntax
    05945 sword OCIFormatTDouble(void);
    05946 Comments
    05947 None
    05948 Parameters
    05949 None
    05950 Related Functions
    05951 None
    05952
    05953
    05954 OCIFormatDvoid
    05955 Name
    05956 OCIFormat Package dvoid Type
    05957 Purpose
    05958 Return the type value for the dvoid type.
    05959 Syntax
    05960 sword OCIFormatTDvoid(void);
    05961 Comments
    05962 None
    05963 Parameters
    05964 None
    05965 Related Functions
    05966 None
    05967
    05968
    05969 OCIFormatTEnd
    05970 Name
    05971 OCIFormat Package end Type
    05972 Purpose
    05973 Return the list terminator's "type".
    05974 Syntax
    05975 sword OCIFormatTEnd(void);
    05976 Comments
    05977 None
    05978 Parameters
    05979 None
    05980 Related Functions
    05981 None
    05982
    05983
    05984 OCISvcCtxToLda()
    05985 Name
    05986 OCI toggle SerVice context handle to Version 7 Lda_Def
    05987 Purpose
    05988 Toggles between a V8 service context handle and a V7 Lda_Def.
    05989 Syntax
    05990 sword OCISvcCtxToLda ( OCISvcCtx    *srvhp,
    05991                      OCIError     *errhp,
    05992                      Lda_Def      *ldap );
    05993 Comments
    05994 Toggles between an Oracle8 service context handle and an Oracle7 Lda_Def.
    05995 This function can only be called after a service context has been properly
    05996 initialized.
    05997 Once the service context has been translated to an Lda_Def, it can be used in
    05998 release 7.x OCI calls (e.g., obindps(), ofen()).
    05999 Note: If there are multiple service contexts which share the same server
    06000 handle, only one can be in V7 mode at any time.
    06001 The action of this call can be reversed by passing the resulting Lda_Def to
    06002 the OCILdaToSvcCtx() function.
    06003 Parameters
    06004 svchp (IN/OUT) - the service context handle.
    06005 errhp (IN/OUT) - an error handle which can be passed to OCIErrorGet() for
    06006 diagnostic information in the event of an error.
    06007 ldap (IN/OUT) - a Logon Data Area for V7-style OCI calls which is initialized
    06008 by this call.
    06009 Related Functions
    06010 OCILdaToSvcCtx()
    06011
    06012
    06013
    06014
    06015 OCITransCommit()
    06016 Name
    06017 OCI TX (transaction) CoMmit
    06018 Purpose
    06019 Commits the transaction associated with a specified service context.
    06020 Syntax
    06021 sword OCITransCommit ( OCISvcCtx    *srvcp,
    06022                      OCIError     *errhp,
    06023                      ub4          flags );
    06024 Comments
    06025 The transaction currently associated with the service context is committed. If
    06026 it is a distributed transaction that the server cannot commit, this call
    06027 additionally retrieves the state of the transaction from the database to be
    06028 returned to the user in the error handle.
    06029 If the application has defined multiple transactions, this function operates
    06030 on the transaction currently associated with the service context. If the
    06031 application is working with only the implicit local transaction created when
    06032 database changes are made, that implicit transaction is committed.
    06033 If the application is running in the object mode, then the modified or updated
    06034 objects in the object cache for this transaction are also committed.
    06035 The flags parameter is used for one-phase commit optimization in distributed
    06036 transactions. If the transaction is non-distributed, the flags parameter is
    06037 ignored, and OCI_DEFAULT can be passed as its value. OCI applications
    06038 managing global transactions should pass a value of
    06039 OCI_TRANS_TWOPHASE to the flags parameter for a two-phase commit. The
    06040 default is one-phase commit.
    06041 Under normal circumstances, OCITransCommit() returns with a status
    06042 indicating that the transaction has either been committed or rolled back. With
    06043 distributed transactions, it is possible that the transaction is now in-doubt
    06044 (i.e., neither committed nor aborted). In this case, OCITransCommit()
    06045 attempts to retrieve the status of the transaction from the server.
    06046 The status is returned.
    06047 Parameters
    06048 srvcp (IN) - the service context handle.
    06049 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    06050 diagnostic information in the event of an error.
    06051 flags -see the "Comments" section above.
    06052 Related Functions
    06053 OCITransRollback()
    06054
    06055
    06056
    06057
    06058 OCITransDetach()
    06059 Name
    06060 OCI TX (transaction) DeTach
    06061 Purpose
    06062 Detaches a transaction.
    06063 Syntax
    06064 sword OCITransDetach ( OCISvcCtx    *srvcp,
    06065                      OCIError     *errhp,
    06066                      ub4          flags);
    06067 Comments
    06068 Detaches a global transaction from the service context handle. The transaction
    06069 currently attached to the service context handle becomes inactive at the end
    06070 of this call. The transaction may be resumed later by calling OCITransStart(),
    06071 specifying  a flags value of OCI_TRANS_RESUME.
    06072 When a transaction is detached, the value which was specified in the timeout
    06073 parameter of OCITransStart() when the transaction was started is used to
    06074 determine the amount of time the branch can remain inactive before being
    06075 deleted by the server's PMON process.
    06076 Note: The transaction can be resumed by a different process than the one
    06077 that detached it, provided that the transaction has the same
    06078 authorization.
    06079 Parameters
    06080 srvcp (IN) - the service context handle.
    06081 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    06082 diagnostic information in the event of an error.
    06083 flags (IN) - you must pass a value of OCI_DEFAULT for this parameter.
    06084 Related Functions
    06085 OCITransStart()
    06086
    06087
    06088
    06089 OCITransForget()
    06090 Name
    06091 OCI TX (transaction) ForGeT
    06092 Purpose
    06093 Causes the server to forget a heuristically completed global transaction.
    06094 Syntax
    06095 sword OCITransForget ( OCISvcCtx     *svchp,
    06096                      OCIError      *errhp,
    06097                      ub4           flags);
    06098
    06099 Comments
    06100
    06101 Forgets a heuristically completed global transaction. The server deletes the
    06102 status of the transaction from the system's pending transaction table.
    06103 The XID of the transaction to be forgotten is set as an attribute of the
    06104 transaction handle (OCI_ATTR_XID).
    06105 Parameters
    06106 srvcp (IN) - the service context handle - the transaction is rolled back.
    06107 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    06108 diagnostic information in the event of an error.
    06109 flags (IN) - you must pass OCI_DEFAULT for this parameter.
    06110 Related Functions
    06111 OCITransCommit(), OCITransRollback()
    06112
    06113
    06114 OCITransMultiPrepare()
    06115 Name
    06116 OCI Trans(action) Multi-Branch Prepare
    06117 Purpose
    06118 Prepares a transaction with multiple branches in a single call.
    06119 Syntax
    06120 sword OCITransMultiPrepare ( OCISvcCtx    *svchp,
    06121                              ub4           numBranches,
    06122                              OCITrans     **txns,
    06123                              OCIError     **errhp);
    06124
    06125 Comments
    06126
    06127 Prepares the specified global transaction for commit.
    06128 This call is valid only for distributed transactions.
    06129 This call is an advanced performance feature intended for use only in
    06130 situations where the caller is responsible for preparing all the branches
    06131 in a transaction.
    06132 Parameters
    06133 srvcp (IN) - the service context handle.
    06134 numBranches (IN) - This is the number of branches expected. It is also the
    06135 array size for the next two parameters.
    06136 txns (IN) - This is the array of transaction handles for the branches to
    06137 prepare. They should all have the OCI_ATTR_XID set. The global transaction
    06138 ID should be the same.
    06139 errhp (IN) - This is the array of error handles. If OCI_SUCCESS is not
    06140 returned, then these will indicate which branches received which errors.
    06141 Related Functions
    06142 OCITransPrepare()
    06143
    06144
    06145 OCITransPrepare()
    06146 Name
    06147 OCI TX (transaction) PREpare
    06148 Purpose
    06149 Prepares a transaction for commit.
    06150 Syntax
    06151 sword OCITransPrepare ( OCISvcCtx    *svchp,
    06152                       OCIError     *errhp,
    06153                       ub4          flags);
    06154
    06155 Comments
    06156
    06157 Prepares the specified global transaction for commit.
    06158 This call is valid only for distributed transactions.
    06159 The call returns OCI_SUCCESS_WITH_INFO if the transaction has not made
    06160 any changes. The error handle will indicate that the transaction is read-only.
    06161 The flag parameter is not currently used.
    06162 Parameters
    06163 srvcp (IN) - the service context handle.
    06164 errhp (IN) - an error handle which can be passed to OCIErrorGet() for
    06165 diagnostic information in the event of an error.
    06166 flags (IN) - you must pass OCI_DEFAULT for this parameter.
    06167 Related Functions
    06168 OCITransCommit(), OCITransForget()
    06169
    06170
    06171
    06172
    06173 OCITransRollback()
    06174 Name
    06175 OCI TX (transaction) RoLlback
    06176 Purpose
    06177 Rolls back the current transaction.
    06178 Syntax
    06179 sword OCITransRollback ( dvoid        *svchp,
    06180                        OCIError     *errhp,
    06181                        ub4          flags );
    06182 Comments
    06183 The current transaction- defined as the set of statements executed since the
    06184 last OCITransCommit() or since OCISessionBegin()-is rolled back.
    06185 If the application is running under object mode then the modified or updated
    06186 objects in the object cache for this transaction are also rolled back.
    06187 An error is returned if an attempt is made to roll back a global transaction
    06188 that is not currently active.
    06189 Parameters
    06190 svchp (IN) - a service context handle. The transaction currently set in the
    06191 service context handle is rolled back.
    06192 errhp -(IN) - an error handle which can be passed to OCIErrorGet() for
    06193 diagnostic information in the event of an error.
    06194 flags - you must pass a value of OCI_DEFAULT for this parameter.
    06195 Related Functions
    06196 OCITransCommit()
    06197
    06198
    06199
    06200
    06201 OCITransStart()
    06202 Name
    06203 OCI TX (transaction) STart
    06204 Purpose
    06205 Sets the beginning of a transaction.
    06206 Syntax
    06207 sword OCITransStart ( OCISvcCtx    *svchp,
    06208                     OCIError     *errhp,
    06209                     uword        timeout,
    06210                     ub4          flags);
    06211
    06212 Comments
    06213 This function sets the beginning of a global or serializable transaction. The
    06214 transaction context currently associated with the service context handle is
    06215 initialized at the end of the call if the flags parameter specifies that a new
    06216 transaction should be started.
    06217 The XID of the transaction is set as an attribute of the transaction handle
    06218 (OCI_ATTR_XID)
    06219 Parameters
    06220 svchp (IN/OUT) - the service context handle. The transaction context in the
    06221 service context handle is initialized at the end of the call if the flag
    06222 specified a new transaction to be started.
    06223 errhp (IN/OUT) - The OCI error handle. If there is an error, it is recorded in
    06224 err and this function returns OCI_ERROR. Diagnostic information can be
    06225 obtained by calling OCIErrorGet().
    06226 timeout (IN) - the time, in seconds, to wait for a transaction to become
    06227 available for resumption when OCI_TRANS_RESUME is specified. When
    06228 OCI_TRANS_NEW is specified, this value is stored and may be used later by
    06229 OCITransDetach().
    06230 flags (IN) - specifies whether a new transaction is being started or an
    06231 existing transaction is being resumed. Also specifies serializiability or
    06232 read-only status. More than a single value can be specified. By default,
    06233 a read/write transaction is started. The flag values are:
    06234 OCI_TRANS_NEW - starts a new transaction branch. By default starts a
    06235 tightly coupled and migratable branch.
    06236 OCI_TRANS_TIGHT - explicitly specifies a tightly coupled branch
    06237 OCI_TRANS_LOOSE - specifies a loosely coupled branch
    06238 OCI_TRANS_RESUME - resumes an existing transaction branch.
    06239 OCI_TRANS_READONLY - start a readonly transaction
    06240 OCI_TRANS_SERIALIZABLE - start a serializable transaction
    06241 Related Functions
    06242 OCITransDetach()
    06243
    06244
    06245
    06246
    06247
    06248 ******************************************************************************/
    06249 /*-----------------------Dynamic Callback Function Pointers------------------*/
    06250
    06251
    06252 typedef sb4 (*OCICallbackInBind)(dvoid *ictxp, OCIBind *bindp, ub4 iter,
    06253                                   ub4 index, dvoid **bufpp, ub4 *alenp,
    06254                                   ub1 *piecep, dvoid **indp);
    06255
    06256 typedef sb4 (*OCICallbackOutBind)(dvoid *octxp, OCIBind *bindp, ub4 iter,
    06257                                  ub4 index, dvoid **bufpp, ub4 **alenp,
    06258                                  ub1 *piecep, dvoid **indp,
    06259                                  ub2 **rcodep);
    06260
    06261 typedef sb4 (*OCICallbackDefine)(dvoid *octxp, OCIDefine *defnp, ub4 iter,
    06262                                  dvoid **bufpp, ub4 **alenp, ub1 *piecep,
    06263                                  dvoid **indp, ub2 **rcodep);
    06264
    06265 typedef sword (*OCIUserCallback)(dvoid *ctxp, dvoid *hndlp, ub4 type,
    06266                                  ub4 fcode, ub4 when, sword returnCode,
    06267                                  sb4 *errnop, va_list arglist);
    06268
    06269 typedef sword (*OCIEnvCallbackType)(OCIEnv *env, ub4 mode,
    06270                                    size_t xtramem_sz, dvoid *usrmemp,
    06271                                    OCIUcb *ucbDesc);
    06272
    06273 typedef sb4 (*OCICallbackLobRead)(dvoid *ctxp, CONST dvoid *bufp,
    06274                                              ub4 len, ub1 piece);
    06275
    06276 typedef sb4 (*OCICallbackLobWrite)(dvoid *ctxp, dvoid *bufp,
    06277                                           ub4 *lenp, ub1 *piece);
    06278
    06279 #ifdef ORAXB8_DEFINED
    06280
    06281 typedef sb4 (*OCICallbackLobRead2)(dvoid *ctxp, CONST dvoid *bufp, oraub8 len,
    06282                                    ub1 piece, dvoid **changed_bufpp,
    06283                                    oraub8 *changed_lenp);
    06284
    06285 typedef sb4 (*OCICallbackLobWrite2)(dvoid *ctxp, dvoid *bufp, oraub8 *lenp,
    06286                                     ub1 *piece, dvoid **changed_bufpp,
    06287                                     oraub8 *changed_lenp);
    06288 #endif
    06289
    06290 typedef sb4 (*OCICallbackAQEnq)(dvoid *ctxp, dvoid **payload,
    06291                                 dvoid **payload_ind);
    06292
    06293 typedef sb4 (*OCICallbackAQDeq)(dvoid *ctxp, dvoid **payload,
    06294                                 dvoid **payload_ind);
    06295
    06296 /*--------------------------Failover Callback Structure ---------------------*/
    06297 typedef sb4 (*OCICallbackFailover)(dvoid *svcctx, dvoid *envctx,
    06298                                    dvoid *fo_ctx, ub4 fo_type,
    06299                                    ub4 fo_event);
    06300
    06301 typedef struct
    06302 {
    06303   OCICallbackFailover callback_function;
    06304   dvoid *fo_ctx;
    06305 }
    06306 OCIFocbkStruct;
    06307
    06308 /*****************************************************************************
    06309                          ACTUAL PROTOTYPE DECLARATIONS
    06310 ******************************************************************************/
    06311
    06312 sword   OCIInitialize   (ub4 mode, dvoid *ctxp,
    06313                  dvoid *(*malocfp)(dvoid *ctxp, size_t size),
    06314                  dvoid *(*ralocfp)(dvoid *ctxp, dvoid *memptr, size_t newsize),
    06315                  void   (*mfreefp)(dvoid *ctxp, dvoid *memptr) );
    06316
    06317 sword   OCITerminate( ub4 mode);
    06318
    06319 sword   OCIEnvCreate (OCIEnv **envp, ub4 mode, dvoid *ctxp,
    06320                  dvoid *(*malocfp)(dvoid *ctxp, size_t size),
    06321                  dvoid *(*ralocfp)(dvoid *ctxp, dvoid *memptr, size_t newsize),
    06322                  void   (*mfreefp)(dvoid *ctxp, dvoid *memptr),
    06323                  size_t xtramem_sz, dvoid **usrmempp);
    06324
    06325 sword   OCIEnvNlsCreate (OCIEnv **envp, ub4 mode, dvoid *ctxp,
    06326                  dvoid *(*malocfp)(dvoid *ctxp, size_t size),
    06327                  dvoid *(*ralocfp)(dvoid *ctxp, dvoid *memptr, size_t newsize),
    06328                  void   (*mfreefp)(dvoid *ctxp, dvoid *memptr),
    06329                  size_t xtramem_sz, dvoid **usrmempp,
    06330                  ub2 charset, ub2 ncharset);
    06331
    06332 sword   OCIFEnvCreate (OCIEnv **envp, ub4 mode, dvoid *ctxp,
    06333                  dvoid *(*malocfp)(dvoid *ctxp, size_t size),
    06334                  dvoid *(*ralocfp)(dvoid *ctxp, dvoid *memptr, size_t newsize),
    06335                  void   (*mfreefp)(dvoid *ctxp, dvoid *memptr),
    06336                  size_t xtramem_sz, dvoid **usrmempp, dvoid *fupg);
    06337
    06338 sword   OCIHandleAlloc(CONST dvoid *parenth, dvoid **hndlpp, CONST ub4 type,
    06339                        CONST size_t xtramem_sz, dvoid **usrmempp);
    06340
    06341 sword   OCIHandleFree(dvoid *hndlp, CONST ub4 type);
    06342
    06343
    06344 sword   OCIDescriptorAlloc(CONST dvoid *parenth, dvoid **descpp,
    06345                            CONST ub4 type, CONST size_t xtramem_sz,
    06346                            dvoid **usrmempp);
    06347
    06348 sword   OCIDescriptorFree(dvoid *descp, CONST ub4 type);
    06349
    06350 sword   OCIEnvInit (OCIEnv **envp, ub4 mode,
    06351                     size_t xtramem_sz, dvoid **usrmempp);
    06352
    06353 sword   OCIServerAttach  (OCIServer *srvhp, OCIError *errhp,
    06354                           CONST OraText *dblink, sb4 dblink_len, ub4 mode);
    06355
    06356 sword   OCIServerDetach  (OCIServer *srvhp, OCIError *errhp, ub4 mode);
    06357
    06358 sword   OCISessionBegin  (OCISvcCtx *svchp, OCIError *errhp, OCISession *usrhp,
    06359                           ub4 credt, ub4 mode);
    06360
    06361 sword   OCISessionEnd   (OCISvcCtx *svchp, OCIError *errhp, OCISession *usrhp,
    06362                          ub4 mode);
    06363
    06364 sword   OCILogon (OCIEnv *envhp, OCIError *errhp, OCISvcCtx **svchp,
    06365                   CONST OraText *username, ub4 uname_len,
    06366                   CONST OraText *password, ub4 passwd_len,
    06367                   CONST OraText *dbname, ub4 dbname_len);
    06368
    06369 sword   OCILogon2 (OCIEnv *envhp, OCIError *errhp, OCISvcCtx **svchp,
    06370                   CONST OraText *username, ub4 uname_len,
    06371                   CONST OraText *password, ub4 passwd_len,
    06372                   CONST OraText *dbname, ub4 dbname_len,
    06373                   ub4 mode);
    06374
    06375 sword   OCILogoff (OCISvcCtx *svchp, OCIError *errhp);
    06376
    06377
    06378 sword   OCIPasswordChange   (OCISvcCtx *svchp, OCIError *errhp,
    06379                              CONST OraText *user_name, ub4 usernm_len,
    06380                              CONST OraText *opasswd, ub4 opasswd_len,
    06381                              CONST OraText *npasswd, ub4 npasswd_len,
    06382                              ub4 mode);
    06383
    06384 sword   OCIStmtPrepare   (OCIStmt *stmtp, OCIError *errhp, CONST OraText *stmt,
    06385                           ub4 stmt_len, ub4 language, ub4 mode);
    06386
    06387 sword OCIStmtPrepare2 ( OCISvcCtx *svchp, OCIStmt **stmtp, OCIError *errhp,
    06388                      CONST OraText *stmt, ub4 stmt_len, CONST OraText *key,
    06389                      ub4 key_len, ub4 language, ub4 mode);
    06390
    06391 sword OCIStmtRelease ( OCIStmt *stmtp, OCIError *errhp, CONST OraText *key,
    06392                        ub4 key_len, ub4 mode);
    06393
    06394 sword   OCIBindByPos  (OCIStmt *stmtp, OCIBind **bindp, OCIError *errhp,
    06395                        ub4 position, dvoid *valuep, sb4 value_sz,
    06396                        ub2 dty, dvoid *indp, ub2 *alenp, ub2 *rcodep,
    06397                        ub4 maxarr_len, ub4 *curelep, ub4 mode);
    06398
    06399 sword   OCIBindByName   (OCIStmt *stmtp, OCIBind **bindp, OCIError *errhp,
    06400                          CONST OraText *placeholder, sb4 placeh_len,
    06401                          dvoid *valuep, sb4 value_sz, ub2 dty,
    06402                          dvoid *indp, ub2 *alenp, ub2 *rcodep,
    06403                          ub4 maxarr_len, ub4 *curelep, ub4 mode);
    06404
    06405 sword   OCIBindObject  (OCIBind *bindp, OCIError *errhp, CONST OCIType *type,
    06406                         dvoid **pgvpp, ub4 *pvszsp, dvoid **indpp,
    06407                         ub4 *indszp);
    06408
    06409 sword   OCIBindDynamic   (OCIBind *bindp, OCIError *errhp, dvoid *ictxp,
    06410                           OCICallbackInBind icbfp, dvoid *octxp,
    06411                           OCICallbackOutBind ocbfp);
    06412
    06413 sword   OCIBindArrayOfStruct   (OCIBind *bindp, OCIError *errhp,
    06414                                 ub4 pvskip, ub4 indskip,
    06415                                 ub4 alskip, ub4 rcskip);
    06416
    06417 sword   OCIStmtGetPieceInfo   (OCIStmt *stmtp, OCIError *errhp,
    06418                                dvoid **hndlpp, ub4 *typep,
    06419                                ub1 *in_outp, ub4 *iterp, ub4 *idxp,
    06420                                ub1 *piecep);
    06421
    06422 sword   OCIStmtSetPieceInfo   (dvoid *hndlp, ub4 type, OCIError *errhp,
    06423                                CONST dvoid *bufp, ub4 *alenp, ub1 piece,
    06424                                CONST dvoid *indp, ub2 *rcodep);
    06425
    06426 sword   OCIStmtExecute  (OCISvcCtx *svchp, OCIStmt *stmtp, OCIError *errhp,
    06427                          ub4 iters, ub4 rowoff, CONST OCISnapshot *snap_in,
    06428                          OCISnapshot *snap_out, ub4 mode);
    06429
    06430 sword   OCIDefineByPos  (OCIStmt *stmtp, OCIDefine **defnp, OCIError *errhp,
    06431                          ub4 position, dvoid *valuep, sb4 value_sz, ub2 dty,
    06432                          dvoid *indp, ub2 *rlenp, ub2 *rcodep, ub4 mode);
    06433
    06434 sword   OCIDefineObject  (OCIDefine *defnp, OCIError *errhp,
    06435                           CONST OCIType *type, dvoid **pgvpp,
    06436                           ub4 *pvszsp, dvoid **indpp, ub4 *indszp);
    06437
    06438 sword   OCIDefineDynamic   (OCIDefine *defnp, OCIError *errhp, dvoid *octxp,
    06439                             OCICallbackDefine ocbfp);
    06440
    06441 sword   OCIRowidToChar  (OCIRowid *rowidDesc, OraText *outbfp, ub2 *outbflp,
    06442                          OCIError *errhp);
    06443
    06444 sword   OCIDefineArrayOfStruct  (OCIDefine *defnp, OCIError *errhp, ub4 pvskip,
    06445                                  ub4 indskip, ub4 rlskip, ub4 rcskip);
    06446
    06447 sword   OCIStmtFetch   (OCIStmt *stmtp, OCIError *errhp, ub4 nrows,
    06448                         ub2 orientation, ub4 mode);
    06449
    06450 sword   OCIStmtFetch2   (OCIStmt *stmtp, OCIError *errhp, ub4 nrows,
    06451                         ub2 orientation, sb4 scrollOffset, ub4 mode);
    06452
    06453 sword   OCIStmtGetBindInfo   (OCIStmt *stmtp, OCIError *errhp, ub4 size,
    06454                               ub4 startloc,
    06455                               sb4 *found, OraText *bvnp[], ub1 bvnl[],
    06456                               OraText *invp[], ub1 inpl[], ub1 dupl[],
    06457                               OCIBind **hndl);
    06458
    06459 sword   OCIDescribeAny  (OCISvcCtx *svchp, OCIError *errhp,
    06460                          dvoid *objptr,
    06461                          ub4 objnm_len, ub1 objptr_typ, ub1 info_level,
    06462                          ub1 objtyp, OCIDescribe *dschp);
    06463
    06464 sword   OCIParamGet (CONST dvoid *hndlp, ub4 htype, OCIError *errhp,
    06465                      dvoid **parmdpp, ub4 pos);
    06466
    06467 sword   OCIParamSet(dvoid *hdlp, ub4 htyp, OCIError *errhp, CONST dvoid *dscp,
    06468                     ub4 dtyp, ub4 pos);
    06469
    06470 sword   OCITransStart  (OCISvcCtx *svchp, OCIError *errhp,
    06471                         uword timeout, ub4 flags );
    06472
    06473 sword   OCITransDetach  (OCISvcCtx *svchp, OCIError *errhp, ub4 flags );
    06474
    06475 sword   OCITransCommit  (OCISvcCtx *svchp, OCIError *errhp, ub4 flags);
    06476
    06477 sword   OCITransRollback  (OCISvcCtx *svchp, OCIError *errhp, ub4 flags);
    06478
    06479 sword   OCITransPrepare (OCISvcCtx *svchp, OCIError *errhp, ub4 flags);
    06480
    06481 sword   OCITransMultiPrepare (OCISvcCtx *svchp, ub4 numBranches,
    06482                               OCITrans **txns, OCIError **errhp);
    06483
    06484 sword   OCITransForget (OCISvcCtx *svchp, OCIError *errhp, ub4 flags);
    06485
    06486 sword   OCIErrorGet   (dvoid *hndlp, ub4 recordno, OraText *sqlstate,
    06487                        sb4 *errcodep, OraText *bufp, ub4 bufsiz, ub4 type);
    06488
    06489 sword   OCILobAppend  (OCISvcCtx *svchp, OCIError *errhp,
    06490                        OCILobLocator *dst_locp,
    06491                        OCILobLocator *src_locp);
    06492
    06493 sword   OCILobAssign (OCIEnv *envhp, OCIError *errhp,
    06494                       CONST OCILobLocator *src_locp,
    06495                       OCILobLocator **dst_locpp);
    06496
    06497 sword   OCILobCharSetForm (OCIEnv *envhp, OCIError *errhp,
    06498                            CONST OCILobLocator *locp, ub1 *csfrm);
    06499
    06500 sword   OCILobCharSetId (OCIEnv *envhp, OCIError *errhp,
    06501                          CONST OCILobLocator *locp, ub2 *csid);
    06502
    06503 sword   OCILobCopy (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *dst_locp,
    06504                     OCILobLocator *src_locp, ub4 amount, ub4 dst_offset,
    06505                     ub4 src_offset);
    06506
    06507 sword OCILobCreateTemporary(OCISvcCtx          *svchp,
    06508                             OCIError           *errhp,
    06509                             OCILobLocator      *locp,
    06510                             ub2                 csid,
    06511                             ub1                 csfrm,
    06512                             ub1                 lobtype,
    06513                             boolean             cache,
    06514                             OCIDuration         duration);
    06515
    06516
    06517 sword OCILobClose( OCISvcCtx        *svchp,
    06518                    OCIError         *errhp,
    06519                    OCILobLocator    *locp );
    06520
    06521
    06522 sword   OCILobDisableBuffering (OCISvcCtx      *svchp,
    06523                                 OCIError       *errhp,
    06524                                 OCILobLocator  *locp);
    06525
    06526 sword   OCILobEnableBuffering (OCISvcCtx      *svchp,
    06527                                OCIError       *errhp,
    06528                                OCILobLocator  *locp);
    06529
    06530 sword   OCILobErase (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
    06531                       ub4 *amount, ub4 offset);
    06532
    06533 sword   OCILobFileClose (OCISvcCtx *svchp, OCIError *errhp,
    06534                          OCILobLocator *filep);
    06535
    06536 sword   OCILobFileCloseAll (OCISvcCtx *svchp, OCIError *errhp);
    06537
    06538 sword   OCILobFileExists (OCISvcCtx *svchp, OCIError *errhp,
    06539                           OCILobLocator *filep,
    06540                           boolean *flag);
    06541
    06542 sword   OCILobFileGetName (OCIEnv *envhp, OCIError *errhp,
    06543                            CONST OCILobLocator *filep,
    06544                            OraText *dir_alias, ub2 *d_length,
    06545                            OraText *filename, ub2 *f_length);
    06546
    06547 sword   OCILobFileIsOpen (OCISvcCtx *svchp, OCIError *errhp,
    06548                           OCILobLocator *filep,
    06549                           boolean *flag);
    06550
    06551 sword   OCILobFileOpen (OCISvcCtx *svchp, OCIError *errhp,
    06552                         OCILobLocator *filep,
    06553                         ub1 mode);
    06554
    06555 sword   OCILobFileSetName (OCIEnv *envhp, OCIError *errhp,
    06556                            OCILobLocator **filepp,
    06557                            CONST OraText *dir_alias, ub2 d_length,
    06558                            CONST OraText *filename, ub2 f_length);
    06559
    06560 sword   OCILobFlushBuffer (OCISvcCtx       *svchp,
    06561                            OCIError        *errhp,
    06562                            OCILobLocator   *locp,
    06563                            ub4              flag);
    06564
    06565 sword OCILobFreeTemporary(OCISvcCtx          *svchp,
    06566                           OCIError           *errhp,
    06567                           OCILobLocator      *locp);
    06568
    06569 sword OCILobGetChunkSize(OCISvcCtx         *svchp,
    06570                          OCIError          *errhp,
    06571                          OCILobLocator     *locp,
    06572                          ub4               *chunksizep);
    06573
    06574 sword   OCILobGetLength  (OCISvcCtx *svchp, OCIError *errhp,
    06575                           OCILobLocator *locp,
    06576                           ub4 *lenp);
    06577
    06578 sword   OCILobIsEqual  (OCIEnv *envhp, CONST OCILobLocator *x,
    06579                         CONST OCILobLocator *y,
    06580                         boolean *is_equal);
    06581
    06582 sword OCILobIsOpen( OCISvcCtx     *svchp,
    06583                     OCIError      *errhp,
    06584                     OCILobLocator *locp,
    06585                     boolean       *flag);
    06586
    06587 sword OCILobIsTemporary(OCIEnv            *envp,
    06588                         OCIError          *errhp,
    06589                         OCILobLocator     *locp,
    06590                         boolean           *is_temporary);
    06591
    06592 sword   OCILobLoadFromFile (OCISvcCtx *svchp, OCIError *errhp,
    06593                             OCILobLocator *dst_locp,
    06594                             OCILobLocator *src_filep,
    06595                             ub4 amount, ub4 dst_offset,
    06596                             ub4 src_offset);
    06597
    06598 sword   OCILobLocatorAssign  (OCISvcCtx *svchp, OCIError *errhp,
    06599                             CONST OCILobLocator *src_locp,
    06600                             OCILobLocator **dst_locpp);
    06601
    06602
    06603 sword   OCILobLocatorIsInit (OCIEnv *envhp, OCIError *errhp,
    06604                              CONST OCILobLocator *locp,
    06605                              boolean *is_initialized);
    06606
    06607 sword   OCILobOpen( OCISvcCtx        *svchp,
    06608                    OCIError         *errhp,
    06609                    OCILobLocator    *locp,
    06610                    ub1               mode );
    06611
    06612 sword   OCILobRead  (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
    06613                      ub4 *amtp, ub4 offset, dvoid *bufp, ub4 bufl, dvoid *ctxp,
    06614                      OCICallbackLobRead cbfp, ub2 csid, ub1 csfrm);
    06615
    06616 sword   OCILobTrim  (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
    06617                      ub4 newlen);
    06618
    06619 sword   OCILobWrite  (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
    06620                       ub4 *amtp, ub4 offset, dvoid *bufp, ub4 buflen, ub1 piece,
    06621                       dvoid *ctxp, OCICallbackLobWrite cbfp, ub2 csid,
    06622                       ub1 csfrm);
    06623
    06624 sword OCILobWriteAppend(OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *lobp,
    06625                         ub4 *amtp, dvoid *bufp, ub4 bufl, ub1 piece, dvoid *ctxp,
    06626                         OCICallbackLobWrite cbfp, ub2 csid, ub1 csfrm);
    06627
    06628 sword   OCIBreak (dvoid *hndlp, OCIError *errhp);
    06629
    06630 sword   OCIReset (dvoid *hndlp, OCIError *errhp);
    06631
    06632 sword   OCIServerVersion  (dvoid *hndlp, OCIError *errhp, OraText *bufp,
    06633                            ub4 bufsz,
    06634                            ub1 hndltype);
    06635
    06636 sword   OCIServerRelease  (dvoid *hndlp, OCIError *errhp, OraText *bufp,
    06637                            ub4 bufsz,
    06638                            ub1 hndltype, ub4 *version);
    06639
    06640 sword   OCIAttrGet (CONST dvoid *trgthndlp, ub4 trghndltyp,
    06641                     dvoid *attributep, ub4 *sizep, ub4 attrtype,
    06642                     OCIError *errhp);
    06643
    06644 sword   OCIAttrSet (dvoid *trgthndlp, ub4 trghndltyp, dvoid *attributep,
    06645                     ub4 size, ub4 attrtype, OCIError *errhp);
    06646
    06647 sword   OCISvcCtxToLda (OCISvcCtx *svchp, OCIError *errhp, Lda_Def *ldap);
    06648
    06649 sword   OCILdaToSvcCtx (OCISvcCtx **svchpp, OCIError *errhp, Lda_Def *ldap);
    06650
    06651 sword   OCIResultSetToStmt (OCIResult *rsetdp, OCIError *errhp);
    06652
    06653 sword OCIFileClose ( dvoid  *hndl, OCIError *err, OCIFileObject *filep );
    06654
    06655 sword   OCIUserCallbackRegister(dvoid *hndlp, ub4 type, dvoid *ehndlp,
    06656                                     OCIUserCallback callback, dvoid *ctxp,
    06657                                     ub4 fcode, ub4 when, OCIUcb *ucbDesc);
    06658
    06659 sword   OCIUserCallbackGet(dvoid *hndlp, ub4 type, dvoid *ehndlp,
    06660                                ub4 fcode, ub4 when, OCIUserCallback *callbackp,
    06661                                dvoid **ctxpp, OCIUcb *ucbDesc);
    06662
    06663 sword   OCISharedLibInit(dvoid *metaCtx, dvoid *libCtx, ub4 argfmt, sword argc,
    06664                          dvoid **argv, OCIEnvCallbackType envCallback);
    06665
    06666 sword OCIFileExists ( dvoid  *hndl, OCIError *err, OraText *filename,
    06667                      OraText *path, ub1 *flag  );
    06668
    06669 sword OCIFileFlush( dvoid *hndl, OCIError *err, OCIFileObject *filep  );
    06670
    06671
    06672 sword OCIFileGetLength( dvoid *hndl, OCIError *err, OraText *filename,
    06673                         OraText *path, ubig_ora *lenp  );
    06674
    06675 sword OCIFileInit ( dvoid *hndl, OCIError *err );
    06676
    06677 sword OCIFileOpen ( dvoid *hndl, OCIError *err, OCIFileObject **filep,
    06678                     OraText *filename, OraText *path, ub4 mode, ub4 create,
    06679                     ub4 type );
    06680
    06681 sword OCIFileRead ( dvoid *hndl, OCIError *err, OCIFileObject *filep,
    06682                     dvoid *bufp, ub4 bufl, ub4 *bytesread );
    06683
    06684 sword OCIFileSeek ( dvoid *hndl, OCIError *err, OCIFileObject *filep,
    06685                      uword origin, ubig_ora offset, sb1 dir );
    06686
    06687 sword OCIFileTerm ( dvoid *hndl, OCIError *err );
    06688
    06689
    06690 sword OCIFileWrite ( dvoid *hndl, OCIError *err, OCIFileObject   *filep,
    06691                      dvoid *bufp, ub4 buflen, ub4 *byteswritten );
    06692
    06693
    06694 #ifdef ORAXB8_DEFINED
    06695
    06696 sword   OCILobCopy2 (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *dst_locp,
    06697                      OCILobLocator *src_locp, oraub8 amount, oraub8 dst_offset,
    06698                      oraub8 src_offset);
    06699
    06700 sword   OCILobErase2 (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
    06701                       oraub8 *amount, oraub8 offset);
    06702
    06703 sword   OCILobGetLength2 (OCISvcCtx *svchp, OCIError *errhp,
    06704                           OCILobLocator *locp, oraub8 *lenp);
    06705
    06706 sword   OCILobLoadFromFile2 (OCISvcCtx *svchp, OCIError *errhp,
    06707                              OCILobLocator *dst_locp,
    06708                              OCILobLocator *src_filep,
    06709                              oraub8 amount, oraub8 dst_offset,
    06710                              oraub8 src_offset);
    06711
    06712 sword   OCILobRead2 (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
    06713                      oraub8 *byte_amtp, oraub8 *char_amtp, oraub8 offset,
    06714                      dvoid *bufp, oraub8 bufl, ub1 piece, dvoid *ctxp,
    06715                      OCICallbackLobRead2 cbfp, ub2 csid, ub1 csfrm);
    06716
    06717 sword   OCILobTrim2 (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
    06718                      oraub8 newlen);
    06719
    06720 sword   OCILobWrite2 (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp,
    06721                       oraub8 *byte_amtp, oraub8 *char_amtp, oraub8 offset,
    06722                       dvoid *bufp, oraub8 buflen, ub1 piece, dvoid *ctxp,
    06723                       OCICallbackLobWrite2 cbfp, ub2 csid, ub1 csfrm);
    06724
    06725 sword OCILobWriteAppend2 (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *lobp,
    06726                           oraub8 *byte_amtp, oraub8 *char_amtp, dvoid *bufp,
    06727                           oraub8 bufl, ub1 piece, dvoid *ctxp,
    06728                           OCICallbackLobWrite2 cbfp, ub2 csid, ub1 csfrm);
    06729
    06730 sword OCILobGetStorageLimit (OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *lobp, oraub8 *limitp);
    06731
    06732 #endif
    06733
    06734 /*
    06735  ** Initialize the security package
    06736  */
    06737 sword   OCISecurityInitialize (OCISecurity *sechandle, OCIError *error_handle);
    06738
    06739 sword   OCISecurityTerminate (OCISecurity *sechandle, OCIError *error_handle);
    06740
    06741 sword OCISecurityOpenWallet(OCISecurity *osshandle,
    06742                             OCIError *error_handle,
    06743                             size_t wrllen,
    06744                             OraText *wallet_resource_locator,
    06745                             size_t pwdlen,
    06746                             OraText *password,
    06747                             nzttWallet *wallet);
    06748
    06749 sword OCISecurityCloseWallet(OCISecurity *osshandle,
    06750                              OCIError *error_handle,
    06751                              nzttWallet *wallet);
    06752
    06753 sword OCISecurityCreateWallet(OCISecurity *osshandle,
    06754                               OCIError *error_handle,
    06755                               size_t wrllen,
    06756                               OraText *wallet_resource_locator,
    06757                               size_t pwdlen,
    06758                               OraText *password,
    06759                               nzttWallet *wallet);
    06760
    06761 sword OCISecurityDestroyWallet(OCISecurity *osshandle,
    06762                                OCIError *error_handle,
    06763                                size_t wrllen,
    06764                                OraText *wallet_resource_locator,
    06765                                size_t pwdlen,
    06766                                OraText *password);
    06767
    06768 sword OCISecurityStorePersona(OCISecurity *osshandle,
    06769                               OCIError *error_handle,
    06770                               nzttPersona **persona,
    06771                               nzttWallet *wallet);
    06772
    06773 sword OCISecurityOpenPersona(OCISecurity *osshandle,
    06774                              OCIError *error_handle,
    06775                              nzttPersona *persona);
    06776
    06777 sword OCISecurityClosePersona(OCISecurity *osshandle,
    06778                               OCIError *error_handle,
    06779                               nzttPersona *persona);
    06780
    06781 sword OCISecurityRemovePersona(OCISecurity *osshandle,
    06782                                OCIError *error_handle,
    06783                                nzttPersona **persona);
    06784
    06785 sword OCISecurityCreatePersona(OCISecurity *osshandle,
    06786                                OCIError *error_handle,
    06787                                nzttIdentType identity_type,
    06788                                nzttCipherType cipher_type,
    06789                                nzttPersonaDesc *desc,
    06790                                nzttPersona **persona);
    06791
    06792 sword OCISecuritySetProtection(OCISecurity *osshandle,
    06793                                OCIError *error_handle,
    06794                                nzttPersona *persona,
    06795                                nzttcef crypto_engine_function,
    06796                                nztttdufmt data_unit_format,
    06797                                nzttProtInfo *protection_info);
    06798
    06799 sword OCISecurityGetProtection(OCISecurity *osshandle,
    06800                                OCIError *error_handle,
    06801                                nzttPersona *persona,
    06802                                nzttcef crypto_engine_function,
    06803                                nztttdufmt * data_unit_format_ptr,
    06804                                nzttProtInfo *protection_info);
    06805
    06806 sword OCISecurityRemoveIdentity(OCISecurity *osshandle,
    06807                                 OCIError *error_handle,
    06808                                 nzttIdentity **identity_ptr);
    06809
    06810 sword OCISecurityCreateIdentity(OCISecurity *osshandle,
    06811                                 OCIError *error_handle,
    06812                                 nzttIdentType type,
    06813                                 nzttIdentityDesc *desc,
    06814                                 nzttIdentity **identity_ptr);
    06815
    06816 sword OCISecurityAbortIdentity(OCISecurity *osshandle,
    06817                                OCIError *error_handle,
    06818                                nzttIdentity **identity_ptr);
    06819
    06820 sword OCISecurityFreeIdentity(OCISecurity *osshandle,
    06821                               OCIError *error_handle,
    06822                               nzttIdentity **identity_ptr);
    06823
    06824
    06825 sword OCISecurityStoreTrustedIdentity(OCISecurity *osshandle,
    06826                                       OCIError *error_handle,
    06827                                       nzttIdentity **identity_ptr,
    06828                                       nzttPersona *persona);
    06829
    06830 sword OCISecuritySign(OCISecurity *osshandle,
    06831                       OCIError *error_handle,
    06832                       nzttPersona *persona,
    06833                       nzttces signature_state,
    06834                       size_t input_length,
    06835                       ub1 *input,
    06836                       nzttBufferBlock *buffer_block);
    06837
    06838 sword OCISecuritySignExpansion(OCISecurity *osshandle,
    06839                                OCIError *error_handle,
    06840                                nzttPersona *persona,
    06841                                size_t inputlen,
    06842                                size_t *signature_length);
    06843
    06844 sword OCISecurityVerify(OCISecurity *osshandle,
    06845                         OCIError *error_handle,
    06846                         nzttPersona *persona,
    06847                         nzttces signature_state,
    06848                         size_t siglen,
    06849                         ub1 *signature,
    06850                         nzttBufferBlock *extracted_message,
    06851                         boolean *verified,
    06852                         boolean *validated,
    06853                         nzttIdentity **signing_party_identity);
    06854
    06855 sword OCISecurityValidate(OCISecurity *osshandle,
    06856                           OCIError *error_handle,
    06857                           nzttPersona *persona,
    06858                           nzttIdentity *identity,
    06859                           boolean *validated);
    06860
    06861 sword OCISecuritySignDetached(OCISecurity *osshandle,
    06862                               OCIError *error_handle,
    06863                               nzttPersona *persona,
    06864                               nzttces signature_state,
    06865                               size_t input_length,
    06866                               ub1 * input,
    06867                               nzttBufferBlock *signature);
    06868
    06869 sword OCISecuritySignDetExpansion(OCISecurity *osshandle,
    06870                                   OCIError *error_handle,
    06871                                   nzttPersona *persona,
    06872                                   size_t input_length,
    06873                                   size_t *required_buffer_length);
    06874
    06875 sword OCISecurityVerifyDetached(OCISecurity *osshandle,
    06876                                 OCIError *error_handle,
    06877                                 nzttPersona *persona,
    06878                                 nzttces signature_state,
    06879                                 size_t data_length,
    06880                                 ub1 *data,
    06881                                 size_t siglen,
    06882                                 ub1 *signature,
    06883                                 boolean *verified,
    06884                                 boolean *validated,
    06885                                 nzttIdentity **signing_party_identity);
    06886
    06887 sword OCISecurity_PKEncrypt(OCISecurity *osshandle,
    06888                             OCIError *error_handle,
    06889                             nzttPersona *persona,
    06890                             size_t number_of_recipients,
    06891                             nzttIdentity *recipient_list,
    06892                             nzttces encryption_state,
    06893                             size_t input_length,
    06894                             ub1 *input,
    06895                             nzttBufferBlock *encrypted_data);
    06896
    06897 sword OCISecurityPKEncryptExpansion(OCISecurity *osshandle,
    06898                                     OCIError *error_handle,
    06899                                     nzttPersona *persona,
    06900                                     size_t number_recipients,
    06901                                     size_t input_length,
    06902                                     size_t *buffer_length_required);
    06903
    06904 sword OCISecurityPKDecrypt(OCISecurity *osshandle,
    06905                            OCIError *error_handle,
    06906                            nzttPersona *persona,
    06907                            nzttces encryption_state,
    06908                            size_t input_length,
    06909                            ub1 *input,
    06910                            nzttBufferBlock *encrypted_data);
    06911
    06912 sword OCISecurityEncrypt(OCISecurity *osshandle,
    06913                          OCIError *error_handle,
    06914                          nzttPersona *persona,
    06915                          nzttces encryption_state,
    06916                          size_t input_length,
    06917                          ub1 *input,
    06918                          nzttBufferBlock *encrypted_data);
    06919
    06920 sword OCISecurityEncryptExpansion(OCISecurity *osshandle,
    06921                                   OCIError *error_handle,
    06922                                   nzttPersona *persona,
    06923                                   size_t input_length,
    06924                                   size_t *encrypted_data_length);
    06925
    06926 sword OCISecurityDecrypt(OCISecurity *osshandle,
    06927                          OCIError *error_handle,
    06928                          nzttPersona *persona,
    06929                          nzttces decryption_state,
    06930                          size_t input_length,
    06931                          ub1 *input,
    06932                          nzttBufferBlock *decrypted_data);
    06933
    06934 sword OCISecurityEnvelope(OCISecurity *osshandle,
    06935                           OCIError *error_handle,
    06936                           nzttPersona *persona,
    06937                           size_t number_of_recipients,
    06938                           nzttIdentity *identity,
    06939                           nzttces encryption_state,
    06940                           size_t input_length,
    06941                           ub1 *input,
    06942                           nzttBufferBlock *enveloped_data);
    06943
    06944 sword OCISecurityDeEnvelope(OCISecurity *osshandle,
    06945                             OCIError *error_handle,
    06946                             nzttPersona *persona,
    06947                             nzttces decryption_state,
    06948                             size_t input_length,
    06949                             ub1 *input,
    06950                             nzttBufferBlock *output_message,
    06951                             boolean *verified,
    06952                             boolean *validated,
    06953                             nzttIdentity **sender_identity);
    06954
    06955 sword OCISecurityKeyedHash(OCISecurity *osshandle,
    06956                            OCIError *error_handle,
    06957                            nzttPersona *persona,
    06958                            nzttces hash_state,
    06959                            size_t input_length,
    06960                            ub1 *input,
    06961                            nzttBufferBlock *keyed_hash);
    06962
    06963 sword OCISecurityKeyedHashExpansion(OCISecurity *osshandle,
    06964                                     OCIError *error_handle,
    06965                                     nzttPersona *persona,
    06966                                     size_t input_length,
    06967                                     size_t *required_buffer_length);
    06968
    06969 sword OCISecurityHash(OCISecurity *osshandle,
    06970                       OCIError *error_handle,
    06971                       nzttPersona *persona,
    06972                       nzttces hash_state,
    06973                       size_t input,
    06974                       ub1 *input_length,
    06975                       nzttBufferBlock *hash);
    06976
    06977 sword OCISecurityHashExpansion(OCISecurity *osshandle,
    06978                                OCIError *error_handle,
    06979                                nzttPersona *persona,
    06980                                size_t input_length,
    06981                                size_t *required_buffer_length);
    06982
    06983 sword OCISecuritySeedRandom(OCISecurity *osshandle,
    06984                             OCIError *error_handle,
    06985                             nzttPersona *persona,
    06986                             size_t seed_length,
    06987                             ub1 *seed);
    06988
    06989 sword OCISecurityRandomBytes(OCISecurity *osshandle,
    06990                              OCIError *error_handle,
    06991                              nzttPersona *persona,
    06992                              size_t number_of_bytes_desired,
    06993                              nzttBufferBlock *random_bytes);
    06994
    06995 sword OCISecurityRandomNumber(OCISecurity *osshandle,
    06996                               OCIError *error_handle,
    06997                               nzttPersona *persona,
    06998                               uword *random_number_ptr);
    06999
    07000 sword OCISecurityInitBlock(OCISecurity *osshandle,
    07001                            OCIError *error_handle,
    07002                            nzttBufferBlock *buffer_block);
    07003
    07004 sword OCISecurityReuseBlock(OCISecurity *osshandle,
    07005                             OCIError *error_handle,
    07006                             nzttBufferBlock *buffer_block);
    07007
    07008 sword OCISecurityPurgeBlock(OCISecurity *osshandle,
    07009                             OCIError *error_handle,
    07010                             nzttBufferBlock *buffer_block);
    07011
    07012 sword OCISecuritySetBlock(OCISecurity *osshandle,
    07013                           OCIError *error_handle,
    07014                           uword flags_to_set,
    07015                           size_t buffer_length,
    07016                           size_t used_buffer_length,
    07017                           ub1 *buffer,
    07018                           nzttBufferBlock *buffer_block);
    07019
    07020 sword OCISecurityGetIdentity(OCISecurity   *osshandle,
    07021                              OCIError      *error_handle,
    07022                              size_t         namelen,
    07023                              OraText          *distinguished_name,
    07024                              nzttIdentity **identity);
    07025
    07026 sword OCIAQEnq(OCISvcCtx *svchp, OCIError *errhp, OraText *queue_name,
    07027                  OCIAQEnqOptions *enqopt, OCIAQMsgProperties *msgprop,
    07028                  OCIType *payload_tdo, dvoid **payload, dvoid **payload_ind,
    07029                  OCIRaw **msgid, ub4 flags);
    07030
    07031 sword OCIAQDeq(OCISvcCtx *svchp, OCIError *errhp, OraText *queue_name,
    07032                  OCIAQDeqOptions *deqopt, OCIAQMsgProperties *msgprop,
    07033                  OCIType *payload_tdo, dvoid **payload, dvoid **payload_ind,
    07034                  OCIRaw **msgid, ub4 flags);
    07035
    07036 sword OCIAQEnqArray(OCISvcCtx *svchp, OCIError *errhp, OraText *queue_name,
    07037                     OCIAQEnqOptions *enqopt, ub4 *iters,
    07038                     OCIAQMsgProperties **msgprop, OCIType *payload_tdo,
    07039                     dvoid **payload, dvoid **payload_ind, OCIRaw **msgid,
    07040                     dvoid *ctxp, OCICallbackAQEnq enqcbfp, ub4 flags);
    07041
    07042 sword OCIAQDeqArray(OCISvcCtx *svchp, OCIError *errhp, OraText *queue_name,
    07043                     OCIAQDeqOptions *deqopt, ub4 *iters,
    07044                     OCIAQMsgProperties **msgprop, OCIType *payload_tdo,
    07045                     dvoid **payload, dvoid **payload_ind, OCIRaw **msgid,
    07046                     dvoid *ctxp, OCICallbackAQDeq deqcbfp, ub4 flags);
    07047
    07048 sword OCIAQListen(OCISvcCtx *svchp, OCIError *errhp,
    07049                       OCIAQAgent **agent_list, ub4 num_agents,
    07050                       sb4 wait, OCIAQAgent **agent,
    07051                       ub4 flags);
    07052
    07053 sword OCIExtractInit(dvoid *hndl, OCIError *err);
    07054
    07055 sword OCIExtractTerm(dvoid *hndl, OCIError *err);
    07056
    07057 sword OCIExtractReset(dvoid *hndl, OCIError *err);
    07058
    07059 sword OCIExtractSetNumKeys(dvoid *hndl, OCIError *err, uword numkeys);
    07060
    07061 sword OCIExtractSetKey(dvoid *hndl, OCIError *err, CONST OraText *name,
    07062                        ub1 type, ub4 flag, CONST dvoid *defval,
    07063                        CONST sb4 *intrange, CONST OraText *CONST *strlist);
    07064
    07065 sword OCIExtractFromFile(dvoid *hndl, OCIError *err, ub4 flag,
    07066                          OraText *filename);
    07067
    07068 sword OCIExtractFromStr(dvoid *hndl, OCIError *err, ub4 flag, OraText *input);
    07069
    07070 sword OCIExtractToInt(dvoid *hndl, OCIError *err, OraText *keyname,
    07071                       uword valno, sb4 *retval);
    07072
    07073 sword OCIExtractToBool(dvoid *hndl, OCIError *err, OraText *keyname,
    07074                        uword valno, ub1 *retval);
    07075
    07076 sword OCIExtractToStr(dvoid *hndl, OCIError *err, OraText *keyname,
    07077                       uword valno, OraText *retval, uword buflen);
    07078
    07079 sword OCIExtractToOCINum(dvoid *hndl, OCIError *err, OraText *keyname,
    07080                          uword valno, OCINumber *retval);
    07081
    07082 sword OCIExtractToList(dvoid *hndl, OCIError *err, uword *numkeys);
    07083
    07084 sword OCIExtractFromList(dvoid *hndl, OCIError *err, uword index,
    07085                          OraText **name,
    07086                          ub1 *type, uword *numvals, dvoid ***values);
    07087
    07088 /* Memory Related Service Interfaces */
    07089
    07090 sword OCIMemoryAlloc(dvoid *hdl, OCIError *err, dvoid **mem,
    07091         OCIDuration dur, ub4 size, ub4 flags);
    07092
    07093 sword OCIMemoryResize(dvoid *hdl, OCIError *err, dvoid **mem,
    07094                         ub4 newsize, ub4 flags);
    07095
    07096 sword OCIMemoryFree(dvoid *hdl, OCIError *err, dvoid *mem);
    07097
    07098 sword OCIContextSetValue(dvoid *hdl, OCIError *err, OCIDuration duration,
    07099                         ub1 *key, ub1 keylen, dvoid *ctx_value);
    07100
    07101 sword OCIContextGetValue(dvoid *hdl, OCIError *err, ub1 *key,
    07102                         ub1 keylen, dvoid **ctx_value);
    07103
    07104 sword OCIContextClearValue(dvoid *hdl, OCIError *err, ub1 *key,
    07105                         ub1 keylen);
    07106
    07107 sword OCIContextGenerateKey(dvoid *hdl, OCIError *err, ub4 *key);
    07108
    07109 sword OCIMemorySetCurrentIDs(dvoid *hdl, OCIError *err,
    07110                              ub4 curr_session_id, ub4 curr_trans_id,
    07111                              ub4 curr_stmt_id);
    07112
    07113 sword OCIPicklerTdsCtxInit(OCIEnv *env, OCIError *err,
    07114                            OCIPicklerTdsCtx **tdsc);
    07115
    07116 sword OCIPicklerTdsCtxFree(OCIEnv *env, OCIError *err, OCIPicklerTdsCtx *tdsc);
    07117
    07118 sword OCIPicklerTdsInit(OCIEnv *env, OCIError *err, OCIPicklerTdsCtx *tdsc,
    07119                                         OCIPicklerTds **tdsh);
    07120
    07121 sword OCIPicklerTdsFree(OCIEnv *env, OCIError *err, OCIPicklerTds *tdsh);
    07122
    07123 sword OCIPicklerTdsCreateElementNumber(OCIEnv *env, OCIError *err,
    07124                                         OCIPicklerTds *tdsh, ub1 prec,
    07125                                         sb1 scale, OCIPicklerTdsElement *elt);
    07126
    07127 sword OCIPicklerTdsCreateElementChar(OCIEnv *env, OCIError *err,
    07128                                      OCIPicklerTds *tdsh, ub2 len,
    07129                                      OCIPicklerTdsElement *elt);
    07130
    07131 sword OCIPicklerTdsCreateElementVarchar(OCIEnv *env, OCIError *err,
    07132                                         OCIPicklerTds *tdsh, ub2 len,
    07133                                         OCIPicklerTdsElement *elt);
    07134
    07135 sword OCIPicklerTdsCreateElementRaw(OCIEnv *env, OCIError *err,
    07136                                     OCIPicklerTds *tdsh, ub2 len,
    07137                                     OCIPicklerTdsElement *elt);
    07138
    07139 sword OCIPicklerTdsCreateElement(OCIEnv *env, OCIError *err,
    07140                                  OCIPicklerTds *tdsh, OCITypeCode dty,
    07141                                  OCIPicklerTdsElement *elt);
    07142
    07143 sword OCIPicklerTdsAddAttr(OCIEnv *env, OCIError *err,
    07144                            OCIPicklerTds *tdsh, OCIPicklerTdsElement elt);
    07145
    07146 sword OCIPicklerTdsGenerate(OCIEnv *env, OCIError *err,
    07147                                 OCIPicklerTds *tdsh);
    07148
    07149 sword OCIPicklerTdsGetAttr(OCIEnv *env, OCIError *err,
    07150                                 CONST OCIPicklerTds *tdsh, ub1  attrno,
    07151                                 OCITypeCode *typ, ub2  *len);
    07152
    07153 sword OCIPicklerFdoInit(OCIEnv *env, OCIError *err,
    07154                                 OCIPicklerFdo **fdoh);
    07155
    07156 sword OCIPicklerFdoFree(OCIEnv *env, OCIError *err,
    07157                                 OCIPicklerFdo *fdoh);
    07158
    07159 sword OCIPicklerImageInit(OCIEnv *env, OCIError *err,
    07160                           OCIPicklerFdo *fdoh,
    07161                           OCIPicklerTds *tdsh,
    07162                           OCIPicklerImage **imgh);
    07163
    07164 sword OCIPicklerImageFree(OCIEnv *env, OCIError *err,
    07165                                 OCIPicklerImage *imgh);
    07166
    07167 sword OCIPicklerImageAddScalar(OCIEnv *env, OCIError *err,
    07168                                OCIPicklerImage *imgh,
    07169                                dvoid *scalar, ub4  len);
    07170
    07171 sword OCIPicklerImageAddNullScalar(OCIEnv *env, OCIError *err,
    07172                                 OCIPicklerImage *imgh);
    07173
    07174 sword OCIPicklerImageGenerate(OCIEnv *env, OCIError *err,
    07175                                 OCIPicklerImage *imgh);
    07176
    07177 sword OCIPicklerImageGetScalarSize(OCIEnv *env, OCIError *err,
    07178                                 OCIPicklerImage *imgh,
    07179                                 ub4  attrno, ub4  *size);
    07180
    07181 sword OCIPicklerImageGetScalar(OCIEnv *env, OCIError *err,
    07182                                 OCIPicklerImage *imgh, ub4  attrno,
    07183                                 dvoid *buf, ub4  *len, OCIInd *ind);
    07184
    07185 sword OCIPicklerImageCollBegin(OCIEnv *env, OCIError *err,
    07186                 OCIPicklerImage *imgh, CONST OCIPicklerTds *colltdsh);
    07187
    07188 sword OCIPicklerImageCollAddScalar( OCIEnv *env, OCIError *err,
    07189                 OCIPicklerImage *imgh, dvoid *scalar,
    07190                 ub4 buflen, OCIInd ind);
    07191
    07192 sword OCIPicklerImageCollEnd(OCIEnv *env, OCIError *err,
    07193                 OCIPicklerImage *imgh);
    07194
    07195 /* should take svcctx for locator stuff */
    07196 sword OCIPicklerImageCollBeginScan(OCIEnv *env, OCIError *err,
    07197                 OCIPicklerImage *imgh, CONST OCIPicklerTds *coll_tdsh,
    07198                 ub4 attrnum, ub4 startidx, OCIInd *ind);
    07199
    07200 sword OCIPicklerImageCollGetScalarSize(OCIEnv *env, OCIError *err,
    07201                 CONST OCIPicklerTds *coll_tdsh, ub4 *size);
    07202
    07203 sword OCIPicklerImageCollGetScalar(OCIEnv *env, OCIError *err,
    07204                                    OCIPicklerImage *imgh, dvoid *buf,
    07205                                    ub4 *buflen, OCIInd *ind);
    07206
    07207 sword OCIAnyDataGetType(OCISvcCtx *svchp, OCIError *errhp, OCIAnyData *sdata,
    07208         OCITypeCode *tc, OCIType **type);
    07209
    07210 sword OCIAnyDataIsNull(OCISvcCtx *svchp, OCIError *errhp, OCIAnyData *sdata,
    07211         boolean *isnull);
    07212
    07213 sword OCIAnyDataConvert(OCISvcCtx *svchp, OCIError *errhp, OCITypeCode tc,
    07214         OCIType *type, OCIDuration dur, dvoid *ind, dvoid *data_val,
    07215         ub4 len, OCIAnyData **sdata);
    07216
    07217 sword OCIAnyDataBeginCreate(OCISvcCtx *svchp, OCIError *errhp, OCITypeCode tc,
    07218         OCIType *type, OCIDuration dur, OCIAnyData **sdata);
    07219
    07220 sword OCIAnyDataDestroy(OCISvcCtx *svchp, OCIError *errhp, OCIAnyData *sdata);
    07221
    07222 sword OCIAnyDataAttrSet(OCISvcCtx *svchp, OCIError *errhp, OCIAnyData *sdata,
    07223         OCITypeCode tc, OCIType *type, dvoid *ind, dvoid *attr_val,
    07224         ub4 length, boolean is_any);
    07225
    07226 sword OCIAnyDataCollAddElem(OCISvcCtx *svchp, OCIError *errhp,
    07227         OCIAnyData *sdata, OCITypeCode tc, OCIType *type, dvoid *ind,
    07228         dvoid *attr_val, ub4 length, boolean is_any, boolean last_elem);
    07229
    07230 sword OCIAnyDataEndCreate(OCISvcCtx *svchp, OCIError *errhp,
    07231                           OCIAnyData *sdata);
    07232
    07233 sword OCIAnyDataAccess(OCISvcCtx *svchp, OCIError *errhp, OCIAnyData *sdata,
    07234         OCITypeCode tc, OCIType *type, dvoid *ind, dvoid *attr_val,
    07235         ub4 *length);
    07236
    07237 sword OCIAnyDataGetCurrAttrNum(OCISvcCtx *svchp, OCIError *errhp,
    07238                                OCIAnyData *sdata, ub4 *attrnum);
    07239
    07240 sword OCIAnyDataAttrGet(OCISvcCtx *svchp, OCIError *errhp, OCIAnyData *sdata,
    07241   OCITypeCode tc, OCIType *type, dvoid *ind, dvoid *attr_val,
    07242         ub4 *length, boolean is_any);
    07243
    07244 sword OCIAnyDataCollGetElem(OCISvcCtx *svchp, OCIError *errhp,
    07245   OCIAnyData *sdata,
    07246   OCITypeCode tc, OCIType *type, dvoid *ind, dvoid *celem_val,
    07247   ub4 *length, boolean is_any);
    07248
    07249
    07250 /*------------------------ OCIAnyDataSet interfaces -------------------------*/
    07251
    07252 /*
    07253    NAME
    07254      OCIAnyDataSetBeginCreate - OCIAnyDataSet Begin Creation
    07255    PARAMETERS
    07256      svchp (IN/OUT) - The OCI service context.
    07257      errhp (IN/OUT) - The OCI error handle. If there is an error, it is
    07258                       recorded in errhp and this function returns OCI_ERROR.
    07259                       Diagnostic information can be obtained by calling
    07260                       OCIErrorGet().
    07261      typecode       - typecode corresponding to the OCIAnyDataSet.
    07262      type (IN)      - type corresponding to the OCIAnyDataSet. If the typecode
    07263                       corresponds to a built-in type (OCI_TYPECODE_NUMBER etc.)
    07264                       , this parameter can be NULL. It should be non NULL for
    07265                       user defined types (OCI_TYPECODE_OBJECT,
    07266                       OCI_TYPECODE_REF, collection types etc.)
    07267      dur (IN)       - duration for which OCIAnyDataSet is allocated.
    07268      data_set (OUT) - Initialized OCIAnyDataSet.
    07269      RETURNS        - error code
    07270    NOTES
    07271      This call allocates an OCIAnyDataSet for the duration of dur and
    07272      initializes it with the type information. The OCIAnyDataSet can hold
    07273      multiple instances of the given type. For performance reasons, the
    07274      OCIAnyDataSet will end up pointing to the passed in OCIType parameter.
    07275      It is the responsibility of the caller to ensure that the OCIType is
    07276      longer lived (has allocation duration >= the duration of the OCIAnyData
    07277      if the OCIType is a transient one, allocation/pin duration >= duration of
    07278      the OCIAnyData if the OCIType is a persistent one).
    07279
    07280 */
    07281 sword OCIAnyDataSetBeginCreate(OCISvcCtx *svchp, OCIError *errhp,
    07282      OCITypeCode typecode, CONST OCIType *type, OCIDuration dur,
    07283      OCIAnyDataSet ** data_set);
    07284
    07285 /*
    07286    NAME
    07287      OCIAnyDataSetDestroy  - OCIAnyDataSet Destroy
    07288    DESCRIPTION
    07289      This call frees the OCIAnyDataSet allocated using
    07290      OCIAnyDataSetBeginCreate().
    07291    RETURNS
    07292      error code.
    07293    PARAMETERS
    07294      svchp (IN/OUT)    - The OCI service context.
    07295      errhp (IN/OUT)    - The OCI Error handle.
    07296      data_set (IN/OUT) - OCIAnyDataSet to be freed.
    07297 */
    07298 sword OCIAnyDataSetDestroy(OCISvcCtx *svchp, OCIError *errhp,
    07299      OCIAnyDataSet *data_set);
    07300
    07301
    07302 /*
    07303    NAME
    07304      OCIAnyDataSetAddInstance - OCIAnyDataSet Add an instance
    07305    DESCRIPTION
    07306      This call adds a new skeleton instance to the OCIAnyDataSet and all the
    07307      attributes of the instance are set to NULL. It returns this skeleton
    07308      instance through the OCIAnyData parameter which can be constructed
    07309      subsequently by invoking the OCIAnyData API.
    07310    RETURNS
    07311      error code.
    07312    PARAMETERS
    07313      svchp (IN/OUT)      - The OCI service context.
    07314      errhp (IN/OUT)      - The OCI Error handle.
    07315      data_set (IN/OUT)   - OCIAnyDataSet to which a new instance is added.
    07316      data (IN/OUT)       - OCIAnyData corresponding to the newly added
    07317                            instance. If (*data) is NULL, a new OCIAnyData will
    07318                            be allocated for same duration as the OCIAnyDataSet.
    07319                            If (*data) is not NULL, it will get reused. This
    07320                            OCIAnyData can be subseqently constructed using the
    07321                            OCIAnyDataConvert() call or it can be constructed
    07322                            piece-wise using the OCIAnyDataAttrSet and
    07323                            OCIAnyDataCollAddElem calls.
    07324    NOTES
    07325      No Destruction of the old value is done here. It is the responsibility of
    07326      the caller to destroy the old value pointed to by (*data) and set (*data)
    07327      to a null pointer before beginning to make a sequence of this call. No
    07328      deep copying (of OCIType information nor the data part.) is done in the
    07329      returned OCIAnyData. This OCIAnyData cannot be used beyond the allocation
    07330      duration of the OCIAnyDataSet (it is like a reference into the
    07331      OCIAnyDataSet). The returned OCIAnyData can be reused on subsequent calls
    07332      to this function, to sequentially add new data instances to the
    07333      OCIAnyDataSet.
    07334 */
    07335 sword OCIAnyDataSetAddInstance(OCISvcCtx *svchp, OCIError *errhp,
    07336      OCIAnyDataSet *data_set, OCIAnyData **data);
    07337
    07338 /*
    07339    NAME
    07340      OCIAnyDataSetEndCreate - OCIAnyDataSet End Creation process.
    07341    DESCRIPTION
    07342      This call marks the end of OCIAnyDataSet creation. It should be called
    07343      after constructing all of its instance(s).
    07344    RETURNS
    07345      error code.
    07346    PARAMETERS
    07347      svchp (IN/OUT)        - The OCI service context.
    07348      errhp (IN/OUT)        - The OCI error handle. If there is an error, it is
    07349                              recorded in errhp and this function returns
    07350                              OCI_ERROR. Diagnostic information can be obtained
    07351                              by calling OCIErrorGet().
    07352      data_set (IN/OUT)     - OCIAnyDataSet that has been fully constructed.
    07353 */
    07354 sword OCIAnyDataSetEndCreate(OCISvcCtx *svchp, OCIError *errhp,
    07355      OCIAnyDataSet *data_set);
    07356
    07357 /*
    07358    NAME
    07359      OCIAnyDataSetGetType - OCIAnyDataSet Get Type of an OCIAnyDataSet
    07360    DESCRIPTION
    07361      Gets the Type corresponding to an OCIAnyDataSet. It returns the actual
    07362      pointer to the type maintained inside an OCIAnyDataSet. No copying is
    07363      done for performance reasons. The client is responsible for not using
    07364      this type once the OCIAnyDataSet is freed (or its duration ends).
    07365    RETURNS
    07366      error code.
    07367    PARAMETERS
    07368      svchp (IN/OUT)      - The OCI service context.
    07369      errhp (IN/OUT)      - The OCI Error handle.
    07370      data_set (IN)       - Initialized OCIAnyDataSet.
    07371      tc (OUT)            - The typecode of the type.
    07372      type (OUT)          - The type corresponding to the OCIAnyDataSet. This
    07373                            could be null if the OCIAnyData corresponds to a
    07374                            built-in type.
    07375 */
    07376 sword OCIAnyDataSetGetType (OCISvcCtx *svchp, OCIError *errhp,
    07377      OCIAnyDataSet *data_set, OCITypeCode *tc, OCIType **type);
    07378
    07379 /*
    07380   NAME
    07381     OCIAnyDataSetGetCount - OCIAnyDataSet Get Count of instances.
    07382   DESCRIPTION
    07383     This call gets the number of instances in the OCIAnyDataSet.
    07384   RETURNS
    07385     error code.
    07386   PARAMETERS
    07387     svchp (IN/OUT)      - OCI Service Context
    07388     errhp (IN/OUT)      - OCI Error handle
    07389     data_set (IN)       - Well formed OCIAnyDataSet.
    07390     count (OUT)         - number of instances in OCIAnyDataSet
    07391 */
    07392 sword OCIAnyDataSetGetCount(OCISvcCtx *svchp, OCIError *errhp,
    07393      OCIAnyDataSet *data_set, ub4 *count);
    07394
    07395 /*
    07396   NAME
    07397     OCIAnyDataSetGetInstance - OCIAnyDataSet Get next instance.
    07398   DESCRIPTION
    07399     Only sequential access to the instances in an OCIAnyDataSet is allowed.
    07400     This call returns the OCIAnyData corresponding to an instance at the
    07401     current position and updates the current position. Subsequently, the
    07402     OCIAnyData access routines may be used to access the instance.
    07403   RETURNS
    07404     error code. Returns OCI_NO_DATA if the current position is at the end of
    07405     the set, OCI_SUCCESS otherwise.
    07406   PARAMETERS
    07407     svchp (IN/OUT)      - OCI Service Context
    07408     errhp (IN/OUT)      - OCI Error handle
    07409     data_set (IN)       - Well formed OCIAnyDataSet
    07410     data (IN/OUT)       - OCIAnyData corresponding to the instance. If (*data)
    07411                           is NULL, a new OCIAnyData will be allocated for same
    07412                           duration as the OCIAnyDataSet. If (*data) is not NULL
    07413                           , it will get reused. This OCIAnyData can be
    07414                           subsequently accessed using the OCIAnyDataAccess()
    07415                           call or piece-wise by using the OCIAnyDataAttrGet()
    07416                           call.
    07417   NOTE
    07418     No Destruction of the old value is done here. It is the responsibility of
    07419     the caller to destroy the old value pointed to by (*data) and set (*data)
    07420     to a null pointer before beginning to make a sequence of this call. No deep
    07421     copying (of OCIType information nor the data part.) is done in the returned
    07422     OCIAnyData. This OCIAnyData cannot be used beyond the allocation duration
    07423     of the OCIAnyDataSet (it is like a reference into the OCIAnyDataSet). The
    07424     returned OCIAnyData can be reused on subsequent calls to this function to
    07425     sequentially access the OCIAnyDataSet.
    07426 */
    07427 sword OCIAnyDataSetGetInstance(OCISvcCtx *svchp, OCIError *errhp,
    07428      OCIAnyDataSet *data_set, OCIAnyData **data);
    07429
    07430 /*--------------------- End of OCIAnyDataSet interfaces ---------------------*/
    07431
    07432 sword OCIFormatInit(dvoid *hndl, OCIError *err);
    07433
    07434 sword OCIFormatString(dvoid *hndl, OCIError *err, OraText *buffer,
    07435                       sbig_ora bufferLength, sbig_ora *returnLength,
    07436                       CONST OraText *formatString, ...);
    07437
    07438 sword OCIFormatTerm(dvoid *hndl, OCIError *err);
    07439
    07440 sword OCIFormatTUb1(void);
    07441 sword OCIFormatTUb2(void);
    07442 sword OCIFormatTUb4(void);
    07443 sword OCIFormatTUword(void);
    07444 sword OCIFormatTUbig_ora(void);
    07445 sword OCIFormatTSb1(void);
    07446 sword OCIFormatTSb2(void);
    07447 sword OCIFormatTSb4(void);
    07448 sword OCIFormatTSword(void);
    07449 sword OCIFormatTSbig_ora(void);
    07450 sword OCIFormatTEb1(void);
    07451 sword OCIFormatTEb2(void);
    07452 sword OCIFormatTEb4(void);
    07453 sword OCIFormatTEword(void);
    07454 sword OCIFormatTChar(void);
    07455 sword OCIFormatTText(void);
    07456 sword OCIFormatTDouble(void);
    07457 sword OCIFormatTDvoid(void);
    07458 sword OCIFormatTEnd(void);
    07459
    07460 /*-------------------------- Extensions to XA interface ---------------------*/
    07461 /* ------------------------- xaosvch ----------------------------------------*/
    07462 /*
    07463    NAME
    07464      xaosvch  -  XA Oracle get SerViCe Handle
    07465    DESCRIPTION
    07466      Given a database name return the service handle that is used by the
    07467      XA library
    07468    NOTE
    07469      This macro has been provided for backward compatibilty with 8.0.2
    07470 */
    07471 OCISvcCtx *xaosvch(OraText *dbname);
    07472
    07473 /* ------------------------- xaoSvcCtx --------------------------------------*/
    07474 /*
    07475    NAME
    07476      xaoSvcCtx  -  XA Oracle get SerViCe ConTeXt
    07477    DESCRIPTION
    07478      Given a database name return the service handle that is used by the
    07479      XA library
    07480    NOTE
    07481      This routine has been provided for APs to get access to the service
    07482      handle that XA library uses. Without this routine APs must use SQLLIB
    07483      routine sqlld2 to get access to the Logon data area registered by the
    07484      XA library
    07485 */
    07486 OCISvcCtx *xaoSvcCtx(OraText *dbname);
    07487
    07488 /* ------------------------- xaoEnv -----------------------------------------*/
    07489 /*
    07490    NAME
    07491      xaoEnv  -  XA Oracle get ENvironment Handle
    07492    DESCRIPTION
    07493      Given a database name return the environment handle that is used by the
    07494      XA library
    07495    NOTE
    07496      This routine has been provided for APs to get access to the environment
    07497      handle that XA library uses. Without this routine APs must use SQLLIB
    07498      routine sqlld2 to get access to the Logon data area registered by the
    07499      XA library
    07500 */
    07501 OCIEnv *xaoEnv(OraText *dbname);
    07502
    07503 /* ------------------------- xaosterr ---------------------------------------*/
    07504 /*
    07505    NAME
    07506      xaosterr  -  XA Oracle get xa STart ERRor code
    07507    DESCRIPTION
    07508      Given an oracle error code return the XA error code
    07509  */
    07510 int xaosterr(OCISvcCtx *svch, sb4 error);
    07511 /*-------------------------- End Extensions ---------------------------------*/
    07512 /*---------------------- Extensions to NLS cartridge service ----------------*/
    07513 /* ----------------------- OCINlsGetInfo ------------------------------------*/
    07514 /*
    07515    NAME
    07516      OCINlsGetInfo - Get NLS info from OCI environment handle
    07517    REMARKS
    07518      This function generates language information specified by item from OCI
    07519      environment handle envhp into an array pointed to by buf within size
    07520      limitation as buflen.
    07521    RETURNS
    07522      OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR on wrong item.
    07523    envhp(IN/OUT)
    07524      OCI environment handle.
    07525    errhp(IN/OUT)
    07526      The OCI error handle. If there is an error, it is record in errhp and
    07527      this function returns a NULL pointer. Diagnostic information can be
    07528      obtained by calling OCIErrorGet().
    07529    buf(OUT)
    07530      Pointer to the destination buffer.
    07531    buflen(IN)
    07532      The size of destination buffer. The maximum length for each information
    07533      is 32 bytes.
    07534    item(IN)
    07535      It specifies to get which item in OCI environment handle and can be one
    07536      of following values:
    07537        OCI_NLS_DAYNAME1 : Native name for Monday.
    07538        OCI_NLS_DAYNAME2 : Native name for Tuesday.
    07539        OCI_NLS_DAYNAME3 : Native name for Wednesday.
    07540        OCI_NLS_DAYNAME4 : Native name for Thursday.
    07541        OCI_NLS_DAYNAME5 : Native name for Friday.
    07542        OCI_NLS_DAYNAME6 : Native name for for Saturday.
    07543        OCI_NLS_DAYNAME7 : Native name for for Sunday.
    07544        OCI_NLS_ABDAYNAME1 : Native abbreviated name for Monday.
    07545        OCI_NLS_ABDAYNAME2 : Native abbreviated name for Tuesday.
    07546        OCI_NLS_ABDAYNAME3 : Native abbreviated name for Wednesday.
    07547        OCI_NLS_ABDAYNAME4 : Native abbreviated name for Thursday.
    07548        OCI_NLS_ABDAYNAME5 : Native abbreviated name for Friday.
    07549        OCI_NLS_ABDAYNAME6 : Native abbreviated name for for Saturday.
    07550        OCI_NLS_ABDAYNAME7 : Native abbreviated name for for Sunday.
    07551        OCI_NLS_MONTHNAME1 : Native name for January.
    07552        OCI_NLS_MONTHNAME2 : Native name for February.
    07553        OCI_NLS_MONTHNAME3 : Native name for March.
    07554        OCI_NLS_MONTHNAME4 : Native name for April.
    07555        OCI_NLS_MONTHNAME5 : Native name for May.
    07556        OCI_NLS_MONTHNAME6 : Native name for June.
    07557        OCI_NLS_MONTHNAME7 : Native name for July.
    07558        OCI_NLS_MONTHNAME8 : Native name for August.
    07559        OCI_NLS_MONTHNAME9 : Native name for September.
    07560        OCI_NLS_MONTHNAME10 : Native name for October.
    07561        OCI_NLS_MONTHNAME11 : Native name for November.
    07562        OCI_NLS_MONTHNAME12 : Native name for December.
    07563        OCI_NLS_ABMONTHNAME1 : Native abbreviated name for January.
    07564        OCI_NLS_ABMONTHNAME2 : Native abbreviated name for February.
    07565        OCI_NLS_ABMONTHNAME3 : Native abbreviated name for March.
    07566        OCI_NLS_ABMONTHNAME4 : Native abbreviated name for April.
    07567        OCI_NLS_ABMONTHNAME5 : Native abbreviated name for May.
    07568        OCI_NLS_ABMONTHNAME6 : Native abbreviated name for June.
    07569        OCI_NLS_ABMONTHNAME7 : Native abbreviated name for July.
    07570        OCI_NLS_ABMONTHNAME8 : Native abbreviated name for August.
    07571        OCI_NLS_ABMONTHNAME9 : Native abbreviated name for September.
    07572        OCI_NLS_ABMONTHNAME10 : Native abbreviated name for October.
    07573        OCI_NLS_ABMONTHNAME11 : Native abbreviated name for November.
    07574        OCI_NLS_ABMONTHNAME12 : Native abbreviated name for December.
    07575        OCI_NLS_YES : Native string for affirmative response.
    07576        OCI_NLS_NO : Native negative response.
    07577        OCI_NLS_AM : Native equivalent string of AM.
    07578        OCI_NLS_PM : Native equivalent string of PM.
    07579        OCI_NLS_AD : Native equivalent string of AD.
    07580        OCI_NLS_BC : Native equivalent string of BC.
    07581        OCI_NLS_DECIMAL : decimal character.
    07582        OCI_NLS_GROUP : group separator.
    07583        OCI_NLS_DEBIT : Native symbol of debit.
    07584        OCI_NLS_CREDIT : Native sumbol of credit.
    07585        OCI_NLS_DATEFORMAT : Oracle date format.
    07586        OCI_NLS_INT_CURRENCY: International currency symbol.
    07587        OCI_NLS_LOC_CURRENCY : Locale currency symbol.
    07588        OCI_NLS_LANGUAGE : Language name.
    07589        OCI_NLS_ABLANGUAGE : Abbreviation for language name.
    07590        OCI_NLS_TERRITORY : Territory name.
    07591        OCI_NLS_CHARACTER_SET : Character set name.
    07592        OCI_NLS_LINGUISTIC : Linguistic name.
    07593        OCI_NLS_CALENDAR : Calendar name.
    07594        OCI_NLS_DUAL_CURRENCY : Dual currency symbol.
    07595 */
    07596 sword OCINlsGetInfo(dvoid *envhp, OCIError *errhp, OraText *buf,
    07597                     size_t buflen, ub2 item);
    07598
    07599 /* ----------------------- OCINlsNumericInfoGet -----------------------------*/
    07600 /*
    07601    NAME
    07602      OCINlsNumericInfoGet - Get NLS numeric info from OCI environment handle
    07603    REMARKS
    07604      This function generates numeric language information specified by item
    07605      from OCI environment handle envhp into an output number variable.
    07606    RETURNS
    07607      OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR on wrong item.
    07608    envhp(IN/OUT)
    07609      OCI environment handle. If handle invalid, returns OCI_INVALID_HANDLE.
    07610    errhp(IN/OUT)
    07611      The OCI error handle. If there is an error, it is record in errhp and
    07612      this function returns a NULL pointer. Diagnostic information can be
    07613      obtained by calling OCIErrorGet().
    07614    val(OUT)
    07615      Pointer to the output number variable. On OCI_SUCCESS return, it will
    07616      contain the requested NLS numeric info.
    07617    item(IN)
    07618      It specifies to get which item in OCI environment handle and can be one
    07619      of following values:
    07620        OCI_NLS_CHARSET_MAXBYTESZ : Maximum character byte size for OCI
    07621                                    environment or session handle charset
    07622        OCI_NLS_CHARSET_FIXEDWIDTH: Character byte size for fixed-width charset;
    07623                                    0 for variable-width charset
    07624 */
    07625 sword OCINlsNumericInfoGet(dvoid *envhp, OCIError *errhp, sb4 *val, ub2 item);
    07626
    07627 /* ----------------------- OCINlsCharSetNameToId ----------------------------*/
    07628 /*
    07629    NAME
    07630      OCINlsCharSetNameToId - Get Oracle charset id given Oracle charset name
    07631    REMARKS
    07632      This function will get the Oracle character set id corresponding to
    07633      the given Oracle character set name.
    07634    RETURNS
    07635      Oracle character set id for the given Oracle character set name if
    07636      character set name and OCI handle are valid; otherwise returns 0.
    07637    envhp(IN/OUT)
    07638      OCI environment handle.
    07639    name(IN)
    07640      Pointer to a null-terminated Oracle character set name whose id
    07641      will be returned.
    07642 */
    07643 ub2 OCINlsCharSetNameToId(dvoid *envhp, const oratext *name);
    07644
    07645 /* ----------------------- OCINlsCharSetIdToName ----------------------------*/
    07646 /*
    07647    NAME
    07648      OCINlsCharSetIdToName - Get Oracle charset name given Oracle charset id
    07649    REMARKS
    07650      This function will get the Oracle character set name corresponding to
    07651      the given Oracle character set id.
    07652    RETURNS
    07653      OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    07654    envhp(IN/OUT)
    07655      OCI environment handle. If handle invalid, returns OCI_INVALID_HANDLE.
    07656    buf(OUT)
    07657      Pointer to the destination buffer. On OCI_SUCCESS return, it will contain
    07658      the null-terminated string for character set name.
    07659    buflen(IN)
    07660      Size of destination buffer. Recommended size is OCI_NLS_MAXBUFSZ for
    07661      guarantee to store an Oracle character set name. If it's smaller than
    07662      the length of the character set name, the function will return OCI_ERROR.
    07663    id(IN)
    07664      Oracle character set id.
    07665 */
    07666 sword OCINlsCharSetIdToName(dvoid *envhp, oratext *buf, size_t buflen, ub2 id);
    07667
    07668 /* ----------------------- OCINlsNameMap ------------------------------------*/
    07669 /*
    07670    NAME
    07671      OCINlsNameMap - Map NLS naming from Oracle to other standards and vice
    07672                      versa
    07673    REMARKS
    07674      This function will map NLS naming from Oracle to other standards (such
    07675      as ISO, IANA) and vice versa.
    07676    RETURNS
    07677      OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
    07678    envhp(IN/OUT)
    07679      OCI environment handle. If handle invalid, returns OCI_INVALID_HANDLE.
    07680    buf(OUT)
    07681      Pointer to the destination buffer. On OCI_SUCCESS return, it will
    07682      contain null-terminated string for requested mapped name.
    07683    buflen(IN)
    07684      The size of destination buffer. Recommended size is OCI_NLS_MAXBUFSZ
    07685      for guarantee to store an NLS name. If it is smaller than the length
    07686      of the name, the function will return OCI_ERROR.
    07687    srcbuf(IN)
    07688      Pointer to null-terminated NLS name. If it is not a valid name in its
    07689      define scope, the function will return OCI_ERROR.
    07690    flag(IN)
    07691      It specifies name mapping direction and can take the following values:
    07692        OCI_NLS_CS_IANA_TO_ORA : Map character set name from IANA to Oracle
    07693        OCI_NLS_CS_ORA_TO_IANA : Map character set name from Oracle to IANA
    07694        OCI_NLS_LANG_ISO_TO_ORA : Map language name from ISO to Oracle
    07695        OCI_NLS_LANG_ORA_TO_ISO : Map language name from Oracle to ISO
    07696        OCI_NLS_TERR_ISO_TO_ORA : Map territory name from ISO to Oracle
    07697        OCI_NLS_TERR_ORA_TO_ISO : Map territory name from Oracle to ISO
    07698        OCI_NLS_TERR_ISO3_TO_ORA : Map territory name from 3-letter ISO
    07699                                   abbreviation to Oracle
    07700        OCI_NLS_TERR_ORA_TO_ISO3 : Map territory name from Oracle to 3-letter
    07701                                   ISO abbreviation
    07702 */
    07703 sword OCINlsNameMap(dvoid *envhp, oratext *buf, size_t buflen,
    07704                     const oratext *srcbuf, ub4 flag);
    07705
    07706 /* -------------------- OCIMultiByteToWideChar ------------------------------*/
    07707 /*
    07708    NAME
    07709      OCIMultiByteToWideChar - Convert a null terminated multibyte string into
    07710                               wchar
    07711    REMARKS
    07712      This routine converts an entire null-terminated string into the wchar
    07713      format. The wchar output buffer will be null-terminated.
    07714    RETURNS
    07715      OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
    07716    envhp(IN/OUT)
    07717      OCI environment handle to determine the character set of string.
    07718    dst (OUT)
    07719      Destination buffer for wchar.
    07720    src (IN)
    07721      Source string to be converted.
    07722    rsize (OUT)
    07723      Number of characters converted including null-terminator.
    07724      If it is a NULL pointer, no number return
    07725 */
    07726 sword OCIMultiByteToWideChar(dvoid *envhp, OCIWchar *dst, CONST OraText *src,
    07727                              size_t *rsize);
    07728
    07729
    07730 /* --------------------- OCIMultiByteInSizeToWideChar -----------------------*/
    07731 /*
    07732    NAME
    07733      OCIMultiByteInSizeToWideChar - Convert a mulitbyte string in length into
    07734                                     wchar
    07735    REMARKS
    07736      This routine converts part of string into the wchar format. It will
    07737      convert as many complete characters as it can until it reaches output
    07738      buffer size or input buffer size or it reaches a null-terminator in
    07739      source string. The output buffer will be null-terminated if space permits.
    07740      If dstsz is zero, this function will only return number of characters not
    07741      including ending null terminator for converted string.
    07742    RETURNS
    07743      OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
    07744    envhp(IN/OUT)
    07745      OCI environment handle to determine the character set of string.
    07746    dst (OUT)
    07747      Pointer to a destination buffer for wchar. It can be NULL pointer when
    07748      dstsz is zero.
    07749    dstsz(IN)
    07750      Destination buffer size in character. If it is zero, this function just
    07751      returns number of characters will be need for the conversion.
    07752    src (IN)
    07753      Source string to be converted.
    07754    srcsz(IN)
    07755      Length of source string in byte.
    07756    rsize(OUT)
    07757      Number of characters written into destination buffer, or number of
    07758      characters for converted string is dstsz is zero.
    07759      If it is NULL pointer, nothing to return.
    07760 */
    07761 sword OCIMultiByteInSizeToWideChar(dvoid *envhp, OCIWchar *dst,
    07762                                   size_t dstsz, CONST OraText *src,
    07763                                   size_t srcsz, size_t *rsize);
    07764
    07765
    07766 /* ---------------------- OCIWideCharToMultiByte ----------------------------*/
    07767 /*
    07768    NAME
    07769      OCIWideCharToMultiByte - Convert a null terminated wchar string into
    07770                               multibyte
    07771    REMARKS
    07772      This routine converts an entire null-terminated wide character string into
    07773      multi-byte string. The output buffer will be null-terminated.
    07774    RETURNS
    07775      OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
    07776    envhp(IN/OUT)
    07777      OCI environment handle to determine the character set of string.
    07778    dst (OUT)
    07779      Destination buffer for multi-byte string.
    07780    src (IN)
    07781      Source wchar string to be converted.
    07782    rsize (OUT)
    07783      Number of bytes written into the destination buffer.
    07784      If it is NULL pointer, nothing to return.
    07785 */
    07786 sword OCIWideCharToMultiByte(dvoid *envhp, OraText *dst, CONST OCIWchar *src,
    07787                              size_t *rsize);
    07788
    07789
    07790 /* ---------------------- OCIWideCharInSizeToMultiByte ----------------------*/
    07791 /*
    07792    NAME
    07793      OCIWideCharInSizeToMultiByte - Convert a wchar string in length into
    07794                                     mulitbyte
    07795    REMARKS
    07796      This routine converts part of wchar string into the multi-byte format.
    07797      It will convert as many complete characters as it can until it reaches
    07798      output buffer size or input buffer size or it reaches a null-terminator
    07799      in source string. The output buffer will be null-terminated if space
    07800      permits. If dstsz is zero, the function just returns the size of byte not
    07801      including ending null-terminator need to store the converted string.
    07802    RETURNS
    07803      OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
    07804    envhp(IN/OUT)
    07805      OCI environment handle to determine the character set of string.
    07806    dst (OUT)
    07807      Destination buffer for multi-byte. It can be NULL pointer if dstsz is
    07808      zero.
    07809    dstsz(IN)
    07810      Destination buffer size in byte. If it is zero, it just returns the size
    07811      of bytes need for converted string.
    07812    src (IN)
    07813      Source wchar string to be converted.
    07814    srcsz(IN)
    07815      Length of source string in character.
    07816    rsize(OUT)
    07817      Number of bytes written into destination buffer, or number of bytes need
    07818      to store the converted string if dstsz is zero.
    07819      If it is NULL pointer, nothing to return.
    07820 */
    07821 sword OCIWideCharInSizeToMultiByte(dvoid *envhp, OraText *dst,
    07822                                     size_t dstsz, CONST OCIWchar *src,
    07823                                     size_t srcsz, size_t *rsize);
    07824
    07825
    07826
    07827 /* ----------------------- OCIWideCharIsAlnum -------------------------------*/
    07828 /*
    07829    NAME
    07830      OCIWideCharIsAlnum - test whether wc is a letter or decimal digit
    07831    REMARKS
    07832      It tests whether wc is a letter or decimal digit.
    07833    RETURNS
    07834      TRUE or FLASE.
    07835    envhp(IN/OUT)
    07836      OCI environment handle to determine the character set .
    07837    wc(IN)
    07838      Wchar for testing.
    07839 */
    07840 boolean OCIWideCharIsAlnum(dvoid *envhp, OCIWchar wc);
    07841
    07842
    07843 /* ----------------------- OCIWideCharIsAlpha -------------------------------*/
    07844 /*
    07845    NAME
    07846      OCIWideCharIsAlpha - test whether wc is an alphabetic letter
    07847    REMARKS
    07848      It tests whether wc is an alphabetic letter
    07849    RETURNS
    07850      TRUE or FLASE.
    07851    envhp(IN/OUT)
    07852      OCI environment handle to determine the character set .
    07853    wc(IN)
    07854      Wchar for testing.
    07855 */
    07856 boolean OCIWideCharIsAlpha(dvoid *envhp, OCIWchar wc);
    07857
    07858
    07859 /* --------------------- OCIWideCharIsCntrl ---------------------------------*/
    07860 /*
    07861    NAME
    07862      OCIWideCharIsCntrl - test whether wc is a control character
    07863    REMARKS
    07864      It tests whether wc is a control character.
    07865    RETURNS
    07866      TRUE or FLASE.
    07867    envhp(IN/OUT)
    07868      OCI environment handle to determine the character set .
    07869    wc(IN)
    07870      Wchar for testing.
    07871 */
    07872 boolean OCIWideCharIsCntrl(dvoid *envhp, OCIWchar wc);
    07873
    07874
    07875 /* ----------------------- OCIWideCharIsDigit -------------------------------*/
    07876 /*
    07877    NAME
    07878      OCIWideCharIsDigit - test whether wc is a decimal digit character
    07879    REMARKS
    07880      It tests whether wc is a decimal digit character.
    07881    RETURNS
    07882      TRUE or FLASE.
    07883    envhp(IN/OUT)
    07884      OCI environment handle to determine the character set .
    07885    wc(IN)
    07886      Wchar for testing.
    07887 */
    07888 boolean OCIWideCharIsDigit(dvoid *envhp, OCIWchar wc);
    07889
    07890
    07891 /* ----------------------- OCIWideCharIsGraph -------------------------------*/
    07892 /*
    07893    NAME
    07894      OCIWideCharIsGraph - test whether wc is a graph character
    07895    REMARKS
    07896      It tests whether wc is a graph character. A graph character is character
    07897      with a visible representation and normally includes alphabetic letter,
    07898      decimal digit, and punctuation.
    07899    RETURNS
    07900      TRUE or FLASE.
    07901    envhp(IN/OUT)
    07902      OCI environment handle to determine the character set .
    07903    wc(IN)
    07904      Wchar for testing.
    07905 */
    07906 boolean OCIWideCharIsGraph(dvoid *envhp, OCIWchar wc);
    07907
    07908
    07909 /* ----------------------- OCIWideCharIsLower -------------------------------*/
    07910 /*
    07911    NAME
    07912      OCIWideCharIsLower - test whether wc is a lowercase letter
    07913    REMARKS
    07914      It tests whether wc is a lowercase letter.
    07915    RETURNS
    07916      TRUE or FLASE.
    07917    envhp(IN/OUT)
    07918      OCI environment handle to determine the character set .
    07919    wc(IN)
    07920      Wchar for testing.
    07921 */
    07922 boolean OCIWideCharIsLower(dvoid *envhp, OCIWchar wc);
    07923
    07924
    07925 /* ----------------------- OCIWideCharIsPrint -------------------------------*/
    07926 /*
    07927    NAME
    07928      OCIWideCharIsPrint - test whether wc is a printable character
    07929    REMARKS
    07930      It tests whether wc is a printable character.
    07931    RETURNS
    07932      TRUE or FLASE.
    07933    envhp(IN/OUT)
    07934      OCI environment handle to determine the character set .
    07935    wc(IN)
    07936      Wchar for testing.
    07937 */
    07938 boolean OCIWideCharIsPrint(dvoid *envhp, OCIWchar wc);
    07939
    07940
    07941 /* ----------------------- OCIWideCharIsPunct -------------------------------*/
    07942 /*
    07943    NAME
    07944      OCIWideCharIsPunct - test whether wc is a punctuation character
    07945    REMARKS
    07946      It tests whether wc is a punctuation character.
    07947    RETURNS
    07948      TRUE or FLASE.
    07949    envhp(IN/OUT)
    07950      OCI environment handle to determine the character set .
    07951    wc(IN)
    07952      Wchar for testing.
    07953 */
    07954 boolean OCIWideCharIsPunct(dvoid *envhp, OCIWchar wc);
    07955
    07956
    07957 /* ----------------------- OCIWideCharIsSpace -------------------------------*/
    07958 /*
    07959    NAME
    07960      OCIWideCharIsSpace - test whether wc is a space character
    07961    REMARKS
    07962      It tests whether wc is a space character. A space character only causes
    07963      white space in displayed text(for example, space, tab, carriage return,
    07964      newline, vertical tab or form feed).
    07965    RETURNS
    07966      TRUE or FLASE.
    07967    envhp(IN/OUT)
    07968      OCI environment handle to determine the character set .
    07969    wc(IN)
    07970      Wchar for testing.
    07971 */
    07972 boolean OCIWideCharIsSpace(dvoid *envhp, OCIWchar wc);
    07973
    07974
    07975 /* ----------------------- OCIWideCharIsUpper -------------------------------*/
    07976 /*
    07977    NAME
    07978      OCIWideCharIsUpper - test whether wc is a uppercase letter
    07979    REMARKS
    07980      It tests whether wc is a uppercase letter.
    07981    RETURNS
    07982      TRUE or FLASE.
    07983    envhp(IN/OUT)
    07984      OCI environment handle to determine the character set .
    07985    wc(IN)
    07986      Wchar for testing.
    07987 */
    07988 boolean OCIWideCharIsUpper(dvoid *envhp, OCIWchar wc);
    07989
    07990
    07991 /*----------------------- OCIWideCharIsXdigit -------------------------------*/
    07992 /*
    07993    NAME
    07994      OCIWideCharIsXdigit - test whether wc is a hexadecimal digit
    07995    REMARKS
    07996      It tests whether wc is a hexadecimal digit ( 0-9, A-F, a-f ).
    07997    RETURNS
    07998      TRUE or FLASE.
    07999    envhp(IN/OUT)
    08000      OCI environment handle to determine the character set .
    08001    wc(IN)
    08002      Wchar for testing.
    08003 */
    08004 boolean OCIWideCharIsXdigit(dvoid *envhp, OCIWchar wc);
    08005
    08006
    08007 /* --------------------- OCIWideCharIsSingleByte ----------------------------*/
    08008 /*
    08009    NAME
    08010      OCIWideCharIsSingleByte - test whether wc is a single-byte character
    08011    REMARKS
    08012      It tests whether wc is a single-byte character when converted into
    08013      multi-byte.
    08014    RETURNS
    08015      TRUE or FLASE.
    08016    envhp(IN/OUT)
    08017      OCI environment handle to determine the character set .
    08018    wc(IN)
    08019      Wchar for testing.
    08020 */
    08021 boolean OCIWideCharIsSingleByte(dvoid *envhp, OCIWchar wc);
    08022
    08023
    08024 /* ----------------------- OCIWideCharToLower -------------------------------*/
    08025 /*
    08026    NAME
    08027      OCIWideCharToLower - Convert a wchar into the lowercase
    08028    REMARKS
    08029      If there is a lower-case character mapping for wc in the specified locale,
    08030      it will return the lower-case in wchar, else return wc itself.
    08031    RETURNS
    08032      A wchar
    08033    envhp(IN/OUT)
    08034      OCI environment handle to determine the character set .
    08035    wc(IN)
    08036      Wchar for lowercase mapping.
    08037 */
    08038 OCIWchar OCIWideCharToLower(dvoid *envhp, OCIWchar wc);
    08039
    08040
    08041 /* ----------------------- OCIWideCharToUpper -------------------------------*/
    08042 /*
    08043    NAME
    08044      OCIWideCharToUpper - Convert a wchar into the uppercase
    08045    REMARKS
    08046      If there is a upper-case character mapping for wc in the specified locale,
    08047      it will return the upper-case in wchar, else return wc itself.
    08048    RETURNS
    08049      A wchar
    08050    envhp(IN/OUT)
    08051      OCI environment handle to determine the character set .
    08052    wc(IN)
    08053      Wchar for uppercase mapping.
    08054 */
    08055 OCIWchar OCIWideCharToUpper(dvoid *envhp, OCIWchar wc);
    08056
    08057
    08058 /* ----------------------- OCIWideCharStrcmp --------------------------------*/
    08059 /*
    08060    NAME
    08061      OCIWideCharStrcmp - compare two null terminated wchar string
    08062    REMARKS
    08063      It compares two wchar string in binary ( based on wchar encoding value ),
    08064      linguistic, or case-insensitive.
    08065    RETURNS
    08066      0, if wstr1 == wstr2.
    08067      Positive, if wstr1 > wstr2.
    08068      Negative, if wstr1 < wstr2.
    08069    envhp(IN/OUT)
    08070      OCI environment handle to determine the character set.
    08071    wstr1(IN)
    08072      Pointer to a null-terminated wchar string.
    08073    wstr2(IN)
    08074      Pointer to a null-terminated wchar string.
    08075    flag(IN)
    08076      It is used to decide the comparison method. It can be taken one of the
    08077      following values:
    08078        OCI_NLS_BINARY : for the binary comparison, this is default value.
    08079        OCI_NLS_LINGUISTIC : for linguistic comparison specified in the locale.
    08080      This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive
    08081      comparison.
    08082 */
    08083 int OCIWideCharStrcmp(dvoid *envhp, CONST OCIWchar *wstr1,
    08084                 CONST OCIWchar *wstr2, int flag);
    08085
    08086
    08087 /* ----------------------- OCIWideCharStrncmp -------------------------------*/
    08088 /*
    08089    NAME
    08090      OCIWideCharStrncmp - compare twe wchar string in length
    08091    REMARKS
    08092      This function is similar to OCIWideCharStrcmp(), except that at most len1
    08093      characters from wstr1 and len2 characters from wstr1 are compared. The
    08094      null-terminator will be taken into the comparison.
    08095    RETURNS
    08096      0, if wstr1 = wstr2
    08097      Positive, if wstr1 > wstr2
    08098      Negative, if wstr1 < wstr2
    08099    envhp(IN/OUT)
    08100      OCI environment handle to determine the character set .
    08101    wstr1(IN)
    08102      Pointer to the first wchar string
    08103    len1(IN)
    08104      The length for the first string for comparison
    08105    wstr2(IN)
    08106      Pointer to the second wchar string
    08107    len2(IN)
    08108      The length for the second string for comparison.
    08109    flag(IN)
    08110      It is used to decide the comparison method. It can be taken one of the
    08111      following values:
    08112        OCI_NLS_BINARY : for the binary comparison, this is default value.
    08113        OCI_NLS_LINGUISTIC : for linguistic comparison specified in the locale.
    08114      This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive
    08115      comparison.
    08116 */
    08117 int OCIWideCharStrncmp(dvoid *envhp, CONST OCIWchar *wstr1, size_t len1,
    08118                  CONST OCIWchar *wstr2, size_t len2, int flag);
    08119
    08120
    08121 /* ----------------------- OCIWideCharStrcat --------------------------------*/
    08122 /*
    08123    NAME
    08124      OCIWideCharStrcat - concatenate two wchar strings
    08125    REMARKS
    08126      This function appends a copy of the wchar string pointed to by wsrcstr,
    08127      including the null-terminator to the end of wchar string pointed to by
    08128      wdststr. It returns the number of character in the result string not
    08129      including the ending null-terminator.
    08130    RETURNS
    08131      number of characters in the result string not including the ending
    08132      null-terminator.
    08133    envhp(IN/OUT)
    08134      OCI environment handle to determine the character set .
    08135    wdststr(IN/OUT)
    08136      Pointer to the destination wchar string for appending.
    08137    wsrcstr(IN)
    08138      Pointer to the source wchar string to append.
    08139 */
    08140 size_t OCIWideCharStrcat(dvoid *envhp, OCIWchar *wdststr,
    08141                          CONST OCIWchar *wsrcstr);
    08142
    08143
    08144 /* ----------------------- OCIWideCharStrchr --------------------------------*/
    08145 /*
    08146    NAME
    08147      OCIWideCharStrchr - Search the first occurrence of wchar in a wchar string
    08148    REMARKS
    08149      This function searchs for the first occurrence of wc in the wchar string
    08150      pointed to by wstr. It returns a pointer to the whcar if successful, or
    08151      a null pointer.
    08152    RETURNS
    08153      wchar pointer if successful, otherwise a null pointer.
    08154    envhp(IN/OUT)
    08155      OCI environment handle to determine the character set .
    08156    wstr(IN)
    08157      Pointer to the wchar string to search
    08158    wc(IN)
    08159      Wchar to search for.
    08160 */
    08161 OCIWchar *OCIWideCharStrchr(dvoid *envhp, CONST OCIWchar *wstr,
    08162                             OCIWchar wc);
    08163
    08164
    08165 /* ----------------------- OCIWideCharStrcpy --------------------------------*/
    08166 /*
    08167    NAME
    08168      OCIWideCharStrcpy - copy a wchar string
    08169    REMARKS
    08170      This function copies the wchar string pointed to by wsrcstr, including the
    08171      null-terminator, into the array pointed to by wdststr. It returns the
    08172      number of character copied not including the ending null-terminator.
    08173    RETURNS
    08174      number of characters copied not including the ending null-terminator.
    08175    envhp(IN/OUT)
    08176      OCI environment handle to determine the character set .
    08177    wdststr(OUT)
    08178      Pointer to the destination wchar buffer.
    08179    wsrcstr(IN)
    08180      Pointer to the source wchar string.
    08181 */
    08182 size_t OCIWideCharStrcpy(dvoid *envhp, OCIWchar *wdststr,
    08183                          CONST OCIWchar *wsrcstr);
    08184
    08185
    08186 /* ----------------------- OCIWideCharStrlen --------------------------------*/
    08187 /*
    08188    NAME
    08189      OCIWideCharStrlen - Return number of character in a wchar string
    08190    REMARKS
    08191      This function computes the number of characters in the wchar string
    08192      pointed to by wstr, not including the null-terminator, and returns
    08193     this number.
    08194    RETURNS
    08195      number of characters not including ending null-terminator.
    08196    envhp(IN/OUT)
    08197      OCI environment handle to determine the character set .
    08198    wstr(IN)
    08199      Pointer to the source wchar string.
    08200 */
    08201 size_t OCIWideCharStrlen(dvoid *envhp, CONST OCIWchar *wstr);
    08202
    08203
    08204 /* ----------------------- OCIWideCharStrncat -------------------------------*/
    08205 /*
    08206    NAME
    08207      OCIWideCharStrncat - Concatenate wchar string in length
    08208    REMARKS
    08209      This function is similar to OCIWideCharStrcat(), except that at most n
    08210      characters from wsrcstr are appended to wdststr. Note that the
    08211      null-terminator in wsrcstr will stop appending. wdststr will be
    08212      null-terminated..
    08213    RETURNS
    08214      Number of characters in the result string not including the ending
    08215      null-terminator.
    08216    envhp(IN/OUT)
    08217      OCI environment handle to determine the character set .
    08218    wdststr(IN/OUT)
    08219      Pointer to the destination wchar string for appending.
    08220    wsrcstr(IN)
    08221      Pointer to the source wchar string to append.
    08222    n(IN)
    08223      Number of characters from wsrcstr to append.
    08224 */
    08225 size_t OCIWideCharStrncat(dvoid *envhp, OCIWchar *wdststr,
    08226                           CONST OCIWchar *wsrcstr, size_t n);
    08227
    08228
    08229 /* ----------------------- OCIWideCharStrncpy -------------------------------*/
    08230 /*
    08231    NAME
    08232      OCIWideCharStrncpy - Copy wchar string in length
    08233    REMARKS
    08234      This function is similar to OCIWideCharStrcpy(), except that at most n
    08235      characters are copied from the array pointed to by wsrcstr to the array
    08236      pointed to by wdststr. Note that the null-terminator in wdststr will
    08237      stop coping and result string will be null-terminated.
    08238    RETURNS
    08239      number of characters copied not including the ending null-terminator.
    08240    envhp(IN/OUT)
    08241      OCI environment handle to determine the character set .
    08242    wdststr(OUT)
    08243      Pointer to the destination wchar buffer.
    08244    wsrcstr(IN)
    08245      Pointer to the source wchar string.
    08246    n(IN)
    08247      Number of characters from wsrcstr to copy.
    08248 */
    08249 size_t OCIWideCharStrncpy(dvoid *envhp, OCIWchar *wdststr,
    08250                           CONST OCIWchar *wsrcstr, size_t n);
    08251
    08252
    08253 /* ----------------------- OCIWideCharStrrchr -------------------------------*/
    08254 /*
    08255    NAME
    08256      OCIWideCharStrrchr - search the last occurrence of a wchar in wchar string
    08257    REMARKS
    08258      This function searchs for the last occurrence of wc in the wchar string
    08259      pointed to by wstr. It returns a pointer to the whcar if successful, or
    08260      a null pointer.
    08261    RETURNS
    08262      wchar pointer if successful, otherwise a null pointer.
    08263    envhp(IN/OUT)
    08264      OCI environment handle to determine the character set .
    08265    wstr(IN)
    08266      Pointer to the wchar string to search
    08267    wc(IN)
    08268      Wchar to search for.
    08269 */
    08270 OCIWchar *OCIWideCharStrrchr(dvoid *envhp, CONST OCIWchar *wstr,
    08271                              OCIWchar wc);
    08272
    08273
    08274 /* --------------------- OCIWideCharStrCaseConversion -----------------------*/
    08275 /*
    08276    NAME
    08277      OCIWideCharStrCaseConversion - convert a wchar string into lowercase or
    08278                                     uppercase
    08279    REMARKS
    08280      This function convert the wide char string pointed to by wsrcstr into the
    08281      uppercase or lowercase specified by flag and copies the result into the
    08282      array pointed to by wdststr. The result string will be null-terminated.
    08283    RETURNS
    08284      number of characters for result string not including null-terminator.
    08285    envhp(IN/OUT)
    08286      OCI environment handle.
    08287    wdststr(OUT)
    08288      Pointer to destination array.
    08289    wsrcstr(IN)
    08290      Pointer to source string.
    08291    flag(IN)
    08292      Specify the case to convert:
    08293        OCI_NLS_UPPERCASE : convert to uppercase.
    08294        OCI_NLS_LOWERCASE: convert to lowercase.
    08295      This flag can be ORed with OCI_NLS_LINGUISTIC to specify that the
    08296      linguistic setting in the locale will be used for case conversion.
    08297 */
    08298 size_t OCIWideCharStrCaseConversion(dvoid *envhp, OCIWchar *wdststr,
    08299                                     CONST OCIWchar *wsrcstr, ub4 flag);
    08300
    08301
    08302 /*---------------------- OCIWideCharDisplayLength ---------------------------*/
    08303 /*
    08304    NAME
    08305      OCIWideCharDisplayLength - Calculate the display length for a wchar
    08306    REMARKS
    08307      This function determines the number of column positions required for wc
    08308      in display. It returns number of column positions, or 0 if wc is
    08309      null-terminator.
    08310    RETURNS
    08311      Number of display positions.
    08312    envhp(IN/OUT)
    08313      OCI environment handle to determine the character set .
    08314    wc(IN)
    08315      Wchar character.
    08316 */
    08317 size_t OCIWideCharDisplayLength(dvoid *envhp, OCIWchar wc );
    08318
    08319
    08320 /*---------------------- OCIWideCharMultiByteLength -------------------------*/
    08321 /*
    08322    NAME
    08323      OCIWideCharMultiByteLength - Determine byte size in multi-byte encoding
    08324    REMARKS
    08325      This function determines the number of byte required for wc in multi-byte
    08326      encoding. It returns number of bytes in multi-byte for wc.
    08327    RETURNS
    08328      Number of bytes.
    08329    envhp(IN/OUT)
    08330      OCI environment handle to determine the character set .
    08331    wc(IN)
    08332      Wchar character.
    08333 */
    08334 size_t OCIWideCharMultiByteLength(dvoid *envhp, OCIWchar wc);
    08335
    08336
    08337 /* ----------------------- OCIMultiByteStrcmp -------------------------------*/
    08338 /*
    08339    NAME
    08340      OCIMultiByteStrcmp - Compare two multi-byte strings
    08341    REMARKS
    08342      It compares two multi-byte strings in binary ( based on encoding value ),
    08343      linguistic, or case-insensitive.
    08344    RETURNS
    08345      0, if str1 == str2.
    08346      Positive, if str1 > str2.
    08347      Negative, if str1 < str2.
    08348    envhp(IN/OUT)
    08349      OCI environment handle to determine the character set.
    08350    str1(IN)
    08351      Pointer to a null-terminated string.
    08352    str2(IN)
    08353      Pointer to a null-terminated string.
    08354    flag(IN)
    08355      It is used to decide the comparison method. It can be taken one of the
    08356      following values:
    08357        OCI_NLS_BINARY: for the binary comparison, this is default value.
    08358        OCI_NLS_LINGUISTIC: for linguistic comparison specified in the locale.
    08359      This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive
    08360      comparison.
    08361 */
    08362 int OCIMultiByteStrcmp(dvoid *envhp, CONST OraText *str1,
    08363                        CONST OraText *str2, int flag);
    08364
    08365
    08366 /*----------------------- OCIMultiByteStrncmp -------------------------------*/
    08367 /*
    08368    NAME
    08369      OCIMultiByteStrncmp - compare two strings in length
    08370    REMARKS
    08371      This function is similar to OCIMultiBytestrcmp(), except that at most
    08372      len1 bytes from str1 and len2 bytes from str2 are compared. The
    08373      null-terminator will be taken into the comparison.
    08374    RETURNS
    08375      0, if str1 = str2
    08376      Positive, if str1 > str2
    08377      Negative, if str1 < str2
    08378    envhp(IN/OUT)
    08379      OCI environment handle to determine the character set.
    08380    str1(IN)
    08381      Pointer to the first string
    08382    len1(IN)
    08383      The length for the first string for comparison
    08384    str2(IN)
    08385      Pointer to the second string
    08386    len2(IN)
    08387      The length for the second string for comparison.
    08388    flag(IN)
    08389      It is used to decide the comparison method. It can be taken one of the
    08390      following values:
    08391        OCI_NLS_BINARY: for the binary comparison, this is default value.
    08392        OCI_NLS_LINGUISTIC: for linguistic comparison specified in the locale.
    08393      This flag can be ORed with OCI_NLS_CASE_INSENSITIVE for case-insensitive
    08394      comparison.
    08395 */
    08396 int OCIMultiByteStrncmp(dvoid *envhp, CONST OraText *str1, size_t len1,
    08397                         OraText *str2, size_t len2, int flag);
    08398
    08399
    08400 /*----------------------- OCIMultiByteStrcat --------------------------------*/
    08401 /*
    08402    NAME
    08403      OCIMultiByteStrcat - concatenate multibyte strings
    08404    REMARKS
    08405      This function appends a copy of the multi-byte string pointed to by
    08406      srcstr, including the null-terminator to the end of string pointed to by
    08407      dststr. It returns the number of bytes in the result string not including
    08408      the ending null-terminator.
    08409    RETURNS
    08410      number of bytes in the result string not including the ending
    08411      null-terminator.
    08412    envhp(IN/OUT)
    08413      Pointer to OCI environment handle
    08414    dststr(IN/OUT)
    08415      Pointer to the destination multi-byte string for appending.
    08416    srcstr(IN)
    08417      Pointer to the source string to append.
    08418 */
    08419 size_t OCIMultiByteStrcat(dvoid *envhp, OraText *dststr,
    08420                           CONST OraText *srcstr);
    08421
    08422
    08423 /*------------------------- OCIMultiByteStrcpy ------------------------------*/
    08424 /*
    08425    NAME
    08426      OCIMultiByteStrcpy - copy multibyte string
    08427    REMARKS
    08428      This function copies the multi-byte string pointed to by srcstr,
    08429      including the null-terminator, into the array pointed to by dststr. It
    08430      returns the number of bytes copied not including the ending
    08431      null-terminator.
    08432    RETURNS
    08433      number of bytes copied not including the ending null-terminator.
    08434    envhp(IN/OUT)
    08435      Pointer to the OCI environment handle.
    08436    srcstr(OUT)
    08437      Pointer to the destination buffer.
    08438    dststr(IN)
    08439      Pointer to the source multi-byte string.
    08440 */
    08441 size_t OCIMultiByteStrcpy(dvoid *envhp, OraText *dststr,
    08442                           CONST OraText *srcstr);
    08443
    08444
    08445 /*----------------------- OCIMultiByteStrlen --------------------------------*/
    08446 /*
    08447    NAME
    08448      OCIMultiByteStrlen - Calculate multibyte string length
    08449    REMARKS
    08450      This function computes the number of bytes in the multi-byte string
    08451      pointed to by str, not including the null-terminator, and returns this
    08452      number.
    08453    RETURNS
    08454      number of bytes not including ending null-terminator.
    08455    str(IN)
    08456      Pointer to the source multi-byte string.
    08457 */
    08458 size_t OCIMultiByteStrlen(dvoid *envhp, CONST OraText *str);
    08459
    08460
    08461 /*----------------------- OCIMultiByteStrncat -------------------------------*/
    08462 /*
    08463    NAME
    08464      OCIMultiByteStrncat - concatenate string in length
    08465    REMARKS
    08466      This function is similar to OCIMultiBytestrcat(), except that at most n
    08467      bytes from srcstr are appended to dststr. Note that the null-terminator in
    08468      srcstr will stop appending and the function will append as many character
    08469      as possible within n bytes. dststr will be null-terminated.
    08470    RETURNS
    08471      Number of bytes in the result string not including the ending
    08472      null-terminator.
    08473    envhp(IN/OUT)
    08474      Pointer to OCI environment handle.
    08475    srcstr(IN/OUT)
    08476      Pointer to the destination multi-byte string for appending.
    08477    dststr(IN)
    08478      Pointer to the source multi-byte string to append.
    08479    n(IN)
    08480      Number of bytes from srcstr to append.
    08481 */
    08482 size_t OCIMultiByteStrncat(dvoid *envhp, OraText *dststr,
    08483                            CONST OraText *srcstr, size_t n);
    08484
    08485
    08486 /*----------------------- OCIMultiByteStrncpy -------------------------------*/
    08487 /*
    08488    NAME
    08489      OCIMultiByteStrncpy - copy multibyte string in length
    08490    REMARKS
    08491      This function is similar to OCIMultiBytestrcpy(), except that at most n
    08492      bytes are copied from the array pointed to by srcstr to the array pointed
    08493      to by dststr. Note that the null-terminator in srcstr will stop coping and
    08494      the function will copy as many character as possible within n bytes. The
    08495      result string will be null-terminated.
    08496    RETURNS
    08497      number of bytes copied not including the ending null-terminator.
    08498    envhp(IN/OUT)
    08499      Pointer to a OCI environment handle.
    08500    dststr(IN)
    08501      Pointer to the source multi-byte string.
    08502    srcstr(OUT)
    08503      Pointer to the destination buffer.
    08504    n(IN)
    08505      Number of bytes from srcstr to copy.
    08506 */
    08507 size_t OCIMultiByteStrncpy(dvoid *envhp, OraText *dststr,
    08508                            CONST OraText *srcstr, size_t n);
    08509
    08510
    08511 /*----------------------- OCIMultiByteStrnDisplayLength ---------------------*/
    08512 /*
    08513    NAME
    08514      OCIMultiByteStrnDisplayLength - calculate the display length for a
    08515                                      multibyt string
    08516    REMARKS
    08517      This function returns the number of display positions occupied by the
    08518      complete characters within the range of n bytes.
    08519    RETURNS
    08520      number of display positions.
    08521    envhp(IN/OUT)
    08522      OCI environment handle.
    08523    str(IN)
    08524      Pointer to a multi-byte string.
    08525    n(IN)
    08526      Number of bytes to examine.
    08527 */
    08528 size_t OCIMultiByteStrnDisplayLength(dvoid *envhp, CONST OraText *str1,
    08529                                      size_t n);
    08530
    08531
    08532 /*---------------------- OCIMultiByteStrCaseConversion  ---------------------*/
    08533 /*
    08534    NAME
    08535      OCIMultiByteStrCaseConversion
    08536    REMARKS
    08537      This function convert the multi-byte string pointed to by srcstr into the
    08538      uppercase or lowercase specified by flag and copies the result into the
    08539      array pointed to by dststr. The result string will be null-terminated.
    08540    RETURNS
    08541      number of bytes for result string not including null-terminator.
    08542    envhp(IN/OUT)
    08543      OCI environment handle.
    08544    dststr(OUT)
    08545      Pointer to destination array.
    08546    srcstr(IN)
    08547      Pointer to source string.
    08548    flag(IN)
    08549      Specify the case to convert:
    08550        OCI_NLS_UPPERCASE: convert to uppercase.
    08551        OCI_NLS_LOWERCASE: convert to lowercase.
    08552      This flag can be ORed with OCI_NLS_LINGUISTIC to specify that the
    08553      linguistic setting in the locale will be used for case conversion.
    08554 */
    08555 size_t OCIMultiByteStrCaseConversion(dvoid *envhp, OraText *dststr,
    08556                                      CONST OraText *srcstr, ub4 flag);
    08557
    08558
    08559 /*------------------------- OCICharSetToUnicode -----------------------------*/
    08560 /*
    08561    NAME
    08562      OCICharSetToUnicode - convert multibyte string into Unicode as UCS2
    08563    REMARKS
    08564      This function converts a multi-byte string pointed to by src to Unicode
    08565      into the array pointed to by dst. The conversion will stop when it reach
    08566      to the source limitation or destination limitation.
    08567      The function will return number of characters converted into Unicode.
    08568      If dstlen is zero, it will just return the number of characters for the
    08569      result without real conversion.
    08570    RETURNS
    08571      OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
    08572    envhp(IN/OUT)
    08573      Pointer to an OCI environment handle
    08574    dst(OUT)
    08575      Pointer to a destination buffer
    08576    dstlen(IN)
    08577      Size of destination buffer in character
    08578    src(IN)
    08579      Pointer to multi-byte source string.
    08580    srclen(IN)
    08581      Size of source string in bytes.
    08582    rsize(OUT)
    08583      Number of characters converted.
    08584      If it is a NULL pointer, nothing to return.
    08585 */
    08586 sword OCICharSetToUnicode(dvoid *envhp, ub2 *dst, size_t dstlen,
    08587                           CONST OraText *src, size_t  srclen, size_t *rsize);
    08588
    08589
    08590 /*------------------------- OCIUnicodeToCharSet -----------------------------*/
    08591 /*
    08592    NAME
    08593      OCIUnicodeToCharSet - convert Unicode into multibyte
    08594    REMARKS
    08595      This function converts a Unicode string pointed to by src to multi-byte
    08596      into the array pointed to by dst. The conversion will stop when it reach
    08597      to the source limitation or destination limitation. The function will
    08598      return number of bytes converted into multi-byte. If dstlen is zero, it
    08599      will just return the number of bytes for the result without real
    08600      conversion. If a Unicode character is not convertible for the character
    08601      set specified in OCI environment handle, a replacement character will be
    08602      used for it. In this case, OCICharSetConversionIsReplacementUsed() will
    08603      return ture.
    08604    RETURNS
    08605      OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
    08606    envhp(IN/OUT)
    08607      Pointer to an OCI environment handle.
    08608    dst(OUT)
    08609      Pointer to a destination buffer.
    08610    dstlen(IN)
    08611      Size of destination buffer in byte.
    08612    src(IN)
    08613      Pointer to a Unicode string.
    08614    srclen(IN)
    08615      Size of source string in characters.
    08616    rsize(OUT)
    08617      Number of bytes converted.
    08618      If it is a NULL pointer, nothing to return.
    08619 */
    08620 sword OCIUnicodeToCharSet(dvoid *envhp, OraText *dst, size_t dstlen,
    08621                            CONST ub2 *src, size_t srclen, size_t *rsize);
    08622
    08623 /*----------------------- OCINlsCharSetConvert ------------------------------*/
    08624 /*
    08625    NAME
    08626      OCINlsCharSetConvert - convert between any two character set.
    08627    REMARKS
    08628      This function converts a string pointed to by src in the character set
    08629      specified with srcid to the array pointed to by dst in the character set
    08630      specified with dstid. The conversion will stop when it reaches the source
    08631      limitation or destination limitation. The function will return the number
    08632      of bytes converted into the destination buffer. Even though either source
    08633      or destination character set id is OCI_UTF16ID, given and return data
    08634      length will be represented with the byte length as this function is
    08635      intended for generic purpose. Note the conversion will not stop at null
    08636      data.
    08637      To get character set id from name, OCINlsCharSetNameToId can be used.
    08638      To check if derived data in the destination buffer contains any
    08639      replacement character resulting from conversion failure,
    08640      OCICharSetConversionIsReplacementUsed can be used to get the status.
    08641      Data alignment should be guaranteed by a caller. For example, UTF-16 data
    08642      should be aligned to ub2 type.
    08643
    08644    RETURNS
    08645      OCI_SUCCESS or OCI_ERROR.
    08646    errhp(IN/OUT)
    08647      OCI error handle. If there is an error, it is recorded in errhp and this
    08648      function returns a NULL pointer. Diagnostic information can be obtained
    08649      by calling OCIErrorGet().
    08650    dstid(IN)
    08651      Character set id for the destination buffer.
    08652    dstp(OUT)
    08653      Pointer to the destination buffer.
    08654    dstlen(IN)
    08655      The maximum byte size of destination buffer.
    08656    srcid(IN)
    08657      Character set id for the source buffer.
    08658    srcp(IN)
    08659      Pointer to the source buffer.
    08660    srclen(IN)
    08661      The length byte size of source buffer.
    08662    rsize(OUT)
    08663      The number of characters converted. If it is a NULL pointer, nothing to
    08664      return.
    08665 */
    08666 sword OCINlsCharSetConvert(dvoid *envhp, OCIError *errhp,
    08667                         ub2 dstid, dvoid *dstp, size_t dstlen,
    08668                         ub2 srcid, CONST dvoid *srcp, size_t srclen,
    08669                         size_t *rsize);
    08670
    08671
    08672 /* ------------------- OCICharsetConversionIsReplacementUsed ----------------*/
    08673 /*
    08674    NAME
    08675      OCICharsetConversionIsReplacementUsed - chech if replacement is used in
    08676                                              conversion
    08677    REMARKS
    08678      This function indicates whether or not the replacement character was used
    08679      for nonconvertible characters in character set conversion in last invoke
    08680      of OCICharsetUcs2ToMb().
    08681    RETURNS
    08682      TRUE is the replacement character was used in last OCICharsetUcs2ToMb()
    08683      invoking, else FALSE.
    08684    envhp(IN/OUT)
    08685      OCI environment handle. This should be the first handle passed to
    08686      OCICharsetUcs2ToMb().
    08687 */
    08688 boolean OCICharSetConversionIsReplacementUsed(dvoid *envhp);
    08689
    08690 /*------------------- OCINlsEnvironmentVariableGet -----------------*/
    08691 /*
    08692    NAME
    08693      OCINlsEnvironmentVariableGet - get a value of NLS environment variable.
    08694
    08695    DESCRIPTION
    08696      This function retrieves a value of NLS environment variable to the buffer
    08697      pointed to by val. Data type is determined by the parameter specified by
    08698      item. Either numeric data or string data can be retrieved.
    08699
    08700    RETURNS
    08701      OCI_SUCCESS or OCI_ERROR.
    08702
    08703    PARAMETERS
    08704    valp(OUT) -
    08705      Pointer to the buffer.
    08706    size(IN) -
    08707      Size of the buffer. This argument is only applicable to string data type,
    08708      but not to numerical data, in such case, it is ignored.
    08709    item(IN) -
    08710      NLS item value, which can be one of following values:
    08711        OCI_NLS_CHARSET_ID  - NLS_LANG character set id in ub2 data type.
    08712        OCI_NLS_NCHARSET_ID - NLS_NCHAR character set id in ub2 data type.
    08713    charset(IN) -
    08714      Character set id for retrieved string data. If it is 0, NLS_LANG will be
    08715      used. OCI_UTF16ID is a valid id. In case of numeric data, this argument
    08716      is ignored.
    08717    rsize(OUT) -
    08718      Size of return value.
    08719
    08720    NOTE
    08721      This functions is mainly used for retrieving character set id from either
    08722      NLS_LANG or NLS_NCHAR environment variables. If NLS_LANG is not set,
    08723      the default character set id is returned.
    08724      For future extension, the buffer is capable for storing other data types.
    08725 */
    08726 sword OCINlsEnvironmentVariableGet(dvoid  *valp, size_t size, ub2 item,
    08727                                    ub2 charset, size_t *rsize);
    08728
    08729
    08730 /*------------------------- OCIMessageOpen ----------------------------------*/
    08731 /*
    08732    NAME
    08733      OCIMessageOpen - open a locale message file
    08734    REMARKS
    08735      This function opens a message handle for facility of product in a language
    08736      pointed to by envhp. It first try to open the message file corresponding
    08737      to envhp for the facility. If it successes, it will use that file to
    08738      initialize a message handle, else it will use the default message file
    08739      which is for American language for the facility. The function return a
    08740      pointer pointed to a message handle into msghp parameter.
    08741    RETURNS
    08742      OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
    08743    envhp(IN/OUT)
    08744      A pointer to OCI environment handle for message language.
    08745    errhp(IN/OUT)
    08746      The OCI error handle. If there is an error, it is record in errhp and this
    08747      function returns a NULL pointer. Diagnostic information can be obtained by
    08748      calling OCIErrorGet().
    08749    msghp(OUT)
    08750      a message handle for return
    08751    product(IN)
    08752      A pointer to a product name. Product name is used to locate the directory
    08753      for message in a system dependent way. For example, in Solaris, the
    08754      directory of message files for the product `rdbms' is
    08755      `${ORACLE_HOME}/rdbms'.
    08756    facility(IN)
    08757      A pointer to a facility name in the product. It is used to construct a
    08758      message file name. A message file name follows the conversion with
    08759      facility as prefix. For example, the message file name for facility
    08760      `img' in American language will be `imgus.msb' where `us' is the
    08761      abbreviation of American language and `msb' as message binary file
    08762      extension.
    08763    dur(IN)
    08764      Duration for memory allocation for the return message handle. It can be
    08765      the following values:
    08766         OCI_DURATION_CALL
    08767         OCI_DURATION_STATEMENT
    08768         OCI_DURATION_SESSION
    08769         OCI_DURATION_TRANSACTION
    08770      For the detail description, please refer to Memory Related Service
    08771      Interfaces section.
    08772 */
    08773 sword OCIMessageOpen(dvoid *envhp, OCIError *errhp, OCIMsg **msghp,
    08774                       CONST OraText *product, CONST OraText *facility,
    08775                       OCIDuration dur);
    08776
    08777
    08778 /*------------------------- OCIMessageGet -----------------------------------*/
    08779 /*
    08780    NAME
    08781      OCIMessageGet - get a locale message from a message handle
    08782    REMARKS
    08783      This function will get message with message number identified by msgno and
    08784      if buflen is not zero, the function will copy the message into the buffer
    08785      pointed to by msgbuf. If buflen is zero, the message will be copied into
    08786      a message buffer inside the message handle pointed to by msgh. For both
    08787      cases. it will return the pointer to the null-terminated message string.
    08788      If it cannot get the message required, it will return a NULL pointer.
    08789    RETURNS
    08790      A pointer to a null-terminated message string on success, otherwise a NULL
    08791      pointer.
    08792    msgh(IN/OUT)
    08793      Pointer to a message handle which was previously opened by
    08794      OCIMessageOpen().
    08795    msgno(IN)
    08796      The message number for getting message.
    08797    msgbuf(OUT)
    08798      Pointer to a destination buffer to the message retrieved. If buflen is
    08799      zero, it can be NULL pointer.
    08800    buflen(IN)
    08801      The size of the above destination buffer.
    08802 */
    08803 OraText *OCIMessageGet(OCIMsg *msgh, ub4 msgno, OraText *msgbuf,
    08804                        size_t buflen);
    08805
    08806 /*------------------------- OCIMessageClose ---------------------------------*/
    08807 /*
    08808    NAME
    08809      OCIMessageClose - close a message handle
    08810    REMARKS
    08811      This function closes a message handle pointed to by msgh and frees any
    08812      memory associated with this handle.
    08813    RETURNS
    08814      OCI_SUCCESS, OCI_INVALID_HANDLE or OCI_ERROR
    08815    envhp(IN/OUT)
    08816      A pointer to OCI environment handle for message language.
    08817    errhp(IN/OUT)
    08818      The OCI error handle. If there is an error, it is record in errhp and this
    08819      function returns a NULL pointer. Diagnostic information can be obtained by
    08820      calling OCIErrorGet().
    08821    msghp(IN/OUT)
    08822      A pointer to a message handle which was previously opened by
    08823      OCIMessageOpen().
    08824 */
    08825 sword OCIMessageClose(dvoid *envhp, OCIError *errhp, OCIMsg *msghp);
    08826
    08827 /*--------------- End of Extensions to NLS cartridge service ----------------*/
    08828
    08829
    08830 /*----------------- Extensions to OCI Thread interface ---------------------*/
    08831 /*****************************************************************************
    08832                               DESCRIPTION
    08833 ******************************************************************************
    08834 1 Threads Interface
    08835
    08836 The OCIThread package provides a number of commonly used threading
    08837 primitives for use by Oracle customers.  It offers a portable interface to
    08838 threading capabilities native to various platforms.  It does not implement
    08839 threading on platforms which do not have native threading capability.
    08840
    08841 OCIThread does not provide a portable implementation of multithreaded
    08842 facilities.  It only serves as a set of portable covers for native
    08843 multithreaded facilities.  Therefore, platforms that do not have native
    08844 support for multi-threading will only be able to support a limited
    08845 implementation of OCIThread.  As a result, products that rely on all of
    08846 OCIThread's functionality will not port to all platforms.  Products that must
    08847 port to all platforms must use only a subset of OCIThread's functionality.
    08848 This issue is discussed further in later sections of this document.
    08849
    08850 The OCIThread API is split into four main parts.  Each part is described
    08851 briefly here.  The following subsections describe each in greater detail.
    08852
    08853  1. Initialization and Termination Calls
    08854
    08855      These calls deal with the initialization and termination of OCIThread.
    08856      Initialization of OCIThread initializes the OCIThread context which is
    08857      a member of the OCI environment or session handle.  This context is
    08858      required for other OCIThread calls.
    08859
    08860  2. Passive Threading Primitives
    08861
    08862      The passive threading primitives include primitives to manipulate mutual
    08863      exclusion (mutex) locks, thread ID's, and thread-specific data keys.
    08864
    08865      The reason that these primitives are described as 'passive' is that while
    08866      their specifications allow for the existence of multiple threads, they do
    08867      not require it.  This means that it is possible for these primitives to
    08868      be implemented according to specification in both single-threaded and
    08869      multi-threaded environments.
    08870
    08871      As a result, OCIThread clients that use only these primitives will not
    08872      require the existence of multiple threads in order to work correctly,
    08873      i.e., they will be able to work in single-threaded environments without
    08874      branching code.
    08875
    08876  3. Active Threading Primitives
    08877
    08878      Active threading primitives include primitives dealing with the creation,
    08879      termination, and other manipulation of threads.
    08880
    08881      The reason that these primitives are described as 'active' is that they
    08882      can only be used in true multi-threaded environments.  Their
    08883      specifications explicitly require that it be possible to have multiple
    08884      threads.  If you need to determine at runtime whether or not you are in a
    08885      multi-threaded environment, call OCIThreadIsMulti() before calling an
    08886      OCIThread active primitive.
    08887
    08888
    08889 1.1 Initialization & Termination
    08890 ==================================
    08891
    08892 The types and functions described in this section are associated with the
    08893 initialization and termination of the OCIThread package.  OCIThread must
    08894 be properly initialized before any of its functionality can be used.
    08895 OCIThread's process initialization function, 'OCIThreadProcessInit()',
    08896 must be called with care; see below.
    08897
    08898 The observed behavior of the initialization and termination functions is the
    08899 same regardless of whether OCIThread is in single-threaded or multi-threaded
    08900 environment.  It is OK to call the initialization functions from both generic
    08901 and operating system specific (OSD) code.
    08902
    08903 1.1.1 Types
    08904
    08905   OCIThreadContext - OCIThread Context
    08906   -------------------------------------
    08907
    08908     Most calls to OCIThread functions take the OCI environment or session
    08909     handle as a parameter.  The OCIThread context is part of the OCI
    08910     environment or session handle and it must be initialized by calling
    08911     'OCIThreadInit()'.  Termination of the OCIThread context occurs by calling
    08912     'OCIThreadTerm()'.
    08913
    08914     The OCIThread context is a private data structure.  Clients must NEVER
    08915     attempt to examine the contents of the context.
    08916
    08917 1.1.2  OCIThreadProcessInit
    08918
    08919   OCIThreadProcessInit - OCIThread Process INITialization
    08920   --------------------------------------------------------
    08921
    08922     Description
    08923
    08924       This function should be called to perform OCIThread process
    08925       initialization.
    08926
    08927     Prototype
    08928
    08929       void OCIThreadProcessInit();
    08930
    08931     Returns
    08932
    08933       Nothing.
    08934
    08935     Notes
    08936
    08937       Whether or not this function needs to be called depends on how OCI
    08938       Thread is going to be used.
    08939
    08940         * In a single-threaded application, calling this function is optional.
    08941           If it is called at all, the first call to it must occur before calls
    08942           to any other OCIThread functions.  Subsequent calls can be made
    08943           without restriction; they will not have any effect.
    08944
    08945         * In a multi-threaded application, this function MUST be called.  The
    08946           first call to it MUST occur 'strictly before' any other OCIThread
    08947           calls; i.e., no other calls to OCIThread functions (including other
    08948           calls to this one) can be concurrent with the first call.
    08949           Subsequent calls to this function can be made without restriction;
    08950           they will not have any effect.
    08951
    08952
    08953 1.1.3 OCIThreadInit
    08954
    08955   OCIThreadInit - OCIThread INITialize
    08956   -------------------------------------
    08957
    08958     Description
    08959
    08960       This initializes OCIThread context.
    08961
    08962     Prototype
    08963
    08964       sword OCIThreadInit(dvoid *hndl, OCIError *err);
    08965
    08966         hndl(IN/OUT): The OCI environment or session handle.
    08967
    08968         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    08969                      is returned, the error is recorded in err and diagnostic
    08970                      information can be obtained by calling OCIErrorGet().
    08971
    08972     Returns
    08973
    08974       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    08975
    08976     Notes
    08977
    08978       It is illegal for OCIThread clients to try an examine the memory
    08979       pointed to by the returned pointer.
    08980
    08981       It is safe to make concurrent calls to 'OCIThreadInit()'.  Unlike
    08982       'OCIThreadProcessInit()',  there is no need to have a first call
    08983       that occurs before all the others.
    08984
    08985       The first time 'OCIThreadInit()' is called, it initilaizes the OCI
    08986       Thread context.  It also saves a pointer to the context in some system
    08987       dependent manner.  Subsequent calls to 'OCIThreadInit()' will return
    08988       the same context.
    08989
    08990       Each call to 'OCIThreadInit()' must eventually be matched by a call to
    08991       'OCIThreadTerm()'.
    08992
    08993   OCIThreadTerm - OCIThread TERMinate
    08994   ------------------------------------
    08995
    08996     Description
    08997
    08998       This should be called to release the OCIThread context.  It should be
    08999       called exactly once for each call made to 'OCIThreadInit()'.
    09000
    09001     Prototype
    09002
    09003       sword OCIThreadTerm(dvoid *hndl, OCIError *err);
    09004
    09005         hndl(IN/OUT): The OCI environment or session handle.
    09006
    09007         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09008                      is returned, the error is recorded in err and diagnostic
    09009                      information can be obtained by calling OCIErrorGet().
    09010
    09011     Returns
    09012
    09013       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09014
    09015     Notes
    09016
    09017       It is safe to make concurrent calls to 'OCIThreadTerm()'.
    09018
    09019       'OCIThreadTerm()' will not do anything until it has been called as
    09020       many times as 'OCIThreadInit()' has been called.  When that happens,
    09021       it terminates the OCIThread layer and frees the memory allocated for
    09022       the context.  Once this happens, the context should not be re-used.
    09023       It will be necessary to obtain a new one by calling 'OCIThreadInit()'.
    09024
    09025
    09026   OCIThreadIsMulti - OCIThread Is Multi-Threaded?
    09027   ------------------------------------------------
    09028
    09029     Description
    09030
    09031       This tells the caller whether the application is running in a
    09032       multi-threaded environment or a single-threaded environment.
    09033
    09034     Prototype
    09035       boolean OCIThreadIsMulti(void);
    09036
    09037     Returns
    09038
    09039       TRUE if the environment is multi-threaded;
    09040       FALSE if the environment is single-threaded.
    09041
    09042
    09043 1.2 Passive Threading Primitives
    09044 ==================================
    09045
    09046 1.2.1 Types
    09047
    09048 The passive threading primitives deal with the manipulation of mutex,
    09049 thread ID's, and thread-specific data.  Since the specifications of these
    09050 primitives do not require the existence of multiple threads, they can be
    09051 used both on multithreaded and single-threaded platforms.
    09052
    09053 1.2.1.1  OCIThreadMutex - OCIThread Mutual Exclusion Lock
    09054 -----------------------------------------------------------
    09055
    09056   The type 'OCIThreadMutex' is used to represent a mutual exclusion lock
    09057   (mutex).  A mutex is typically used for one of two purposes: (i) to
    09058   ensure that only one thread accesses a given set of data at a time, or
    09059   (ii) to ensure that only one thread executes a given critical section of
    09060   code at a time.
    09061
    09062   Mutexes pointer can be declared as parts of client structures or as
    09063   stand-alone variables.  Before they can be used, they must be initialized
    09064   using 'OCIThreadMutexInit()'.  Once they are no longer needed, they must be
    09065   destroyed using 'OCIThreadMutexDestroy()'.  A mutex pointer must NOT be
    09066   used after it is destroyed.
    09067
    09068   A thread can acquire a mutex by using either 'OCIThreadMutexAcquire()' or
    09069   'OCIThreadMutexTry()'.  They both ensure that only one thread at a time is
    09070   allowed to hold a given mutex.  A thread that holds a mutex can release it
    09071   by calling 'OCIThreadMutexRelease()'.
    09072
    09073
    09074 1.2.1.2  OCIThreadKey - OCIThread Key for Thread-Specific Data
    09075 ----------------------------------------------------------------
    09076
    09077   A key can be thought of as a process-wide variable that has a
    09078   thread-specific value.  What this means is that all the threads in a
    09079   process can use any given key.  However, each thread can examine or modify
    09080   that key independently of the other threads.  The value that a thread sees
    09081   when it examines the key will always be the same as the value that it last
    09082   set for the key.  It will not see any values set for the key by the other
    09083   threads.
    09084
    09085   The type of the value held by a key is a 'dvoid *' generic pointer.
    09086
    09087   Keys can be created using 'OCIThreadKeyInit()'.  When a key is created, its
    09088   value is initialized to 'NULL' for all threads.
    09089
    09090   A thread can set a key's value using 'OCIThreadKeySet()'.  A thread can
    09091   get a key's value using 'OCIThreadKeyGet()'.
    09092
    09093   The OCIThread key functions will save and retrieve data SPECIFIC TO THE
    09094   THREAD.  When clients maintain a pool of threads and assign the threads to
    09095   different tasks, it *may not* be appropriate for a task to use OCIThread
    09096   key functions to save data associated with it.  Here is a scenario of how
    09097   things can fail: A thread is assigned to execute the initialization of a
    09098   task.  During the initialization, the task stored some data related to it
    09099   in the thread using OCIThread key functions.  After the initialization,
    09100   the thread is returned back to the threads pool.  Later, the threads pool
    09101   manager assigned another thread to perform some operations on the task,
    09102   and the task needs to retrieve those data it stored earlier in
    09103   initialization.  Since the task is running in another thread, it will not
    09104   be able to retrieve the same data back!  Applications that use thread
    09105   pools should be aware of this and be cautious when using OCIThread key
    09106   functions.
    09107
    09108
    09109 1.2.1.3  OCIThreadKeyDestFunc - OCIThread Key Destructor Function Type
    09110 ------------------------------------------------------------------------
    09111
    09112   This is the type of a pointer to a key's destructor routine.  Keys can be
    09113   associated with a destructor routine when they are created (see
    09114   'OCIThreadKeyInit()').
    09115
    09116   A key's destructor routine will be called whenever a thread that has a
    09117   non-NULL value for the key terminates.
    09118
    09119   The destructor routine returns nothing and takes one parameter.  The
    09120   parameter will be the value that was set for key when the thread
    09121   terminated.
    09122
    09123   The destructor routine is guaranteed to be called on a thread's value
    09124   in the key after the termination of the thread and before process
    09125   termination.  No more precise guarantee can be made about the timing
    09126   of the destructor routine call; thus no code in the process may assume
    09127   any post-condition of the destructor routine.  In particular, the
    09128   destructor is not guaranteed to execute before a join call on the
    09129   terminated thread returns.
    09130
    09131
    09132 1.2.1.4  OCIThreadId - OCIThread Thread ID
    09133 --------------------------------------------
    09134
    09135   Type 'OCIThreadId' is the type that will be used to identify a thread.
    09136   At any given time, no two threads will ever have the same 'OCIThreadId'.
    09137   However, 'OCIThreadId' values can be recycled; i.e., once a thread dies,
    09138   a new thread may be created that has the same 'OCIThreadId' as the one
    09139   that died.  In particular, the thread ID must uniquely identify a thread
    09140   T within a process, and it must be consistent and valid in all threads U
    09141   of the process for which it can be guaranteed that T is running
    09142   concurrently with U.  The thread ID for a thread T must be retrievable
    09143   within thread T.  This will be done via OCIThreadIdGet().
    09144
    09145   The 'OCIThreadId' type supports the concept of a NULL thread ID: the NULL
    09146   thread ID will never be the same as the ID of an actual thread.
    09147
    09148
    09149
    09150 1.2.2 Function prototypes for passive primitives
    09151 --------------------------------------------------
    09152
    09153 1.2.2.1 Mutex functions
    09154 -------------------------
    09155
    09156   OCIThreadMutexInit - OCIThread MuteX Initialize
    09157   -----------------------------------------------
    09158
    09159     Description
    09160
    09161       This allocate and initializes a mutex.  All mutexes must be
    09162       initialized prior to use.
    09163
    09164     Prototype
    09165
    09166       sword OCIThreadMutexInit(dvoid *hndl, OCIError *err,
    09167                                OCIThreadMutex **mutex);
    09168
    09169         hndl(IN/OUT): The OCI environment or session handle.
    09170
    09171         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09172                      is returned, the error is recorded in err and diagnostic
    09173                      information can be obtained by calling OCIErrorGet().
    09174
    09175         mutex(OUT):  The mutex to initialize.
    09176
    09177     Returns
    09178
    09179       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09180
    09181     Notes
    09182
    09183       Multiple threads must not initialize the same mutex simultaneously.
    09184       Also, a mutex must not be reinitialized until it has been destroyed (see
    09185       'OCIThreadMutexDestroy()').
    09186
    09187   OCIThreadMutexDestroy - OCIThread MuteX Destroy
    09188   -----------------------------------------------
    09189
    09190     Description
    09191
    09192       This destroys and deallocate a mutex.  Each mutex must be destroyed
    09193       once it is no longer needed.
    09194
    09195     Prototype
    09196
    09197       sword OCIThreadMutexDestroy(dvoid *hndl, OCIError *err,
    09198                                   OCIThreadMutex **mutex);
    09199
    09200         hndl(IN/OUT): The OCI environment or session handle.
    09201
    09202         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09203                      is returned, the error is recorded in err and diagnostic
    09204                      information can be obtained by calling OCIErrorGet().
    09205
    09206         mutex(IN/OUT):   The mutex to destroy.
    09207
    09208     Returns
    09209
    09210       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09211
    09212     Notes
    09213
    09214       It is not legal to destroy a mutex that is uninitialized or is currently
    09215       held by a thread.  The destruction of a mutex must not occur concurrently
    09216       with any other operations on the mutex.  A mutex must not be used after
    09217       it has been destroyed.
    09218
    09219
    09220   OCIThreadMutexAcquire - OCIThread MuteX Acquire
    09221   -----------------------------------------------
    09222
    09223     Description
    09224
    09225       This acquires a mutex for the thread in which it is called.  If the mutex
    09226       is held by another thread, the calling thread is blocked until it can
    09227       acquire the mutex.
    09228
    09229     Prototype
    09230
    09231      sword OCIThreadMutexAcquire(dvoid *hndl, OCIError *err,
    09232                                  OCIThreadMutex *mutex);
    09233
    09234         hndl(IN/OUT): The OCI environment or session handle.
    09235
    09236         err(IN/OUT): The OCI error handle.  If there is an error, it is
    09237                      recorded in err and this function returns OCI_ERROR.
    09238                      Diagnostic information can be obtained by calling
    09239                      OCIErrorGet().
    09240
    09241         mutex(IN/OUT):   The mutex to acquire.
    09242
    09243     Returns
    09244
    09245       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09246
    09247     Notes
    09248
    09249       It is illegal to attempt to acquire an uninitialized mutex.
    09250
    09251       This function's behavior is undefined if it is used by a thread to
    09252       acquire a mutex that is already held by that thread.
    09253
    09254
    09255
    09256   OCIThreadMutexRelease - OCIThread MuteX Release
    09257   -----------------------------------------------
    09258
    09259     Description
    09260
    09261       This releases a mutex.  If there are any threads blocked on the mutex,
    09262       one of them will acquire it and become unblocked.
    09263
    09264     Prototype
    09265
    09266       sword OCIThreadMutexRelease(dvoid *hndl, OCIError *err,
    09267                                   OCIThreadMutex *mutex);
    09268
    09269         hndl(IN/OUT): The OCI environment or session handle.
    09270
    09271         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09272                      is returned, the error is recorded in err and diagnostic
    09273                      information can be obtained by calling OCIErrorGet().
    09274
    09275         mutex(IN/OUT):   The mutex to release.
    09276
    09277     Returns
    09278
    09279       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09280
    09281     Notes
    09282
    09283       It is illegal to attempt to release an uninitialized mutex.  It is also
    09284       illegal for a thread to release a mutex that it does not hold.
    09285
    09286
    09287   OCIThreadKeyInit - OCIThread KeY Initialize
    09288   -------------------------------------------
    09289
    09290     Description
    09291
    09292       This creates a key.  Each call to this routine allocate and generates
    09293       a new key that is distinct from all other keys.
    09294
    09295     Prototype
    09296
    09297       sword OCIThreadKeyInit(dvoid *hndl, OCIError *err, OCIThreadKey **key,
    09298                              OCIThreadKeyDestFunc destFn);
    09299
    09300         hndl(IN/OUT): The OCI environment or session handle.
    09301
    09302         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09303                      is returned, the error is recorded in err and diagnostic
    09304                      information can be obtained by calling OCIErrorGet().
    09305
    09306         key(OUT):    The 'OCIThreadKey' in which to create the new key.
    09307
    09308         destFn(IN):  The destructor for the key.  NULL is permitted.
    09309
    09310     Returns
    09311
    09312       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09313
    09314     Notes
    09315
    09316       Once this function executes successfully, a pointer to an allocated and
    09317       initialized key is return.  That key can be used with 'OCIThreadKeyGet()'
    09318       and 'OCIThreadKeySet()'.  The initial value of the key will be 'NULL' for
    09319       all threads.
    09320
    09321       It is illegal for this function to be called more than once to create the
    09322       same key (i.e., to be called more than once with the same value for the
    09323       'key' parameter).
    09324
    09325       If the 'destFn' parameter is not NULL, the routine pointed to by 'destFn'
    09326       will be called whenever a thread that has a non-NULL value for the key
    09327       terminates.  The routine will be called with one parameter.  The
    09328       parameter will be the key's value for the thread at the time at which the
    09329       thread terminated.
    09330       If the key does not need a destructor function, pass NULL for 'destFn'.
    09331
    09332
    09333   OCIThreadKeyDestroy - OCIThread KeY DESTROY
    09334   -------------------------------------------
    09335
    09336    Description
    09337
    09338      Destroy and deallocate the key pointed to by 'key'.
    09339
    09340     Prototype
    09341
    09342       sword OCIThreadKeyDestroy(dvoid *hndl, OCIError *err,
    09343                                 OCIThreadKey **key);
    09344
    09345         hndl(IN/OUT): The OCI environment or session handle.
    09346
    09347         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09348                      is returned, the error is recorded in err and diagnostic
    09349                      information can be obtained by calling OCIErrorGet().
    09350
    09351         key(IN/OUT):  The 'OCIThreadKey' in which to destroy the key.
    09352
    09353     Returns
    09354
    09355       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09356
    09357     Notes
    09358
    09359       This is different from the destructor function callback passed to the
    09360       key create routine.  This new destroy function 'OCIThreadKeyDestroy' is
    09361       used to terminate any resources OCI THREAD acquired when it created
    09362       'key'.  [The 'OCIThreadKeyDestFunc' callback type is a key VALUE
    09363       destructor; it does in no way operate on the key itself.]
    09364
    09365       This must be called once the user has finished using the key.  Not
    09366       calling the key destroy function may result in memory leaks.
    09367
    09368
    09369
    09370
    09371 1.2.2.2 Thread Key operations
    09372 -------------------------------
    09373
    09374   OCIThreadKeyGet - OCIThread KeY Get value
    09375   -----------------------------------------
    09376
    09377     Description
    09378
    09379       This gets the calling thread's current value for a key.
    09380
    09381     Prototype
    09382
    09383       sword OCIThreadKeyGet(dvoid *hndl, OCIError *err, OCIThreadKey *key,
    09384                             dvoid **pValue);
    09385
    09386         hndl(IN/OUT): The OCI environment or session handle.
    09387
    09388         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09389                      is returned, the error is recorded in err and diagnostic
    09390                      information can be obtained by calling OCIErrorGet().
    09391
    09392         key(IN):          The key.
    09393
    09394         pValue(IN/OUT):   The location in which to place the thread-specific
    09395                           key value.
    09396
    09397     Returns
    09398
    09399       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09400
    09401     Notes
    09402
    09403       It is illegal to use this function on a key that has not been created
    09404       using 'OCIThreadKeyInit()'.
    09405
    09406       If the calling thread has not yet assigned a value to the key, 'NULL' is
    09407       placed in the location pointed to by 'pValue'.
    09408
    09409
    09410   OCIThreadKeySet - OCIThread KeY Set value
    09411   -----------------------------------------
    09412
    09413     Description
    09414
    09415       This sets the calling thread's value for a key.
    09416
    09417     Prototype
    09418
    09419       sword OCIThreadKeySet(dvoid *hndl, OCIError *err, OCIThreadKey *key,
    09420                             dvoid *value);
    09421
    09422         hndl(IN/OUT): The OCI environment or session handle.
    09423
    09424         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09425                      is returned, the error is recorded in err and diagnostic
    09426                      information can be obtained by calling OCIErrorGet().
    09427
    09428         key(IN/OUT): The key.
    09429
    09430         value(IN):   The thread-specific value to set in the key.
    09431
    09432     Returns
    09433
    09434       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09435
    09436     Notes
    09437
    09438       It is illegal to use this function on a key that has not been created
    09439       using 'OCIThreadKeyInit()'.
    09440
    09441 1.2.2.3  Thread Id
    09442 --------------------
    09443
    09444   OCIThreadIdInit - OCIThread Thread Id INITialize
    09445   --------------------------------------------------
    09446
    09447     Description
    09448
    09449       Allocate and initialize the thread id 'tid'.
    09450
    09451     Prototype
    09452
    09453       sword OCIThreadIdInit(dvoid *hndl, OCIError *err, OCIThreadId **tid);
    09454
    09455         hndl(IN/OUT): The OCI environment or session handle.
    09456
    09457         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09458                      is returned, the error is recorded in err and diagnostic
    09459                      information can be obtained by calling OCIErrorGet().
    09460
    09461         tid (OUT):   Pointer to the thread ID to initialize.
    09462
    09463     Returns
    09464
    09465       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09466
    09467
    09468   OCIThreadIdDestroy - OCIThread Thread Id DESTROY
    09469   --------------------------------------------------
    09470
    09471     Description
    09472
    09473       Destroy and deallocate the thread id 'tid'.
    09474
    09475     Prototype
    09476
    09477       sword OCIThreadIdDestroy(dvoid *hndl, OCIError *err, OCIThreadId **tid);
    09478
    09479         hndl(IN/OUT): The OCI environment or session handle.
    09480
    09481         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09482                      is returned, the error is recorded in err and diagnostic
    09483                      information can be obtained by calling OCIErrorGet().
    09484
    09485         tid(IN/OUT):        Pointer to the thread ID to destroy.
    09486
    09487     Returns
    09488
    09489       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09490
    09491     Note
    09492
    09493       'tid' should be initialized by OCIThreadIdInit().
    09494
    09495
    09496   OCIThreadIdSet - OCIThread Thread Id Set
    09497   -----------------------------------------
    09498
    09499     Description
    09500
    09501       This sets one 'OCIThreadId' to another.
    09502
    09503     Prototype
    09504
    09505       sword OCIThreadIdSet(dvoid *hndl, OCIError *err,
    09506                            OCIThreadId *tidDest,
    09507                            OCIThreadId *tidSrc);
    09508
    09509         hndl(IN/OUT): The OCI environment or session handle.
    09510
    09511         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09512                      is returned, the error is recorded in err and diagnostic
    09513                      information can be obtained by calling OCIErrorGet().
    09514
    09515         tidDest(OUT):   This should point to the location of the 'OCIThreadId'
    09516                         to be set to.
    09517
    09518         tidSrc(IN):     This should point to the 'OCIThreadId' to set from.
    09519
    09520     Returns
    09521
    09522       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09523
    09524     Notes
    09525
    09526       'tid' should be initialized by OCIThreadIdInit().
    09527
    09528
    09529   OCIThreadIdSetNull - OCIThread Thread Id Set Null
    09530   ---------------------------------------------------------
    09531
    09532     Description
    09533
    09534       This sets the NULL thread ID to a given 'OCIThreadId'.
    09535
    09536     Prototype
    09537
    09538       sword OCIThreadIdSetNull(dvoid *hndl, OCIError *err,
    09539                                OCIThreadId *tid);
    09540
    09541         hndl(IN/OUT): The OCI environment or session handle.
    09542
    09543         err(IN/OUT): The OCI error handle.  If there is an error, it is
    09544                      recorded in err and this function returns OCI_ERROR.
    09545                      Diagnostic information can be obtained by calling
    09546                      OCIErrorGet().
    09547
    09548         tid(OUT):    This should point to the 'OCIThreadId' in which to put
    09549                      the NULL thread ID.
    09550
    09551     Returns
    09552
    09553       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09554
    09555     Notes
    09556
    09557       'tid' should be initialized by OCIThreadIdInit().
    09558
    09559
    09560   OCIThreadIdGet - OCIThread Thread Id Get
    09561   ------------------------------------------
    09562
    09563     Description
    09564
    09565       This retrieves the 'OCIThreadId' of the thread in which it is called.
    09566
    09567     Prototype
    09568
    09569       sword OCIThreadIdGet(dvoid *hndl, OCIError *err,
    09570                            OCIThreadId *tid);
    09571
    09572         hndl(IN/OUT): The OCI environment or session handle.
    09573
    09574         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09575                      is returned, the error is recorded in err and diagnostic
    09576                      information can be obtained by calling OCIErrorGet().
    09577
    09578         tid(OUT):    This should point to the location in which to place the
    09579                      ID of the calling thread.
    09580
    09581     Returns
    09582
    09583       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09584
    09585     Notes
    09586
    09587       'tid' should be initialized by OCIThreadIdInit().
    09588
    09589       When OCIThread is used in a single-threaded environment,
    09590       OCIThreadIdGet() will always place the same value in the location
    09591       pointed to by 'tid'.  The exact value itself is not important.  The
    09592       important thing is that it is not the same as the NULL thread ID and
    09593       that it is always the same value.
    09594
    09595
    09596   OCIThreadIdSame - OCIThread Thread Ids Same?
    09597   ----------------------------------------------
    09598
    09599     Description
    09600
    09601       This determines whether or not two 'OCIThreadId's represent the same
    09602       thread.
    09603
    09604     Prototype
    09605
    09606       sword OCIThreadIdSame(dvoid *hndl, OCIError *err,
    09607                             OCIThreadId *tid1, OCIThreadId *tid2,
    09608                             boolean *result);
    09609
    09610         hndl(IN/OUT): The OCI environment or session handle.
    09611
    09612         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09613                      is returned, the error is recorded in err and diagnostic
    09614                      information can be obtained by calling OCIErrorGet().
    09615
    09616         tid1(IN):   Pointer to the first 'OCIThreadId'.
    09617
    09618         tid2(IN):   Pointer to the second 'OCIThreadId'.
    09619
    09620         result(IN/OUT): Pointer to the result.
    09621
    09622     Returns
    09623
    09624       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09625
    09626     Notes
    09627
    09628       If 'tid1' and 'tid2' represent the same thread, 'result' is set to TRUE.
    09629       Otherwise, 'result' is set to FALSE.
    09630
    09631       'result' is set to TRUE if both 'tid1' and 'tid2' are the NULL thread ID.
    09632
    09633       'ti1d' and 'tid2' should be initialized by OCIThreadIdInit().
    09634
    09635
    09636   OCIThreadIdNull - OCIThread Thread Id NULL?
    09637   ---------------------------------------------
    09638
    09639     Description
    09640
    09641       This determines whether or not a given 'OCIThreadId' is the NULL thread
    09642       ID.
    09643
    09644     Prototype
    09645
    09646       sword OCIThreadIdNull(dvoid *hndl, OCIError *err,
    09647                             OCIThreadId *tid,
    09648                             boolean *result);
    09649
    09650         hndl(IN/OUT): The OCI environment or session handle.
    09651
    09652         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09653                      is returned, the error is recorded in err and diagnostic
    09654                      information can be obtained by calling OCIErrorGet().
    09655
    09656         tid(IN):    Pointer to the 'OCIThreadId' to check.
    09657
    09658         result(IN/OUT): Pointer to the result.
    09659
    09660     Returns
    09661
    09662       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09663
    09664     Notes
    09665
    09666       If 'tid' is the NULL thread ID, 'result' is set to TRUE.  Otherwise,
    09667       'result' is set to FALSE.
    09668
    09669       'tid' should be initialized by OCIThreadIdInit().
    09670
    09671
    09672 1.3 Active Threading Primitives
    09673 =================================
    09674
    09675 The active threading primitives deal with the manipulation of actual
    09676 threads.  Because the specifications of most of these primitives require
    09677 that it be possible to have multiple threads, they work correctly only in
    09678 the enabled OCIThread; In the disabled OCIThread, they always return
    09679 failure.  The exception is OCIThreadHandleGet(); it may be called in a
    09680 single-threaded environment, in which case it will have no effect.
    09681
    09682 Active primitives should only be called by code running in a multi-threaded
    09683 environment.  You can call OCIThreadIsMulti() to determine whether the
    09684 environment is multi-threaded or single-threaded.
    09685
    09686
    09687 1.3.1  Types
    09688 --------------
    09689
    09690 1.3.1.1    OCIThreadHandle - OCIThread Thread Handle
    09691 ------------------------------------------------------
    09692
    09693   Type 'OCIThreadHandle' is used to manipulate a thread in the active
    09694   primitives:  OCIThreadJoin()and OCIThreadClose().  A thread handle opened by
    09695   OCIThreadCreate() must be closed in a matching call to
    09696   OCIThreadClose().  A thread handle is invalid after the call to
    09697   OCIThreadClose().
    09698
    09699   The distinction between a thread ID and a thread handle in OCIThread usage
    09700   follows the distinction between the thread ID and the thread handle on
    09701   Windows NT.  On many platforms, the underlying native types are the same.
    09702
    09703
    09704 1.3.2  Functions
    09705 ------------------
    09706
    09707   OCIThreadHndInit - OCIThread HaNDle Initialize
    09708   ----------------------------------------------
    09709
    09710     Description
    09711
    09712       Allocate and initialize the thread handle.
    09713
    09714     Prototype
    09715
    09716       sword OCIThreadHndInit(dvoid *hndl, OCIError *err,
    09717                              OCIThreadHandle **thnd);
    09718
    09719         hndl(IN/OUT): The OCI environment or session handle.
    09720
    09721         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09722                      is returned, the error is recorded in err and diagnostic
    09723                      information can be obtained by calling OCIErrorGet().
    09724
    09725         thnd(OUT):   The address of pointer to the thread handle to initialize.
    09726
    09727     Returns
    09728
    09729       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09730
    09731
    09732   OCIThreadHndDestroy - OCIThread HaNDle Destroy
    09733   ----------------------------------------------
    09734
    09735     Description
    09736
    09737       Destroy and deallocate the thread handle.
    09738
    09739     Prototype
    09740
    09741       sword OCIThreadHndDestroy(dvoid *hndl, OCIError *err,
    09742                                 OCIThreadHandle **thnd);
    09743
    09744         hndl(IN/OUT): The OCI environment or session handle.
    09745
    09746         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09747                      is returned, the error is recorded in err and diagnostic
    09748                      information can be obtained by calling OCIErrorGet().
    09749
    09750         thnd(IN/OUT):  The address of pointer to the thread handle to destroy.
    09751
    09752     Returns
    09753
    09754       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09755
    09756     Notes
    09757
    09758       'thnd' should be initialized by OCIThreadHndInit().
    09759
    09760
    09761   OCIThreadCreate - OCIThread Thread Create
    09762   -----------------------------------------
    09763
    09764     Description
    09765
    09766       This creates a new thread.
    09767
    09768     Prototype
    09769
    09770       sword OCIThreadCreate(dvoid *hndl, OCIError *err,
    09771                             void (*start)(dvoid *), dvoid *arg,
    09772                             OCIThreadId *tid, OCIThreadHandle *tHnd);
    09773
    09774         hndl(IN/OUT): The OCI environment or session handle.
    09775
    09776         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09777                      is returned, the error is recorded in err and diagnostic
    09778                      information can be obtained by calling OCIErrorGet().
    09779
    09780         start(IN):    The function in which the new thread should begin
    09781                       execution.
    09782
    09783         arg(IN):      The argument to give the function pointed to by 'start'.
    09784
    09785         tid(IN/OUT):  If not NULL, gets the ID for the new thread.
    09786
    09787         tHnd(IN/OUT): If not NULL, gets the handle for the new thread.
    09788
    09789     Returns
    09790
    09791       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09792
    09793     Notes
    09794
    09795       The new thread will start by executing a call to the function pointed
    09796       to by 'start' with the argument given by 'arg'.  When that function
    09797       returns, the new thread will terminate.  The function should not
    09798       return a value and should accept one parameter, a 'dvoid *'.
    09799
    09800       The call to OCIThreadCreate() must be matched by a call to
    09801       OCIThreadClose() if and only if tHnd is non-NULL.
    09802
    09803       If tHnd is NULL, a thread ID placed in *tid will not be valid in the
    09804       calling thread because the timing of the spawned thread's termination
    09805       is unknown.
    09806
    09807       'tid' should be initialized by OCIThreadIdInit().
    09808
    09809       'thnd' should be initialized by OCIThreadHndInit().
    09810
    09811
    09812
    09813   OCIThreadJoin - OCIThread Thread Join
    09814   -------------------------------------
    09815
    09816     Description
    09817
    09818       This function allows the calling thread to 'join' with another thread.
    09819       It blocks the caller until the specified thread terminates.
    09820
    09821     Prototype
    09822
    09823       sword OCIThreadJoin(dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd);
    09824
    09825         hndl(IN/OUT): The OCI environment or session handle.
    09826
    09827         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09828                      is returned, the error is recorded in err and diagnostic
    09829                      information can be obtained by calling OCIErrorGet().
    09830
    09831         tHnd(IN):    The 'OCIThreadHandle' of the thread to join with.
    09832
    09833     Returns
    09834
    09835       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09836
    09837     Notes
    09838
    09839       'thnd' should be initialized by OCIThreadHndInit().
    09840
    09841       The result of multiple threads all trying to join with the same thread is
    09842       undefined.
    09843
    09844
    09845   OCIThreadClose - OCIThread Thread Close
    09846   ---------------------------------------
    09847
    09848    Description
    09849
    09850      This function should be called to close a thread handle.
    09851
    09852    Prototype
    09853
    09854      sword OCIThreadClose(dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd);
    09855
    09856         hndl(IN/OUT): The OCI environment or session handle.
    09857
    09858         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09859                      is returned, the error is recorded in err and diagnostic
    09860                      information can be obtained by calling OCIErrorGet().
    09861
    09862         tHnd(IN/OUT):    The OCIThread thread handle to close.
    09863
    09864    Returns
    09865
    09866       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09867
    09868    Notes
    09869
    09870       'thnd' should be initialized by OCIThreadHndInit().
    09871
    09872       Both thread handle and the thread ID that was returned by the same call
    09873       to OCIThreadCreate() are invalid after the call to OCIThreadClose().
    09874
    09875
    09876
    09877   OCIThreadHandleGet - OCIThread Thread Get Handle
    09878   ------------------------------------------------
    09879
    09880     Description
    09881
    09882       Retrieve the 'OCIThreadHandle' of the thread in which it is called.
    09883
    09884     Prototype
    09885
    09886       sword OCIThreadHandleGet(dvoid *hndl, OCIError *err,
    09887                                OCIThreadHandle *tHnd);
    09888
    09889         hndl(IN/OUT): The OCI environment or session handle.
    09890
    09891         err(IN/OUT): The OCI error handle.  If there is an error and OCI_ERROR
    09892                      is returned, the error is recorded in err and diagnostic
    09893                      information can be obtained by calling OCIErrorGet().
    09894
    09895         tHnd(IN/OUT):      If not NULL, the location to place the thread
    09896                            handle for the thread.
    09897
    09898      Returns
    09899
    09900       OCI_SUCCESS, OCI_ERROR or OCI_INVALID_HANDLE.
    09901
    09902     Notes
    09903
    09904       'thnd' should be initialized by OCIThreadHndInit().
    09905
    09906       The thread handle 'tHnd' retrieved by this function must be closed
    09907       with OCIThreadClose() and destroyed by OCIThreadHndDestroy() after it
    09908       is used.
    09909
    09910
    09911
    09912
    09913 1.4 Using OCIThread
    09914 =====================
    09915
    09916 This section summarizes some of the more important details relating to the use
    09917 of OCIThread.
    09918
    09919   * Process initialization
    09920
    09921     OCIThread only requires that the process initialization function
    09922     ('OCIThreadProcessInit()') be called when OCIThread is being used in a
    09923     multi-threaded application.  Failing to call 'OCIThreadProcessInit()' in
    09924     a single-threaded application is not an error.
    09925
    09926   * OCIThread initialization
    09927
    09928     Separate calls to 'OCIThreadInit()' will all return the same OCIThread
    09929     context.
    09930
    09931     Also, remember that each call to 'OCIThreadInit()' must eventually be
    09932     matched by a call to 'OCIThreadTerm()'.
    09933
    09934   * Active vs. Passive Threading primitives
    09935
    09936     OCIThread client code written without using any active primitives can be
    09937     compiled and used without change on both single-threaded and
    09938     multi-threaded platforms.
    09939
    09940     OCIThread client code written using active primitives will only work
    09941     correctly on multi-threaded platforms.  In order to write a version of the
    09942     same application to run on single-threaded platform, it is necessary to
    09943     branch the your code, whether by branching versions of the source file or
    09944     by branching at runtime with the OCIThreadIsMulti() call.
    09945
    09946 ******************************************************************************/
    09947
    09948 /*****************************************************************************
    09949                          ACTUAL PROTOTYPE DECLARATIONS
    09950 ******************************************************************************/
    09951
    09952 void OCIThreadProcessInit();
    09953
    09954 sword OCIThreadInit(dvoid *hndl, OCIError *err);
    09955
    09956 sword OCIThreadTerm(dvoid *hndl, OCIError *err);
    09957
    09958 boolean OCIThreadIsMulti();
    09959
    09960 sword OCIThreadMutexInit(dvoid *hndl, OCIError *err,
    09961                          OCIThreadMutex **mutex);
    09962
    09963 sword OCIThreadMutexDestroy(dvoid *hndl, OCIError *err,
    09964                             OCIThreadMutex **mutex);
    09965
    09966 sword OCIThreadMutexAcquire(dvoid *hndl, OCIError *err,
    09967                             OCIThreadMutex *mutex);
    09968
    09969 sword OCIThreadMutexRelease(dvoid *hndl, OCIError *err,
    09970                             OCIThreadMutex *mutex);
    09971
    09972 sword OCIThreadKeyInit(dvoid *hndl, OCIError *err, OCIThreadKey **key,
    09973                        OCIThreadKeyDestFunc destFn);
    09974
    09975 sword OCIThreadKeyDestroy(dvoid *hndl, OCIError *err,
    09976                           OCIThreadKey **key);
    09977
    09978 sword OCIThreadKeyGet(dvoid *hndl, OCIError *err, OCIThreadKey *key,
    09979                       dvoid **pValue);
    09980
    09981 sword OCIThreadKeySet(dvoid *hndl, OCIError *err, OCIThreadKey *key,
    09982                       dvoid *value);
    09983
    09984 sword OCIThreadIdInit(dvoid *hndl, OCIError *err, OCIThreadId **tid);
    09985
    09986 sword OCIThreadIdDestroy(dvoid *hndl, OCIError *err, OCIThreadId **tid);
    09987
    09988 sword OCIThreadIdSet(dvoid *hndl, OCIError *err,
    09989                      OCIThreadId *tidDest, OCIThreadId *tidSrc);
    09990
    09991 sword OCIThreadIdSetNull(dvoid *hndl, OCIError *err, OCIThreadId *tid);
    09992
    09993 sword OCIThreadIdGet(dvoid *hndl, OCIError *err, OCIThreadId *tid);
    09994
    09995 sword OCIThreadIdSame(dvoid *hndl, OCIError *err,
    09996                       OCIThreadId *tid1, OCIThreadId *tid2,
    09997                       boolean *result);
    09998
    09999 sword OCIThreadIdNull(dvoid *hndl, OCIError *err,
    10000                       OCIThreadId *tid, boolean *result);
    10001
    10002 sword OCIThreadHndInit(dvoid *hndl, OCIError *err, OCIThreadHandle **thnd);
    10003
    10004 sword OCIThreadHndDestroy(dvoid *hndl, OCIError *err, OCIThreadHandle **thnd);
    10005
    10006 sword OCIThreadCreate(dvoid *hndl, OCIError *err,
    10007                       void (*start)(dvoid *), dvoid *arg,
    10008                       OCIThreadId *tid, OCIThreadHandle *tHnd);
    10009
    10010 sword OCIThreadJoin(dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd);
    10011
    10012 sword OCIThreadClose(dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd);
    10013
    10014 sword OCIThreadHandleGet(dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd);
    10015 /*----------------- End OCI Thread interface Extensions ---------------------*/
    10016
    10017 /*------------------ Begin OCI Row Callback Interfaces ----------------------*/
    10018
    10019 typedef sword (*OCIBindRowCallback)(dvoid *ctx);
    10020 typedef sword (*OCIFetchRowCallback)(dvoid *ctx);
    10021
    10022 /*------------------ Begin OCI Row Callback Interfaces ----------------------*/
    10023
    10024 /*--------------- Begin OCI Client Notification Interfaces ------------------*/
    10025
    10026 typedef ub4 (*OCISubscriptionNotify)(dvoid *ctx, OCISubscription *subscrhp,
    10027                                      dvoid *pay, ub4 payl,
    10028                                      dvoid *desc, ub4 mode);
    10029
    10030 sword OCISubscriptionRegister(OCISvcCtx *svchp, OCISubscription **subscrhpp,
    10031                               ub2 count, OCIError *errhp, ub4 mode);
    10032
    10033
    10034 sword OCISubscriptionPost(OCISvcCtx *svchp, OCISubscription **subscrhpp,
    10035                               ub2 count, OCIError *errhp, ub4 mode);
    10036
    10037 sword OCISubscriptionUnRegister(OCISvcCtx *svchp, OCISubscription *subscrhp,
    10038                               OCIError *errhp, ub4 mode);
    10039
    10040 sword OCISubscriptionDisable(OCISubscription *subscrhp,
    10041                            OCIError *errhp, ub4 mode);
    10042
    10043 sword OCISubscriptionEnable(OCISubscription *subscrhp,
    10044                           OCIError *errhp, ub4 mode);
    10045
    10046 /*------------------- End OCI Publish/Subscribe Interfaces ------------------*/
    10047
    10048 /*----------------- Extensions to Datetime interfaces -----------------------*/
    10049 /*--------------------- Actual Prototypes -----------------------------------*/
    10050 sword OCIDateTimeGetTime(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
    10051                          ub1 *hr, ub1 *mm, ub1 *ss, ub4 *fsec);
    10052
    10053 sword OCIDateTimeGetDate(dvoid *hndl, OCIError *err,  CONST OCIDateTime *date,
    10054                  sb2 *yr, ub1 *mnth, ub1 *dy );
    10055
    10056 sword OCIDateTimeGetTimeZoneOffset(dvoid *hndl,OCIError *err,
    10057                                    CONST OCIDateTime *datetime,
    10058                                    sb1 *hr,sb1 *mm);
    10059
    10060 sword OCIDateTimeConstruct(dvoid  *hndl,OCIError *err,OCIDateTime *datetime,
    10061                sb2 yr,ub1 mnth,ub1 dy,ub1 hr,ub1 mm,ub1 ss,ub4 fsec,
    10062                OraText  *timezone,size_t timezone_length);
    10063
    10064 sword OCIDateTimeSysTimeStamp(dvoid *hndl, OCIError *err,
    10065                               OCIDateTime *sys_date );
    10066
    10067 sword OCIDateTimeAssign(dvoid *hndl, OCIError *err, CONST OCIDateTime *from,
    10068                        OCIDateTime *to);
    10069
    10070 sword OCIDateTimeToText(dvoid *hndl, OCIError *err, CONST OCIDateTime *date,
    10071                         CONST OraText *fmt, ub1 fmt_length, ub1 fsprec,
    10072                         CONST OraText *lang_name, size_t lang_length,
    10073                         ub4 *buf_size, OraText *buf );
    10074
    10075 sword OCIDateTimeFromText(dvoid *hndl, OCIError *err, CONST OraText *date_str,
    10076              size_t dstr_length, CONST OraText *fmt, ub1 fmt_length,
    10077              CONST OraText *lang_name, size_t lang_length, OCIDateTime *date );
    10078
    10079 sword OCIDateTimeCompare(dvoid *hndl, OCIError *err, CONST OCIDateTime *date1,
    10080                      CONST OCIDateTime *date2,  sword *result );
    10081
    10082 sword OCIDateTimeCheck(dvoid *hndl, OCIError *err, CONST OCIDateTime *date,
    10083                  ub4 *valid );
    10084
    10085 sword OCIDateTimeConvert(dvoid *hndl, OCIError *err, OCIDateTime *indate,
    10086                                 OCIDateTime *outdate);
    10087
    10088 sword OCIDateTimeSubtract(dvoid *hndl, OCIError *err, OCIDateTime *indate1,
    10089                 OCIDateTime *indate2,    OCIInterval *inter);
    10090
    10091 sword OCIDateTimeIntervalAdd(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
    10092          OCIInterval *inter, OCIDateTime *outdatetime);
    10093
    10094 sword OCIDateTimeIntervalSub(dvoid *hndl, OCIError *err, OCIDateTime *datetime,
    10095          OCIInterval *inter, OCIDateTime *outdatetime);
    10096
    10097 sword OCIIntervalSubtract(dvoid *hndl, OCIError *err, OCIInterval *minuend,
    10098                             OCIInterval *subtrahend, OCIInterval *result );
    10099
    10100 sword OCIIntervalAdd(dvoid *hndl, OCIError *err, OCIInterval *addend1,
    10101                         OCIInterval *addend2, OCIInterval *result );
    10102
    10103 sword OCIIntervalMultiply(dvoid *hndl, OCIError *err, CONST OCIInterval *inter,
    10104                         OCINumber *nfactor, OCIInterval *result );
    10105
    10106 sword OCIIntervalDivide(dvoid *hndl, OCIError *err, OCIInterval *dividend,
    10107                 OCINumber *divisor, OCIInterval *result );
    10108
    10109 sword OCIIntervalCompare(dvoid *hndl, OCIError *err, OCIInterval *inter1,
    10110                         OCIInterval *inter2, sword *result );
    10111
    10112 sword OCIIntervalFromNumber(dvoid *hndl, OCIError *err, OCIInterval *inter,
    10113                         OCINumber *number);
    10114
    10115 sword OCIIntervalFromText( dvoid *hndl, OCIError *err, CONST OraText *inpstr,
    10116                 size_t str_len, OCIInterval *result );
    10117
    10118 sword OCIIntervalToText( dvoid *hndl, OCIError *err, CONST OCIInterval *inter,
    10119                          ub1 lfprec, ub1 fsprec,
    10120                         OraText *buffer, size_t buflen, size_t *resultlen );
    10121
    10122 sword OCIIntervalToNumber(dvoid *hndl, OCIError *err,CONST OCIInterval *inter,
    10123                         OCINumber *number);
    10124
    10125 sword OCIIntervalCheck(dvoid *hndl, OCIError *err, CONST OCIInterval *interval,
    10126                          ub4 *valid );
    10127
    10128 sword OCIIntervalAssign(dvoid *hndl, OCIError *err, CONST OCIInterval *ininter,
    10129                         OCIInterval *outinter );
    10130
    10131 sword OCIIntervalSetYearMonth(dvoid *hndl, OCIError *err, sb4 yr, sb4 mnth,
    10132                         OCIInterval *result );
    10133
    10134 sword OCIIntervalGetYearMonth(dvoid *hndl, OCIError *err, sb4 *yr, sb4 *mnth,
    10135                         CONST OCIInterval *result );
    10136
    10137 sword OCIIntervalSetDaySecond(dvoid *hndl, OCIError *err, sb4 dy, sb4 hr,
    10138                         sb4 mm, sb4 ss, sb4 fsec, OCIInterval *result );
    10139
    10140 sword OCIIntervalGetDaySecond(dvoid *hndl, OCIError *err, sb4 *dy, sb4 *hr,
    10141                      sb4 *mm, sb4 *ss, sb4 *fsec, CONST OCIInterval *result );
    10142
    10143 sword OCIDateTimeToArray(dvoid *hndl, OCIError *err,
    10144                          CONST OCIDateTime *datetime, CONST OCIInterval *reftz,
    10145                          ub1 *outarray, ub4 *len, ub1 fsprec);
    10146
    10147 sword OCIDateTimeFromArray(dvoid *hndl, OCIError *err, ub1 *inarray, ub4 len,
    10148                            ub1 type, OCIDateTime *datetime,
    10149                            CONST OCIInterval *reftz, ub1 fsprec);
    10150
    10151 sword OCIDateTimeGetTimeZoneName(dvoid *hndl, OCIError *err,
    10152                                  CONST OCIDateTime *datetime,
    10153                                  ub1 *buf, ub4 *buflen);
    10154
    10155 sword OCIIntervalFromTZ(dvoid *hndl, OCIError *err, CONST oratext *inpstring,
    10156                         size_t str_len, OCIInterval *result);
    10157
    10158 /*----------------- End Datetime interface Extensions -----------------------*/
    10159
    10160 /*----------------- Connection Pooling prototypes ---------------------------*/
    10161 sword OCIConnectionPoolCreate(OCIEnv *envhp, OCIError *errhp, OCICPool *poolhp,
    10162                               OraText **poolName, sb4 *poolNameLen,
    10163                               CONST OraText *dblink, sb4 dblinkLen,
    10164                               ub4 connMin, ub4 connMax, ub4 connIncr,
    10165                               CONST OraText *poolUserName, sb4 poolUserLen,
    10166                               CONST OraText *poolPassword, sb4 poolPassLen,
    10167                               ub4 mode);
    10168
    10169 sword OCIConnectionPoolDestroy(OCICPool *poolhp,
    10170                                OCIError *errhp, ub4 mode);
    10171
    10172 /*----------------- End Connection Pooling prototypes -----------------------*/
    10173
    10174 /*-------------------- Session Pooling prototypes ---------------------------*/
    10175
    10176 sword OCISessionPoolCreate (OCIEnv *envhp, OCIError *errhp, OCISPool *spoolhp,
    10177                             OraText **poolName, ub4 *poolNameLen,
    10178                             CONST OraText *connStr, ub4 connStrLen,
    10179                             ub4 sessMin, ub4 sessMax, ub4 sessIncr,
    10180                             OraText *userid, ub4 useridLen,
    10181                             OraText *password, ub4 passwordLen,
    10182                             ub4 mode);
    10183
    10184 sword OCISessionPoolDestroy (OCISPool *spoolhp,
    10185                              OCIError *errhp,
    10186                              ub4 mode);
    10187
    10188 sword OCISessionGet (OCIEnv *envhp, OCIError *errhp, OCISvcCtx **svchp,
    10189                      OCIAuthInfo *authhp,
    10190                      OraText *poolName, ub4 poolName_len,
    10191                      CONST OraText *tagInfo, ub4 tagInfo_len,
    10192                      OraText **retTagInfo, ub4 *retTagInfo_len,
    10193                      boolean *found, ub4 mode);
    10194
    10195 sword OCISessionRelease (OCISvcCtx *svchp, OCIError *errhp,
    10196                          OraText *tag, ub4 tag_len,
    10197                          ub4 mode);
    10198
    10199 /*-------------------- End Session Pooling prototypes -----------------------*/
    10200
    10201 /*-------------------------------- OCIPing ----------------------------------*/
    10202 sword OCIPing (OCISvcCtx *svchp, OCIError *errhp);
    10203
    10204
    10205 /*----------------- Kerberos Authentication prototypes ----------------------*/
    10206
    10207 sword OCIKerbAttrSet(OCISession *trgthndlp, ub4 cred_use, ub1 *ftgt_ticket,
    10208                      ub4 ticket_len, ub1 *session_key, ub4 skey_len,
    10209                      ub2 ftgt_keytype, ub4 ftgt_ticket_flags,
    10210                      sb4 ftgt_auth_time, sb4 ftgt_start_time,
    10211                      sb4 ftgt_end_time, sb4 ftgt_renew_time,
    10212                      text *ftgt_client_principal,
    10213                      ub4 ftgt_client_principal_len, text *ftgt_client_realm,
    10214                      ub4 ftgt_client_realm_len, OCIError *errhp);
    10215
    10216 /*------------------- End Kerberos Authentication prototypes ----------------*/
    10217
    10218 /*---------------------------------------------------------------------------
    10219                           PRIVATE FUNCTIONS
    10220   ---------------------------------------------------------------------------*/
    10221
    10222             /* the following functions are depracated and should not be used */
    10223 #ifdef NEVER
    10224 sword   OCIStmtBindByPos  (OCIStmt *stmtp, OCIBind *bindp, OCIError *errhp,
    10225                   ub4 position, dvoid *valuep, sb4 value_sz,
    10226                   ub2 dty, dvoid *indp, ub2 *alenp, ub2 *rcodep,
    10227                   ub4 maxarr_len, ub4 *curelep, ub4 mode);
    10228
    10229
    10230 sword   OCIStmtBindByName  (OCIStmt *stmtp, OCIBind *bindp, OCIError *errhp,
    10231                   CONST OraText *placeholder, sb4 placeh_len, dvoid *valuep,
    10232                   sb4 value_sz, ub2 dty, dvoid *indp, ub2 *alenp,
    10233                   ub2 *rcodep, ub4 maxarr_len, ub4 *curelep, ub4 mode);
    10234
    10235 sword   ocidefn  (OCIStmt *stmtp, OCIDefine *defnp, OCIError *errhp,
    10236                   ub4 position, dvoid *valuep, sb4 value_sz, ub2 dty,
    10237                   dvoid *indp, ub2 *rlenp, ub2 *rcodep, ub4 mode);
    10238 #endif /* NEVER */
    10239
    10240 #endif                                                       /* OCIAP_ORACLE */

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines