ocikp.h

将对Oracle数据库读写操作的OCI进行封装。不但具有普通数据的读取操作

Comments:
This call is used to create a connection pool. conn_min connections
to the database are started on calling OCIConnectionPoolCreate.

Parameters:
envhp (IN/OUT)  - A pointer to the environment where the Conencton Pool
                  is to be created
errhp (IN/OUT)  - An error handle which can be passed to OCIErrorGet().
poolhp (IN/OUT) - An uninitialiazed pool handle.
poolName (OUT) - The connection pool name. 
poolNameLen (OUT) - The length of the connection pool name 
dblink (IN/OUT) - Specifies the database(server) to connect. This will also
                  be used as the default pool name.
dblinkLen (IN)  - The length of the string pointed to by dblink.
connMin (IN)    - Specifies the minimum number of connections in the
                  Connection Pool at any instant.
                  connMin number of connections are started when
                  OCIConnectionPoolCreate() is called.
connMax (IN)    - Specifies the maximum number of connections that can be
                  opened to the database. Once this value is reached, no
                  more connections are opened.
connIncr (IN)   - Allows application to set the next increment for
                  connections to be opened to the database if the current
                  number of connections are less than conn_max.
poolUsername (IN/OUT) - Connection pooling requires an implicit proxy
                         session and this attribute provides a username
                         for that session.
poolUserLen (IN) - This represents the length of pool_username.
poolPassword (IN/OUT) - The password for the parameter pool_username passed
                        above.
poolPassLen (IN) - This represents the length of pool_password.

mode (IN) - The modes supported are OCI_DEFAULT and OCI_REINITIALIZE

Related Functions
OCIConnectionPoolDestroy()
---------------------------------------------------------------------------

----------------------------OCIConnectionPoolDestroy-------------------------
Name:
OCIConnectionPoolDestroy

Purpose:
Destroys the Connection Pool.

Syntax:
OCIConnectionPoolDestroy (OCICPool *poolhp, OCIError *errhp, ub4 mode)

Comments:
On calling OCIConnectionPoolDestroy, all the open connections in the pool
are closed and the pool is destroyed.

Parameters:
poolhp (IN/OUT) - An uninitialiazed pool handle.
errhp (IN/OUT)  - An error handle which can be passed to OCIErrorGet().
mode (IN)       - Currently, OCIConnectionPoolDestroy() will support only
                  the OCI_DEFAULT mode.

Related Functions:
OCIConnectionPoolCreate()

-----------------------------------------------------------------------------
----------------------------OCISessionPoolCreate-----------------------------
Name:
OCISessionPoolCreate

Purpose:
Creates the sessions in the session pool.

Syntax:
sword OCISessionPoolCreate (OCIEnv *envhp, OCIError *errhp, OCISpool *spoolhp,
                      OraText **poolName, ub4 *poolNameLen,
                      CONST OraText *connStr, ub4 connStrLen,
                      ub4 sessMin, ub4 sessMax, ub4 sessIncr,
                      OraText *userid,  ub4 useridLen,
                      OraText *password, ub4 passwordLen,
                      ub4 mode)

Comments:
When OCISessionPoolCreate is called, a session pool is initialized for
the associated environment and the database specified by the
connStr parameter. This pool is named uniquely and the name
is returned to the user in the poolname parameter.

Parameters:
envhp (IN/OUT) - A pointer to the environment handle in which the session
                 pool needs to be created.
errhp (IN/OUT) - An error handle which can be passed to OCIErrorGet().
spoolhp (IN/OUT) - A pointer to the session pool handle that is created.
poolName (OUT) - Session pool name returned to the user.
poolNameLen (OUT) - Length of the PoolName
connStr (IN) - The TNS alias of the database to connect to.
connStrLen (IN) - Length of the connStr.
sessMin (IN) - Specifies the minimum number of sessions in the Session Pool.
               These are the number of sessions opened in the beginning, if
               in Homogeneous mode. Else, the parameter is ignored.
