manual.htm

以OLE DB风格访问DB2数据库的C++类源码

        loc.Free();                     // Free the locator

        rs.MoveNext();
    }
    rs.Close();
</pre>

<h2><a name="#Error">Handle errors or exceptions</a></h2>

<p>For each CSqlDatabase/CSqlCommand/CSqlRecordset object which is inherited from CSqlObject,
the application can call its member function GetLastError to acquire the error information of
database operation.

<pre>
void HandleError(CSqlObject* pSqlObject)
{
    CSqlErrorInfo e;
    while (pSqlObject->GetLastError(e))
    {
        printf("SQL error message: %s\n", e.GetErrorText());
    }
}
</pre>

An alternative way is to override CSqlObject::OnSqlError function so that the application can
handle the error immediately after it hapens.

<!--------------------------------------------------------------------------->
<h2><a name="#CSqlObject">CSqlObject class</a></h2>
<p>CSqlObject is the bsae class of CSqlDatabase, CSqlCommand, and CSqlRecordset. It wraps a DB2 CLI
handle (it could be a connection handle, or a statement handle), and manages the error messages
occured on this handle.
<dl>

<dt><pre>CSqlObject();</pre>
<dd>Creates a CSqlObject object.

<dt><pre>SQLHANDLE GetHandle() const;</pre>
<dd>Returns the DB2 CLI handle.

<dt><pre>BOOL IsOpen() const;</pre>
<dd>Returns TRUE if the DB2 CLI handle has been created, otherwise FALSE.

<dt><pre>CSqlDatabase* GetDatabase() const;</pre>
<dd>Returns the pointer of the database connection this object runs upon.

<dt><pre>virtual void Close();</pre>
<dd>Closes handle and releases resources.

<dt><pre>BOOL SqlCheck(SQLRETURN nSqlRet);</pre>
<dd>Checks the return code of a DB2 CLI API call. Returns TRUE if the call succeeded, otherwise FALSE.

<dt><pre>BOOL SetAttribute(SQLINTEGER nAttr, SQLPOINTER pValue, SQLINTEGER nValueSize=0);</pre>
<dd>Sets an attribute of the handle.
<dd><b>Parameters</b>
<dl><dt><i>nAttr</i>
<dd>Specifies the identifier of the attribute.
<dt><i>pValue</i>
<dd>Pointer to the value of the attribute.
<dt><i>nValueSize</i>
<dd>If <i>pValue</i> points to a character string or a binary buffer, this argument should be the length of the value.
</dl>

<dt><pre>BOOL GetAttribute(SQLINTEGER nAttr, SQLPOINTER pValue, SQLINTEGER nBuffSize=0, SQLINTEGER* pnValueSize=NULL);</pre>
<dd>Gets the current setting of an attribute of the handle.
<dd><b>Parameters</b>
<dl><dt><i>nAttr</i>
<dd>Specifies the identifier of the attribute.
<dt><i>pValue</i>
<dd>Pointer to a buffer to retrieve the attribute value.
<dt><i>nBuffSize</i>
<dd>Specifies the length of the buffer.
<dt><i>pnValueSize</i>
<dd>Pointer to an integer to retrieve the length of the attribute value.
</dl>

<dt><pre>BOOL GetLastError(CSqlErrorInfo& rErrorInfo);</pre>
<dd>Gets the last-error occured on this object.

</dl>

<!--------------------------------------------------------------------------->
<h2><a name="#CSqlDatabase">CSqlDatabase class</a></h2>
<p>CSqlDatabase is inherited from CSqlObject class.
<dl>

<dt><pre>CSqlDatabase();</pre>
<dd>Creates a CSqlDatabase object.

<dt><pre>static BOOL Initialize(BOOL bMultiThread=TRUE);</pre>
<dd>Initializes a DB2 CLI environment.
<dd><b>Parameters</b>
<dl><dt><i>bMultiThread</i>
<dd>Specifies whether the application uses DB2 CLI in a multithreading environment.
</dl>

<dt><pre>static void Uninitialize();</pre>
<dd>Releases the DB2 CLI environment.
<dd><a href="#Connect">See sample</a>

<dt><pre>static BOOL SetEnvAttr(SQLINTEGER nAttr, SQLINTEGER nValue);</pre>
<dd>Sets an attribute of the DB2 CLI environment.
<dd><b>Parameters</b>
<dl><dt><i>nAttr</i>
<dd>Specifies the identifier of the attribute.
<dt><i>nValue</i>
<dd>Specifies the value of the attribute.
</dl>

