orl.h

SQLAPI C/C++ 连接Oracle 数据库！

/* Copyright (c) 1993, 1995, 1996, 1997, 1998, 1999 by Oracle Corporation */

/*
  Author:             Srinath Krishnaswamy
  Date:               11/24/93
  Source documents:   "Functional Specification for C Language Mapping of
                      OTS Types, Object Management Subsystem", "Oracle C
                      Coding Standards version 2.2", and the header file
		      template
  Rule sets:          the generic and .h file rule sets
  Quality status:     not exited
  Identification tag: [ one or more letters to identify the .h file ]
  Revision code:      11/24/93
 
  NAME

    ORL - ORacle's external C Language interface to primitive OTS types
 
  DESCRIPTION

    This header file contains C langauge interface to the OTS primitive
    types. The interface includes C mapping of OTS primitive types and
    the prototype of the pre-defined operations on the primitive types.
 
    ***********************************************************************
    *** NOTE: The OCI functions for objects requires the                ***
    ***       application to be running in OBJECT mode. That is, during ***
    ***       process initialization OCIInitialize(), the mode          ***
    ***       specified should be OBJECT mode.                          ***
    **                OCIInitialize(OCI_OBJECT, ..);                    ***
    ***********************************************************************

  RELATED DOCUMENTS

    [1] Krishnaswamy, Srinath and Nguyen, Tin A., "Functional Specification
        for C Language Mapping of OTS Types, Object Management Subsystem",
	March 1994.
    [2] Nguyen, Tin A., "The Open Type System", Oracle Corporation,
	February 1994.
    [3] Klein, Jonathan D., "Large Field Management", Oracle Corporation,
	October 1993.
 
  PUBLIC FUNCTIONS
 
    OCI - OCI functions to manipulate Oracle Number, float and decimal
      ARITHMETIC
	OCINumberInc - OCINumber INCrement (optimized)
	OCINumberDec - OCINumber DECrement (optimized)
        OCINumberAdd - OCINumber ADD numbers
        OCINumberSub - OCINumber SUBtract numbers
        OCINumberMul - OCINumber MULtiply numbers
        OCINumberDiv - OCINumber DIVide numbers
	OCINumberMod - OCINumber MODulo division
	OCINumberIntPower - OCINumber integer PoWeR
	OCINumberShift - OCINumber decimal ShiFT number
	OCINumberNeg - OCINumber NEGate number
	OCINumberAbs - OCINumber ABSolute value
	OCINumberCeil - OCINumber CEiling of number
	OCINumberFloor - OCINumber FLooR of number
	OCINumberSqrt - OCINumber SQuare Root of number
	OCINumberSign - OCINumber get SIGN of number
      NATIVE TYPE CONVERSION
        OCINumberToInt  - OCINumber convert number TO machine-format Integer
        OCINumberFromInt - OCINumber convert machine-format Integer TO Number
        OCINumberToReal  - OCINumber convert number TO machine-format Real
        OCINumberFromReal - OCINumber convert machine-format Real TO Number
      TEXT STRING CONVERSION
        OCINumberToText  - OCINumber convert number TO String
        OCINumberFromText - OCINumber convert String TO Number
      COMPARISON
        OCINumberCmp - OCINumber CoMPare numbers
	OCINumberIsZero - OCINumber comparison with ZERo
	OCINumberIsInt - OCINumber Is an Integer
      ASSIGNMENT
        OCINumberAssign - OCINumber ASsiGn number
        OCINumberSetZero - OCINumber Set number to Zero value
	OCINumberSetPi - OCINumber Set number to Pi
      ROUNDING
        OCINumberTrunc - OCINumber TRUncate an Oracle number
        OCINumberRound - OCINumber ROUnd number
	OCINumberPrec - OCINumber round to Precision digits
      TRANSCENDENTAL
	OCINumberSin - OCINumber SINe
	OCINumberArcSin - OCINumber Arc SINe
	OCINumberHypSin - OCINumber SiNe Hyperbolic
	OCINumberCos - OCINumber COSine
	OCINumberArcCos - OCINumber Arc COSine
	OCINumberHypCos - OCINumber CoSine Hyperbolic
	OCINumberTan - OCINumber TANgent
	OCINumberArcTan - OCINumber Arc TANgent
	OCINumberArcTan2 - OCINumber Arc TaNgent 2
	OCINumberHypTan - OCINumber TaNgent Hyperbolic
	OCINumberPower - OCINumber arbitrary Base EXponentiation
	OCINumberExp - OCINumber EXPonentiation to base e
	OCINumberLn  - OCINumber Logarithm Natural
	OCINumberLog - OCINumber LOGarithm to arbitrary base

    OCIDate - OCI functions to manipulate OCI Date
      OCIDateToExternal - OCIDate convert date to external form
      OCIDateFromExternal - OCIDate convert external form of date into OCIDate
      OCIDateAssign - OCIDate Assignment
      OCIDateToText  - OCIDate convert date TO String
      OCIDateFromText - OCIDate convert String TO Date
      OCIDateZoneToZone - OCIDate convert date from one time 
                        Zone TO another Zone
      OCIDateCompare - OCIDate CoMPare dates
      OCIDateAddMonths - OCIDate ADd or subtract Months
      OCIDateAddDays - OCIDate ADd or subtract Days
      OCIDateLastDay - OCIDate get date of LaST day of month
      OCIDateDaysBetween - OCIDate get number of days BeTWeen two dates
      OCIDateNextDay - OCIDate get date of Next DaY
      OCIDateCheck - OCIDate CHecK if the given date is valid
      OCIDateSysDate - OCIDate get current SYStem date and time

    OCIString - OCI String functions to manipulate Variable-length string
      OCIStringAssign - OCIString Assign string to string
      OCIStringAssignText - OCIString Assign Text string to string
      OCIStringResize - OCIString ReSiZe string
      OCIStringSize - OCIString get String Size
      OCIStringPtr - OCIString get String PoinTeR
      OCIStringAllocSize - OCIString get Allocated SiZe
 
    OCIRaw - OCI Raw functions to manipulate variable-length raW
      OCIRawAssignRaw - OCIRaw Assign Raw (of type OCIRaw*) to raw
                        (of type OCIRaw*)
      OCIRawResize - OCIRaw Resize raw
      OCIRawSize - OCIRaw get Raw Size
      OCIRawPtr  - OCIRaw get Raw data Pointer
      OCIRawAllocSize - OCIRaw get Allocated Size

    OCIColl - OCI Collection generic functions. These functions can be 
		used to manipulate both variable-length array (varray) and 
                nested table.
      OCICollSize  - OCIColl return current SIZe of the given collection
		(in number of elements)
      OCICollMax  - OCIColl return the MAXimum number of elements in the
		collection (i.e. upper-bound)
      OCICollGetElem  - OCIColl GET pointer to the element at the given 
		position
      OCICollAssignElem  - OCIColl assign to element at given index
      OCICollAssign  - OCIColl ASsiGn collection; perform deep-copy of source 
		collection to target collection
      OCICollAppend  - OCIColl aPPend the given element to the end of the
		collection
      OCICollTrim  - OCIColl trim (delete) the given number of elements 
		from the end of the collection
      OCICollIsLocator - OCIColl indicates whether a collection is locator
                         based or not.
      OCIIterCreate  - OCIColl Create an ITerator to scan the collection 
		elements
      OCIIterDelete  - OCIColl Delete ITerator
      OCIIterInit  - OCIColl Initialize ITerator to scan the given collection
      OCIIterGetCurrent - OCIColl Iterator based, get CURrent 
		collection element
      OCIIterNext - OCIColl Iterator based, get NeXT collection element
      OCIIterPrev - OCIColl Iterator based, get PReVious collection element
 
      OCITable - OCI functions to manipulate nested Table. The OCIColl*() and 
		OCITable*() functions can be used to manipulate nested table
      OCITableDelete(i) - OCITable if element(i) exists then the element is 
		marked as deleted else the function returns false. So 
		delete's create "holes".
      OCITableExists(i) - OCITable return true iff an element at
		position i EXIsts
      OCITableFirst  - OCITable return the smallest value of i for which
		exists(i) is true.
      OCITableLast  - OCITable return the largest value of i for which 
		exists(i) is true.
      OCITableNext(i) - OCITable return pointer to the smallest position j, 
		greater than i, such that OCITableExists(j) is true
      OCITablePrev(i) - OCITable return pointer to the largest position j,
		less than i, such that OCITableExists(j) is true
      OCITableSize - OCITable return current SIZe of the given nested table not
		including deleted elements

    OCIRef - OCI functions to manipulate object Reference
      OCIRefClear  - OCIRef CLeaR or nullify a ref
      OCIRefAssign  - OCIRef ASsiGn a ref to another
      OCIRefIsEqual  - OCIRef compare two refs for EQUality
      OCIRefIsNull  - OCIRef test if a ref is NULl 
      OCIRefFromHex  - OCIRef convert a Hexadecimal string TO a Ref
      OCIRefToHex   - OCIRef convert a ref to a Hexadecimal string
      OCIRefHexSize  - OCIRef get size of buffer in bytes to store hexadecimal
		string

  OBSOLETE: to be replaced by functions from oci.h:

    ORLL - ORL functions to manipulate lob Locators
      orllasg   - ORLL AsiGn one locator to another
      orllequ   - ORLL compare two locators for EQUality
      orlliini  - ORLL Is the locator INItialized?
      orllgsz   - ORLL Get locator SiZe
      orllgcid  - ORLL Get Character set ID

      NOTE: The following are specific to FILE lobs:

      orllsnm - ORLL Set directory alias and file NaMe in the locator
      orllgnm - ORLL Get directory alias and file NaMe from the locator
 
  EXAMPLES

    Examples are given in the description of each function where
    relevant.
 
  NOTES

    This file has been subsetted to contain ONLY the routines that will
    be in the first release.
 
  QUESTIONS
     
  MODIFIED
    bpalaval   02/09/01   - Change text to oratext.
    rkasamse   09/20/99 -   lint changes
    whe        09/01/99 -   976457:check __cplusplus for C++ code
    hsbedi     08/11/99 -   Add macro
    rxgovind   10/14/98 -  make non exposed calls (OCIRowType etc) private
    rxgovind   06/09/98 -  update OCIRowTypeCreate
    nmantrav   05/11/98 -  add OCIRowTypeGetCount
    rxgovind   03/29/98 -  add OCIRowType and OCIRowData interfaces
    jwijaya    05/06/98  - add OCICollIsLocator                                
    rxgovind   03/18/98 -  opaque types: move to kolo.h
    etucker    02/02/98 -  add comments for Dec and Inc
    etucker    01/29/98 -  Finish core5 integration
    rxgovind   11/11/97 -  opaque types
    etucker    10/28/97 -  add ORLN functions for SDK
    cxcheng    07/28/97 -  remove OCILobLocator #define
    skmishra   05/13/97 -  stdcc compatibility changes
    skrishna   04/25/97 -  rename OCINumber*(): Exp Power TanHyp Zero Init
                           TanToArc Sqr Truncate and Compare 
    skotsovo   03/31/97 -  remove OCILobLocatorSize
    skrishna   03/25/97 -  remove orld2i and orldi2d
    skrishna   03/18/97 -  fix ifdef for supporting ansi and k&r proto-types
    cxcheng    02/06/97 -  take out short name support except with SLSHORTNAME
    skrishna   01/06/97 -  update OCITableSize() comments
    skrishna   12/27/96 -  fix OCIDateGet/OCIDateSet
    skrishna   12/12/96 -  update OCICollGelElem comments
    skrishna   11/07/96 -  OCICollGetElem: interface change
    skrishna   11/05/96 -  add OCIDate Get/Set and OCIDateAssign
    cxcheng    10/31/96 -  change OCINumberTanHyp to OCINumberHypTan
    cxcheng    10/30/96 -  #define orll short names to long names
    dchatter   10/26/96 -  fix some OCI file long names
    cxcheng    10/24/96 -  remove unnecessary comment in front
    cxcheng    10/14/96 -  disable long name mapping for LOB functions
    skrishna   10/13/96 -  continue beautification
    skotsovo   10/16/96 -  update ocilob names
    cxcheng    10/09/96 -  add structure members in #define for date/time
    cxcheng    10/09/96 -  more lint fixes
    skrishna   10/09/96 -  continue beautification
    cxcheng    10/09/96 -  more fixes
    skrishna   10/09/96 -  change fixed-char rep. to orlvstr*
    jwijaya    10/08/96 -  continue beautification
    jwijaya    10/07/96 -  beautify
    cxcheng    10/07/96 -  more changes
    cxcheng    10/04/96 -  replace short names with long names
    skrishna   10/01/96 -  orlcsiz, orltsiz: change prototype to take errhdl
    skrishna   09/23/96 -  fix lint errors
    skotsovo   09/23/96 -  remove orllmkcur().
    jwijaya    09/17/96 -  comments on null ref
    skrishna   09/19/96 -  change orlraw format
    skotsovo   09/19/96 -  add orlliini and remove orllnul
    skrishna   08/14/96 -  orlvstr: change format to ub4 followed by text
    jboonleu   08/06/96 -  update comment
    skotsovo   08/08/96 -  revert to locators instead of descriptors as input t
    jboonleu   07/23/96 -  remove orlrcur
    skrishna   07/06/96 -  add orltsiz
    skrishna   07/05/96 -  add orld2i and orldi2d
    jwijaya    07/03/96 -  add ANSI prototypes
    skrishna   06/27/96 -  document default string format in orlds2d & orld2s
    skrishna   06/25/96 -  change max date value
    skrishna   06/18/96 -  modify orld2s() comments
    skotsovo   06/13/96 -  orll functions take lob descriptors instead of locat
    rxgovind   06/05/96 -  change prototype of orlrcur to take ocienvh
    skrishna   05/30/96 -  support collection trimming
    skrishna   05/30/96 -  remove orlralo/fre and orllalo/fre instead use 
			   orionew/fre
    skrishna   05/28/96 -  add orlt*() and modify orla*()
    skotsovo   05/23/96 -  add orlbl typedefs for pro*c
    jboonleu   05/14/96 -  add orlrcur
    rxgovind   05/08/96 -  changes for 3gl callbacks
    skotsovo   05/01/96 -  in orllasg, no need to alloc orlbl*
    skrishna   04/21/96 -  merge changes from 960418 object branch into big
    skrishna   04/17/96 -  rename orlrcpy to orlrasg
    skrishna   04/12/96 -  add orlr2h and orlrh2r functions
    skotsovo   04/15/96 -  add fnt to make the lob locator current
    skrishna   04/08/96 -  change orl*() to take ocienvh* and ocierrh* instead
			   of oroenv*
    skotsovo   03/22/96 -  add locator functions
    skotsovo   03/22/96 -  add locator functions
    skrishna   02/27/96 -  remove mlslabel interface
    skotsovo   02/20/96 -  remove orlbty and use dty type instead.
    skotsovo   02/14/96 -  add text file lobs.
    skrishna   01/31/96 -  update comments of orln2r, orldchk, orlds2d & orld2s
    skrishna   01/31/96 -  change orld2s() and orln2s() to return string length
    skrishna   01/21/96 -  remove old raw interface 
    skrishna   12/14/95 -  add raw interface
    skotsovo   01/03/96 -  change LOB offsets and lengths from ub4 to ubig_ora
                           to support 64 bit machines.
    skotsovo   10/30/95 -  add orlblsiz() to get lob locator size
    skrishna   10/24/95 -  move ref functions from ori and update the ref
			   functions to support variable-length ref
    cxcheng    10/20/95 -  add more comments on number versions
    cxcheng    10/13/95 -  add more number functions
    cxcheng    08/29/95 -  Support for segmented varrays
    cxcheng    08/18/95 -  modifiy orlmls structure