sessMax (IN) - Specifies the maximum number of sessions in the Session Pool.
               Once this value is reached, no more sessions are opened,
               unless the OCI_ATTR_SPOOL_FORCEGET is set.
userid (IN) - Specifies the userid with which to start up the sessions.
useridLen (IN) - Length of userid.
password (IN) - Specifies the password for the corresponding userid.
passwordLen (IN) - Specifies the length of the password
mode(IN) - May be OCI_DEFAULT, OCI_SPC_SPOOL_REINITIALIZE, or
           OCI_SPC_SPOOL_HOMOGENEOUS.

Returns:
SUCCESS - If pool could be allocated and created successfully.
ERROR - If above conditions could not be met.

Related Functions:
OCISessionPoolDestroy()
-----------------------------------------------------------------------------
-----------------------------OCISessionPoolDestroy---------------------------
Name:
OCISessionPoolDestroy

Purpose:
Terminates all the sessions in the session pool.

Syntax:
sword OCISessionPoolDestroy (OCISPool *spoolhp, OCIError *errhp, ub4 mode)

Comments:
spoolhp (IN/OUT) - The pool handle of the session pool to be destroyed.
errhp (IN/OUT) - An error handle which can be passed to OCIErrorGet().
mode (IN) - Currently only OCI_DEFAULT mode is supported.

Returns:
SUCCESS - All the sessions could be closed.
ERROR - If the above condition is not met.

Related Functions:
OCISessionPoolCreate()
-----------------------------------------------------------------------------
-------------------------------OCISessionGet---------------------------------
Name:
OCISessionGet

Purpose:
Get a session. This could be from a session pool, connection pool or
a new standalone session.

Syntax:
sword OCISessionGet(OCIenv *envhp, OCIError *errhp, OCISvcCtx **svchp,
                    OCIAuthInfo *authhp,
                    OraText *poolName, ub4 poolName_len,
                    CONST OraText *tagInfo, ub4 tagInfo_len,
                    OraText **retTagInfo, ub4 *retTagInfo_len,
                    boolean *found,
                    ub4 mode)

Comments:
envhp (IN/OUT) - OCI environment handle.
errhp (IN/OUT) - OCI error handle to be passed to OCIErrorGet().
svchp (IN/OUT) - Address of an OCI service context pointer. This will be
                 filled with a server and session handle, attached to the
                 pool.
authhp (IN/OUT) - OCI Authentication Information handle.
poolName (IN) - This indicates the session/connection pool to get the
                session/connection from in the OCI_SPOOL/OCI_CPOOL mode.
                In the OCI_DEFAULT mode it refers to the connect string.
poolName_len (IN) - length of poolName.
tagInfo (IN) - indicates the tag of the session that the user wants. If the
                   user wants a default session, he must specify a NULL here.
                   Only used for Session Pooling.
tagInfo_len (IN) - the length of tagInfo.
retTagInfo (OUT) - This indicates the type of session that is returned to
                   the user. Only used for Session Pooling.
retTagInfo_len (OUT) - the length of retTagInfo.
found (OUT) - set to true if the user gets a session he had requested, else
              set to false. Only used for Session Pooling.
mode (IN) - The supported modes are OCI_DEFAULT, OCI_CRED_PROXY and
            OCI_GET_SPOOL_MATCHANY, OCI_SPOOL and OCI_CPOOL. OCI_SPOOL and
            OCI_CPOOL are mutually exclusive.

Returns:
SUCCESS -  if a session was successfully returned into svchp.
SUCCESS_WITH_INFO - if a session was successfully returned into svchp and the
                    total number of sessions > maxsessions. Only valid for
                    Session Pooling.
ERROR - If a session could not be retrieved.

Related Functions:
OCISessionRelease()
-----------------------------------------------------------------------------
---------------------------OCISessionRelease---------------------------------
Name:
OCISessionRelease

Purpose:
Release the session.

Syntax:
sword OCISessionRelease ( OCISvcCtx *svchp, OCIError *errhp,
                          OraText *tag, ub4 tag_len,
                          ub4 mode);

Comments:
svchp (IN/OUT) - The service context associated with the session/connection.
errhp (IN/OUT) - OCI error handle to be passed to OCIErrorGet().
tag (IN) - Only used for Session Pooling.
           This parameter will be ignored unless mode OCI_RLS_SPOOL_RETAG is
           specified. In this case, the session is labelled with this tag and
           returned to the pool. If this is NULL, then the session is untagged.
tag_len (IN) - Length of the tag. This is ignored unless mode 
               OCI_RLS_SPOOL_RETAG is set.
mode (IN) - The supported modes are OCI_DEFAULT, OCI_RLS_SPOOL_DROPSESS,
            OCI_RLS_SPOOL_RETAG. The last 2 are only valid for Session Pooling.
            When OCI_RLS_SPOOL_DROPSESS is specified, the session
            will be removed from the session pool. If OCI_RLS_SPOOL_RETAG is 
            set, the tag on the session will be altered. If this mode is not 
            set, the tag and tag_len parameters will be ignored.

Returns:
ERROR - If the session could not be released successfully.
SUCCESS - In all other cases.

Related Functions:
OCISessionGet().

-----------------------------------------------------------------------------
------------------------------OCIDateTimeAssign --------------------------
sword OCIDateTimeAssign(dvoid *hndl, OCIError *err, CONST OCIDateTime *from, 
			 OCIDateTime *to);
NAME: OCIDateTimeAssign - OCIDateTime Assignment
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().
from (IN) - datetime to be assigned
to (OUT) - lhs of assignment
DESCRIPTION:
        Performs date assignment. The type of the output will be same as that
	of input

------------------------------OCIDateTimeCheck--------------------
sword OCIDateTimeCheck(dvoid *hndl, OCIError *err, CONST OCIDateTime *date, 
		 ub4 *valid );
NAME: OCIDateTimeCheck - OCIDateTime CHecK if the given date is valid
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().
date (IN) - date to be checked
type (IN) - type of the input datetime(OCI_DATE, OCI_TIME, 
				OCI_TIMESTAMP,	OCI_TZTIMESTAMP, OCI_TZTIME)
valid (OUT) -  returns zero for a valid date, otherwise 
  		the ORed combination of all error bits specified below:
   Macro name                   Bit number      Error
   ----------                   ----------      -----
   OCI_DATE_INVALID_DAY         0x1             Bad day
   OCI_DATE_DAY_BELOW_VALID     0x2             Bad DAy Low/high bit (1=low)
   OCI_DATE_INVALID_MONTH       0x4             Bad MOnth
   OCI_DATE_MONTH_BELOW_VALID   0x8             Bad MOnth Low/high bit (1=low)
   OCI_DATE_INVALID_YEAR        0x10            Bad YeaR
   OCI_DATE_YEAR_BELOW_VALID    0x20            Bad YeaR Low/high bit (1=low)
   OCI_DATE_INVALID_HOUR        0x40            Bad HouR
   OCI_DATE_HOUR_BELOW_VALID    0x80            Bad HouR Low/high bit (1=low)
   OCI_DATE_INVALID_MINUTE      0x100           Bad MiNute
   OCI_DATE_MINUTE_BELOW_VALID	0x200           Bad MiNute Low/high bit (1=low)
   OCI_DATE_INVALID_SECOND      0x400           Bad SeCond
   OCI_DATE_SECOND_BELOW_VALID  0x800           bad second Low/high bit (1=low)
   OCI_DATE_DAY_MISSING_FROM_1582 0x1000        Day is one of those "missing"
                                                from 1582
   OCI_DATE_YEAR_ZERO           0x2000          Year may not equal zero
   OCI_DATE_INVALID_TIMEZONE    0x4000          Bad Timezone
   OCI_DATE_INVALID_FORMAT      0x8000          Bad date format input

   So, for example, if the date passed in was 2/0/1990 25:61:10 in
   (month/day/year hours:minutes:seconds format), the error returned