<dt><pre>static BOOL GetEnvAttr(SQLINTEGER nAttr, SQLINTEGER& nValue);</pre>
<dd>Gets the value of an attribute of the DB2 CLI environment.
<dd><b>Parameters</b>
<dl><dt><i>nAttr</i>
<dd>Specifies the identifier of the attribute.
<dt><i>nValue</i>
<dd>The integer variable to retrieve the value.
</dl>

<dt><pre>BOOL Connect(PCSTR pszDB, PCSTR pszUser, PCSTR pszPwd, DWORD dwOption=defaultOption, DWORD dwTxnIsolation=SQL_TXN_READ_COMMITTED);</pre>
<dd>Establishes a connection to a database.
<dd><b>Parameters</b>
<dl><dt><i>pszDB</i>
<dd>Specifies the database name.
<dt><i>pszUser</i>
<dd>Specifies the user name.
<dt><i>pszPwd</i>
<dd>Specifies the password of the user.
<dt><i>dwOption</i>
<dd>Specifies the attribute of the database connection. It can be 0 or a combination of the following values:
<dl>
<dt>readOnly<dd>Specifies the connection is read-only. By default it is read-write.
<dt>manualCommit<dd>The application must manually, explicitly commit or rollback transactions with
CommitTrans() or RollbackTrans() calls. By default DB2 implicitly commits each statement automatically.
<dt>autoUnlock<dd>Specifies the read locks are released when the cursor is closed. By default the read
locks are not released automatically
</dl>
<dt><i>dwTxnIsolation</i>
<dd>Sets the transaction isolation level.
</dl>
<dd><a href="#Connect">See sample</a>

<dt><pre>void Close();</pre>
<dd>Closes the current database connection.

<dt><pre>BOOL BeginTrans();</pre>
<dd>Begins a new transaction

<dt><pre>BOOL CommitTrans();</pre>
<dd>Saves any changes and ends the current transaction.

<dt><pre>BOOL RollbackTrans();</pre>
<dd>Cancels any changes made during the current transaction and ends the transaction.

</dl>

<!--------------------------------------------------------------------------->
<h2><a name="#CSqlCommand">CSqlCommand class</a></h2>
<p>CSqlCommand is inherited from CSqlObject class.
<dl>

<dt><pre>CSqlCommand();</pre>
<dd>Creates a CSqlCommand object.

<dt><pre>BOOL Create(CSqlDatabase* pDB, DWORD dwOption=defaultOption);</pre>
<dd>Initializes a CSqlCommand object.
<dd><b>Parameters</b>
<dl><dt><i>pDB</i>
<dd>Pointer to the database connection which this command runs upon.
<dt><i>dwOption</i>
<dd>Specifies the command option. It can be 0 or a combination of the following values:
<dl><dt>execDirect<dd>Executes command directly without preparation.
<dt>autoCloseCursor<dd>Automatically closes an open cursor if a second cursor is opened.
<dt>nonScanEscape<dd>Disables the scan of SQL string for escape clauses. Don't use this option to call stored procedure.
<dt>preFetch<dd>Tells the server to prefetch the next block of data immediately after sending the current block.
</dl>
</dl>
<dd><a href="#Execute">See sample</a>

<dt><pre>virtual void Close;</pre>
<dd>Closes the command object.

<dt><pre>virtual void Reset();</pre>
<dd>Unbinds all parameters and resets the command handle for reuse.

<dt><pre>BOOL SetCommand(PCSTR lpszSQL);</pre>
<dd>Specifies the SQL statement to be executed, and prepare the statetment if execDirect option not specified.
<dd><b>Parameters</b>
<dl><dt><i>lpszSQL</i>
<dd>String pointer of a SQL statement.
</dl>

<dt><pre>BOOL Execute();</pre>
<dd>Executes the current SQL statement.

<dt><pre>SQLINTEGER GetRowCount();</pre>
<dd>Returns the count of rows that were affected by the SQL statement.

<dt><pre>CSqlParameters& Parameters();</pre>
<dd>Returns the collection of parameters bound on this command.

</dl>

<!--------------------------------------------------------------------------->
<h2><a name="#CSqlRecordset">CSqlRecordset class</a></h2>
<p>CSqlRecordset is inherited from CSqlCommand class.
<dl>

