| 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/ociap.h
Go to the documentation of this file.

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

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines