ociap.h

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

        timezone  (IN) - Timezone string
        timezone_length(IN) - Length of timezone string

DESCRIPTION:
       Constructs a DateTime descriptor. The type of the datetime is the
       type of the OCIDateTime descriptor. Only the relevant fields based
       on the type are used. For Types with timezone, the date and time
       fields are assumed to be in the local time of the specified timezone.
       If timezone is not specified, then session default timezone is
       assumed.
RETURNS:
        OCI_SUCCESS if the function completes successfully.
        OCI_ERROR if datetime is not valid.

------------------------------OCIDateTimeSubtract-----------------------
sword OCIDateTimeSubtract(dvoid *hndl, OCIError *err, OCIDateTime *indate1, 
		OCIDateTime *indate2, OCIInterval *inter);
NAME: OCIDateTimeSubtract - subtracts two datetimes to return an interval
PARAMETERS:
hndl (IN) - Session/Env handle. 
err (IN/OUT) - error handle. If there is an error, it is
                recorded in 'err' and this function returns OCI_ERROR.
                The error recorded in 'err' can be retrieved by calling
                OCIErrorGet().
indate1(IN) - pointer to subtrahend
indate2(IN) - pointer to minuend
inter  (OUT) - pointer to output interval
DESCRIPTION: 
	Takes two datetimes as input and stores their difference in an 
        interval. The type of the interval is the type of the 'inter'
        descriptor.
RETURNS:
        OCI_SUCCESS if the function completes successfully.
        OCI_INVALID_HANDLE if 'err' is NULL.
	OCI_ERROR if
	   datetimes are not comparable.

--------------------------- OCIDateTimeToText--------------------------
sword OCIDateTimeToText(dvoid *hndl, OCIError *err, CONST OCIDateTime *date, 
                        CONST OraText *fmt, ub1 fmt_length, ub1 fsprec, 
                        CONST OraText *lang_name, size_t lang_length, 
                        ub4 *buf_size, OraText *buf );
NAME: OCIDateTimeToText - OCIDateTime convert date TO String 
PARAMETERS:
hndl (IN) - Session/Env handle. If Session Handle is passed, the 
		    conversion takes place in session NLS_LANGUAGE and
		    session NLS_CALENDAR, otherwise the default is used.
err (IN/OUT) - error handle. If there is an error, it is
                recorded in 'err' and this function returns OCI_ERROR.
                The error recorded in 'err' can be retrieved by calling
                OCIErrorGet().
date (IN) - Oracle datetime to be converted
fmt (IN) - conversion format, if null string pointer (OraText*)0, then
                the date is converted to a character string in the
                default format for that type.
fmt_length (IN) - length of the 'fmt' parameter
fsprec (IN) - specifies the fractional second precision in which the
               fractional seconds is returned.
lang_name (IN) - specifies the language in which the names and 
  	        abbreviations of months and days are returned;
  	        default language of session is used if 'lang_name' 
  		is null i.e. (OraText *)0
lang_length (IN) - length of the 'nls_params' parameter
buf_size (IN/OUT) - size of the buffer; size of the resulting string
                is returned via this parameter
buf (OUT) - buffer into which the converted string is placed
DESCRIPTION:
        Converts the given date to a string according to the specified format.
        Refer to "TO_DATE" conversion function described in
        "Oracle SQL Language Reference Manual" for a description of format
        and NLS arguments. The converted null-terminated date string is
        stored in the buffer 'buf'.
RETURNS:
        OCI_SUCCESS if the function completes successfully.
        OCI_INVALID_HANDLE if 'err' is NULL.
        OCI_ERROR if
  	  buffer too small
  	  invalid format
  	  unknown language
          overflow error

----------------------------OCIDateTimeGetTimeZoneName------------------------
sword OCIDateTimeGetTimeZoneName(dvoid *hndl, 
                                 OCIError *err,
                                 CONST OCIDateTime *datetime,
                                 ub1 *buf,
                                 ub4 *buflen);
NAME OCIDateTimeGetTimeZoneName - OCI DateTime Get the Time Zone Name
PARAMETERS:
hndl (IN)      - Session/Env handle.
err (IN/OUT)   - error handle. If there is an error, it is
                 recorded in 'err' and this function returns OCI_ERROR.
                 The error recorded in 'err' can be retrieved by calling
                 OCIErrorGet().
datetime (IN)   - Pointer to an OCIDateTime.
buf (OUT)       - User allocated storage for name string.
buflen (IN/OUT) - length of buf on input, length of name on out
DESCRIPTION:
        Returns either the timezone region name or the absolute hour and minute
        offset. If the DateTime was created with a region id then the region 
        name will be returned in the buf.  If the region id is zero, then the 
        hour and minute offset is returned as "[-]HH:MM".
RETURNS:
       OCI_SUCCESS if the function completes successfully.
       OCI_INVALID_HANDLE if 'err' is NULL.
       OCI_ERROR if
         buffer too small
         error retrieving timezone data
         invalid region 
         invalid LdiDateTime type

---------------------------------OCIDateTimeToArray----------------------------
sword OCIDateTimeToArray(dvoid *hndl, 
                         OCIError *err,
                         CONST OCIDateTime *datetime,
                         CONST OCIInterval *reftz,
                         ub1 *outarray,
                         ub4 *len
                         ub1 *fsprec);
NAME OCIDateTimeToArray - OCI DateTime convert To Array format
PARAMETERS:
hndl (IN)      - Session/Env handle.
err (IN/OUT)   - error handle. If there is an error, it is
                 recorded in 'err' and this function returns OCI_ERROR.
                 The error recorded in 'err' can be retrieved by calling
                 OCIErrorGet().