<dt><pre>CSqlRecordset();</pre>
<dd>Creates a CSqlRecordset object.

<dt><pre>string m_strFilter;</pre>
<dd>Specifies the search condition of the query before calling Open() with <i>nCmdType</i> set to sqlCmdTable.

<dt><pre>string m_strSort;</pre>
<dd>Specifies the sort order for the result set before calling Open() with <i>nCmdType</i> set to sqlCmdTable.

<dt><pre>BOOL Open(PCSTR pszCommand, int nCmdType, DWORD nCursorType=SQL_CURSOR_STATIC, BOOL bUseBookmarks=FALSE);</pre>
<dd>Opens a recordset by executing a query, store procedure or generic SQL statement.
<dd><b>Parameters</b>
<dl><dt><i>pszCommand</i>
<dd>String pointer of the command to be executed.
<dt><i>nCmdType</i>
<dd>Specifies how the command argument <i>nCmdType</i> should be interpreted:
<dl><dt>sqlCmdSQL<dd>Evaluates the command as a SQL statement.
<dt>sqlCmdTable<dd>Evaluates the command as a table name.
<dt>sqlCmdStoreProc<dd>Evaluates the command as the name of a store procedure.
</dl>
<dt><i>nCursorType</i>
<dd>Specifies the type of cursor. It can be one of the following values:
<dd>SQL_CURSOR_FORWARD_ONLY
<dd>SQL_CURSOR_STATIC (default)
<dd>SQL_CURSOR_KEYSET_DRIVEN
<dt><i>bUseBookmarks</i>
<dd>Specifies whether enable bookmark. This argument is ignored if <i>nCursorType</i> is set to
SQL_CURSOR_FORWARD_ONLY.
<dd><a href="#Query">See sample</a>

<dt><pre>BOOL Requery();</pre>
<dd>Re-executes the current command to refresh the entire result set.

<dt><pre>BOOL NextRecordset();</pre>
<dd>Clears the current recordset, and returns the next recordset by advancing through a series of commands.

<dt><pre>virtual void Close();</pre>
<dd>Closes the object and releases any resources.

<dt><pre>virtual void Reset();</pre>
<dd>Unbinds all columns and parameters, and resets the command handle for reuse.

<dt><pre>BOOL AutoBindProcParams(PCSTR pszProcName, PCSTR pszSchemaName=NULL);</pre>
<dd>Retrieves all the parameters associated with a procedure and add them to parameter list. This function must
be called before Open().
<dd><b>Parameters</b>
<dl><dt><i>pszProcName</i>
<dd>Specifies the name of a stored procedure.
<dt><i>pszSchemaName</i>
<dd>Specifies the name of the schema which the procedure belongs to.
</dl>

<dt><pre>
BOOL IsScrollable() const;
BOOL IsUpdatable() const;
</pre>
<dd>Returns TRUE if the current cursor is scrollable, updatable.

<dt><pre>BOOL SetMaxRows(DWORD nMaxRows=0);</pre>
<dd>Specifies the maximum number of rows to return from a query.
The default value is 0 means all rows are returned. Must be called before Open().

<dt><pre>void SetCacheSize(int nCacheSize=0);</pre>
<dd>Specifies the number of rows of the local row cache. A reasonable cache size can reduce the
network traffic and improve performence.
The default value is 1. Must be called before Open().

<dt><pre>int GetCacheSize() const;</pre>
<dd>Returns the size of the local row cache.

<dt><pre>int GetRetStatus() const;</pre>
<dd>Returns the return code (specified by a RETURN statement) of this stored procedure.

<dt><pre>SQLUSMALLINT GetRowStatus() const;</pre>
<dd>Returns the status of current row. It can be one of the following values:
<dl>
<dt>SQL_ROW_SUCCESS<dd>The row was successfully fetched.
<dt>SQL_ROW_ERROR<dd>An error occurred while fetching the row.
<dt>SQL_ROW_NOROW<dd>The rowset overlapped the end of the result set and no row was returned.
<dt>SQL_ROW_DELETED<dd>The row has been deleted (by calling Delete()) since it was last fetched from this result set.
<dt>SQL_ROW_UPDATED<dd>The row has been updated (by calling Update()) since it was last fetched from this result set.
</dl>

<dt><pre>BOOL IsDeleted() const;</pre>
<dd>Returns TRUE if the current row is marked to be deleted. This function is only valid for updatable cursor.

<dt><pre>
BOOL IsBOF() const;