Connector/ODBC 5 commit: r630 - in trunk/Driver: Driver/Library examples/c

[pharvey]

Modified:
   trunk/Driver/Driver/Library/MYODBCDriverMain.cpp
   trunk/Driver/Driver/Library/SQLAllocHandle.cpp
   trunk/Driver/Driver/Library/SQLBrowseConnectW.cpp
   trunk/Driver/examples/c/tutorial_01.c
Log:
ENH: Some more doc.


Modified: trunk/Driver/Driver/Library/MYODBCDriverMain.cpp
===================================================================
--- trunk/Driver/Driver/Library/MYODBCDriverMain.cpp	2006-10-23 21:01:06 UTC (rev 629)
+++ trunk/Driver/Driver/Library/MYODBCDriverMain.cpp	2006-10-24 10:51:50 UTC (rev 630)
@@ -41,57 +41,60 @@
 HANDLE  ghMYODBCDrvModule       = NULL;
 QFile   gMYODBCTraceFile;
 
+/*!
+    \internal
+    \brief      Does init and fini on MS Windows platforms.
 
-BOOL WINAPI DllMain( HANDLE   hInst,
-                     DWORD    nReason,
-                     LPVOID   pReserved )
-{
-    switch ( nReason )
-    {
-        case DLL_PROCESS_ATTACH:
-            if ( !gnMYODBCDrvProcesses++ )
-            {
-                ghMYODBCDrvModule = hInst;
-                /*! 
-                    \internal
-                    \todo 
+                This is called automagically by the MS Windows link-loader every time an 
+                application makes a reference to the driver (directly or indirectly).
 
-                    MyODBC Trace
-        
-                    The objective here is to have MyODBC trace configurable at the
following levels;
+                We init any driver based tracing upon first reference and fini any
tracing
+                upon the last reference being released.
 
-                    1. enabled/disabled at build time
-                    2. enabled/disabled at run-time
+                C/ODBC Trace
+    
+                The objective here is to have C/ODBC trace configurable at the following
levels;
 
-                    Build Time
+                1. enabled/disabled at build-time
+                2. enabled/disabled at run-time (if enabled at build-time)
 
-                    The level of detail is configurable using a DEFINE picked up in the
make file. It
-                    causes all the MYODBCDbg* defines to bring in trace code - or not. 
+                Build Time
 
-                    Run Time
+                The level of detail is configurable using a DEFINE picked up in the make
file. 
+                Setting MYODBC_DBG to a value > 0 causes all the MYODBCDbg* defines to
bring in 
+                trace code. Higher values increase the amount of trace output.
 
-                    Trace output can only be enabled at run-time if it was also enabled
at build-time.
+                Run Time
 
-                    Trace output is turned on/off by one of the following methods;
+                Trace output can only be enabled at run-time if it was also enabled at
build-time.
 
-                    1. MYODBC_LOG connection attribute via DSN or connect string.
-                    2. MYODBC_LOG environment variable set to "off" or file name.
+                Trace output is turned on/off by one of the following methods;
 
-                    The default behaviour is to have the trace go to stdout. Set
MYODBC_LOG to a file
-                    name to send it to a file. Set MYODBC_LOG to "off" to turn trace
output off.
+                1. MYODBC_LOG connection attribute via DSN or connect string.
+                2. MYODBC_LOG environment variable set to "off" or file name.
 
-                    Examples;
+                Examples;
 
-                    set MYODBC_LOG=off
-                    set MYODBC_LOG=C:\myodbc_log.txt
-                    set MYODBC_LOG=stdout
+                set MYODBC_LOG=off
+                set MYODBC_LOG=C:\\myodbc_log.txt
+                set MYODBC_LOG=stdout
 
-                    \note
-
-                    MyODBC trace is aside from any trace produced by the Driver Manager
(DM). The DM 
-                    uses some global settings for trace and uses TRACE & TRACE_FILE
connection 
-                    attributes.
-                */
+                C/ODBC trace is aside from any trace produced by the Driver Manager (DM).
The DM 
+                uses some global settings for trace and uses TRACE & TRACE_FILE
connection 
+                attributes.
+*/
+BOOL WINAPI DllMain( HANDLE   hInst,
+                     DWORD    nReason,
+                     LPVOID   pReserved )
+{
+    switch ( nReason )
+    {
+        case DLL_PROCESS_ATTACH:
+            /* First reference? */
+            if ( !gnMYODBCDrvProcesses++ )
+            {
+                ghMYODBCDrvModule = hInst;
+                /* Init tracing? */
                 SQLWCHAR *psMYODBC_LOG = _wgetenv( TEXT("MYODBC_LOG") );
                 if ( psMYODBC_LOG )
                 {
@@ -118,23 +121,29 @@
                 }
             }
             break;
+
         case DLL_THREAD_ATTACH:
             gnMYODBCDrvThreads++;
             break;
+
         case DLL_PROCESS_DETACH:
+            /* Last reference? */
             if ( !--gnMYODBCDrvProcesses )
             {
+                /* Fini any tracing... */
                 MYODBCDbgFini();
                 if ( !gMYODBCTraceFile.fileName().isEmpty() )
                     gMYODBCTraceFile.close();
             }
             break;
+
         case DLL_THREAD_DETACH:
             if ( gnMYODBCDrvThreads )
             {
                 --gnMYODBCDrvThreads;
             }
             break;
+
         default:
             printf( "[WARNING][%s][%d] Unknown reason thread/process attach/detach
nReason=%d\n", __FILE__, __LINE__, nReason );
             break;

Modified: trunk/Driver/Driver/Library/SQLAllocHandle.cpp
===================================================================
--- trunk/Driver/Driver/Library/SQLAllocHandle.cpp	2006-10-23 21:01:06 UTC (rev 629)
+++ trunk/Driver/Driver/Library/SQLAllocHandle.cpp	2006-10-24 10:51:50 UTC (rev 630)
@@ -30,11 +30,15 @@
 #include "MYODBCDriverInternal.h"
 
 /*! 
-    \brief      <B>ODBC 3.0 API</B>
-                <BR>
-                Allocates an; environment, connection, statement or 
-                descriptor handle.
+    \brief      Allocates an; environment, connection, statement or descriptor handle.
+      
+                <P><B>Conformance:</B>
+                <P>
+                Version Introduced: ODBC 3.0 <BR>
+                Standards Compliance: ISO 92
                  
+                <P><B>Summary:</B>
+                <P>
                 Call this function to allocate an environment handle. An
                 application should have exactly one environment handle.
                                 
@@ -62,6 +66,9 @@
         
     \sa         SQLFreeHandle
 
+                <P><B>Examples:</B>
+                <P>
+
     \include    tutorial_01.c
     \include    tutorial_02.c
     \include    tutorial_05.c

Modified: trunk/Driver/Driver/Library/SQLBrowseConnectW.cpp
===================================================================
--- trunk/Driver/Driver/Library/SQLBrowseConnectW.cpp	2006-10-23 21:01:06 UTC (rev 629)
+++ trunk/Driver/Driver/Library/SQLBrowseConnectW.cpp	2006-10-24 10:51:50 UTC (rev 630)
@@ -29,6 +29,55 @@
 */
 #include "MYODBCDriverInternal.h"
 
+/*! 
+    \brief      Connects to a data source.
+
+                <P><B>Conformance:</B>
+                <P>
+                Version Introduced: ODBC 1.0
+                Standards Compliance: ODBC
+
+                <P><B>Summary:</B>
+                <P>
+                SQLBrowseConnect supports an iterative method of discovering and
enumerating the attributes 
+                and attribute values required to connect to a data source. Each call to
SQLBrowseConnect 
+                returns successive levels of attributes and attribute values. When all
levels have been 
+                enumerated, a connection to the data source is completed and a complete
connection string is 
+                returned by SQLBrowseConnect. A return code of SQL_SUCCESS or
SQL_SUCCESS_WITH_INFO indicates 
+                that all connection information has been specified and the application is
now connected to the
+                data source.
+
+    \param      nHandleType The handle type desired.
+                            \li SQL_HANDLE_ENV
+                            \li SQL_HANDLE_DBC
+                            \li SQL_HANDLE_STMT
+                            \li SQL_HANDLE_DESC
+                
+    \param      hInputHandle        The parent handle. When allocating an environment 
+                                    handle this should be NULL. When allocating a
+                                    connection handle this should be a valid environment
handle.
+                                    When allocating a statement handle this should be a
valid 
+                                    connection handle. When allocating a descriptor
handle this 
+                                    should be a valid connection handle.
+    \param      phOutputHandlePtr   Desired handle.
+    
+    \return     SQLRETURN
+
+    \retval     SQL_SUCCESS             request processed fine
+    \retval     SQL_SUCCESS_WITH_INFO   request was probably processed 
+                                        fine but generated diagnostic information
+    \retval     SQL_ERROR               request failed
+    \retval     SQL_INVALID_HANDLE      an invalid handle was given to function
+        
+    \sa         SQLFreeHandle
+
+                <P><B>Examples:</B>
+                <P>
+
+    \include    tutorial_01.c
+    \include    tutorial_02.c
+    \include    tutorial_05.c
+*/
 SQLRETURN SQL_API SQLBrowseConnectW( SQLHDBC        hDbc,
                                      SQLWCHAR *     psInConnectionString,
                                      SQLSMALLINT    nStringLength1,

Modified: trunk/Driver/examples/c/tutorial_01.c
===================================================================
--- trunk/Driver/examples/c/tutorial_01.c	2006-10-23 21:01:06 UTC (rev 629)
+++ trunk/Driver/examples/c/tutorial_01.c	2006-10-24 10:51:50 UTC (rev 630)
@@ -14,9 +14,10 @@
     /* Allocate the environment handle. */
     nReturn = SQLAllocHandle( SQL_HANDLE_ENV, NULL, &hEnv );
     /* 
-        Tell the Driver Manager and/or Driver that we are expecting ODBC v3 behaviour.
The default is ODBC v2 behaviour.
-
-        All new applications should set this to ODBC v3. This should be done before any
connections are allocated.
+        Tell the Driver Manager and/or Driver that we are expecting ODBC v3 behaviour. 
+        The default is ODBC v2 behaviour.
+        All new applications should set this to ODBC v3. 
+        This should be done before any connections are allocated.
     */
     nReturn = SQLSetEnvAttr( hEnv, SQL_ATTR_ODBC_VERSION, SQL_OV_ODBC3, 0 );