datetime (IN)   - Pointer to OCIDateTime to be converted.
outarray (OUT)  - Result array storage
len (OUT)        - pointer to  length of outarray.
fsprec (IN)     - Number of fractional seconds digits.
DESCRIPTION:
        Returns an array representing the input DateTime descriptor.
RETURNS:
       OCI_SUCCESS if the function completes successfully.
       OCI_INVALID_HANDLE if 'err' is NULL.
       OCI_ERROR if
         buffer too small
         error retrieving timezone data
         invalid region 
         invalid LdiDateTime type

--------------------------------OCIDateTimeFromArray---------------------------
sword OCIDateTimeFromArray(dvoid *hndl, 
                         OCIError *err,
                         ub1 *inarray,
                         ub4 len
                         ub1 type
                         OCIDateTime *datetime,
                         OCIInterval *reftz,
                         ub1 fsprec);
NAME OCIDateTimeFromArray - OCI DateTime convert From Array format
PARAMETERS:
hndl (IN)      - Session/Env handle.
err (IN/OUT)   - error handle. If there is an error, it is
                 recorded in 'err' and this function returns OCI_ERROR.
                 The error recorded in 'err' can be retrieved by calling
                 OCIErrorGet().
inarray (IN)   - Pointer to input array representtion of DateTime
len (IN)       - len of inarray.
type (IN)      - One of SQLT_DATE, SQLT_TIME, SQLT_TIME_TZ, SQLT_TIMESTAMP,
                 SQLT_TIMESTAMP_TZ, or SQLT_TIMESTAMP_LTZ.
datetime (OUT) - Pointer to the result OCIDateTime.
reftz (IN)     - timezone interval used with SQLT_TIMESTAMP_LTZ.
fsprec (IN)    - fractionl seconds digits of precision (0-9).
DESCRIPTION:
        Returns a pointer to an OCIDateTime of type type converted from 
        the inarray.
RETURNS:
       OCI_SUCCESS if the function completes successfully.
       OCI_INVALID_HANDLE if 'err' is NULL.
       OCI_ERROR if
         buffer too small
         error retrieving timezone data
         invalid region 
         invalid LdiDateTime type

----------------------------------OCIRowidToChar-----------------------------
Name
OCIRowidToChar

Purpose
Converts physical/logical (universal) ROWID to chracter extended (Base 64) 
representation into user provided buffer outbfp of length outbflp. After 
execution outbflp contains amount of bytes converted.In case of truncation 
error, outbflp contains required size to make this conversion successful
and returns ORA-1405.

Syntax
sword OCIRowidToChar( OCIRowid *rowidDesc, 
                      OraText *outbfp, 
                      ub2 *outbflp, 
                      OCIError *errhp)

Comments
After this conversion, ROWID in character format can be bound using
OCIBindByPos or OCIBindByName call and used to query a row at a
desired ROWID. 

Parameters
rowidDesc (IN)   - rowid DESCriptor which is allocated from OCIDescritorAlloc
                   and populated by a prior SQL statement execution
outbfp (OUT)     - pointer to the buffer where converted rowid in character 
                   representation is stored after successful execution.
outbflp (IN/OUT) - pointer to output buffer length variable.
                   Before execution (IN mode) *outbflp contains the size of
                   outbfp, after execution (OUT mode) *outbflp contains amount
                   of bytes converted. In an event of truncation during 
                   conversion *outbflp contains the required length to make
                   conversion successful.
errhp (IN/OUT)   - an error handle which can be passed to OCIErrorGet() for
                   diagnostic information in the event of an error.

------------------------------OCIDefineArrayOfStruct--------------------------


OCIDefineArrayOfStruct()
Name
OCI Define for Array of Structures
Purpose
This call specifies additional attributes necessary for a static array define.
Syntax
sword OCIDefineArrayOfStruct ( OCIDefine   *defnp,
                             OCIError    *errhp,
                             ub4         pvskip, 
                             ub4         indskip, 
                             ub4         rlskip,
                             ub4         rcskip );
Comments
This call specifies additional attributes necessary for an array define, used in 
an array of structures (multi-row, multi-column) fetch.
For more information about skip parameters, see the section "Skip Parameters" 
on page 4-17.
Parameters
defnp (IN) - the handle to the define structure which was returned by a call 
to OCIDefineByPos().
errhp (IN) - an error handle which can be passed to OCIErrorGet() for 
diagnostic information in the event of an error.
pvskip (IN) - skip parameter for the next data value.
indskip (IN) - skip parameter for the next indicator location. 
rlskip (IN) - skip parameter for the next return length value.
rcskip (IN) - skip parameter for the next return code.
Related Functions
OCIAttrGet()





OCIDefineByPos()
Name
OCI Define By Position
Purpose
Associates an item in a select-list with the type and output data buffer. 
Syntax
sb4 OCIDefineByPos ( 
              OCIStmt     *stmtp, 
              OCIDefine   **defnp,
              OCIError    *errhp,
              ub4         position,
              dvoid       *valuep,
              sb4         value_sz,
              ub2         dty,
              dvoid       *indp,
              ub2         *rlenp,
              ub2         *rcodep,
              ub4         mode );
Comments
This call defines an output buffer which will receive data retreived from 
Oracle. The define is a local step which is necessary when a SELECT statement 
returns data to your OCI application.
This call also implicitly allocates the define handle for the select-list item.
Defining attributes of a column for a fetch is done in one or more calls. The 
first call is to OCIDefineByPos(), which defines the minimal attributes 
required to specify the fetch. 
This call takes as a parameter a define handle, which must have been 
previously allocated with a call to OCIHandleAlloc().
Following the call to OCIDefineByPos() additional define calls may be 
necessary for certain data types or fetch modes:
A call to OCIDefineArrayOfStruct() is necessary to set up skip parameters 
for an array fetch of multiple columns.
A call to OCIDefin