The best way to get a feel for the capabilities of the library is to provide some simple examples.

In the following code a connection is established to an ODBC provider which establishes a connection to a remote datasource.      This example assumes that  ODBC has configuration has been configured to provide a Data Source Name (DSN) called MyDSN which connects to the database server.    This server could be MS-SQL, Oracle, MySQL, PostGres (or whatever).       All connections are made using 'Connection Strings' which will vary from provider to provider,  and an understanding of what the provider requires in this connection string will be needed by the programmer.

Once the connection has been established then the program excecutes a simple query on the database by creating a recordset object then opening the object with an SQL query string.    In this case it assumes there is a table called 'billing' that has the columns: 'date','time','duration','telno','rate','cost'.     

The program then steps through the returned recordset data using the cursor manipulation functions (adoRSetMoveFirst(), adoRSetMoveNext() etc),  and prints out the values of the various fields,   before closing the recordset and the connection.

The code is as follows:

// This include file is provided with the libary and contains standard constant definitions.

$include "ado.inc"

main

    int conHandle;

    int setHanldle;

    int x;

    // Turn on trace of ado function entry, function exit and events

    adoTrace(1);

    // Get a private adoConnection object handle (named "MyConn")

    conHandle=adoConnection("MyConn",0);

    if(conHandle < 0)

         errlog("Error getting connection handle...err=",conHandle);

         stop;

    endif

    // Open the connection...

    x=adoConnOpen(conHandle,"","","Provider=MSDASQL.1;Password=admin;User ID=postgres;Data Source=MyDSN");

    if(x < 0)

        errlog("Error opening connection...err=",x);

        stop;

    endif

    // Now get a private adRecordset object (named "MySet")

    voslog("About to get adoRecordset() handle...");

    setHandle=adoRecordset(conHandle,"MySet",0);

    if(setHandle < 0)

         errlog("Error getting recordset handle...error=",setHandle);

         stop;

    else

    // Now execute a query on the recordset

    x=adoRSetQuery(setHandle,adOpenStatic,adLockReadOnly,adCmdText,"select * from billing where cost > 1.0");

    if(x < 0)

        errlog("Error executing query...err=",x);

        stop;

    endif

    // Move to first record (this is done implicitly by the adoRSetQuery() .. but lets make it explicit for the example..)

    // ... now that the query has completed successfully, to stop the example growing too long I have stopped checking

    //         errors for every ado call (although in your application you should really keep checking for errors..)

    adoRSetMovefirst(setHandle);

    // If we get here then the query complete sucessfully...

    while(not adoRSetEOF(setHandle))

         var date:20,time:20,duration:10,cost:10,telno:50;

         adoFldGetValue(setHandle,"date",&date);

         adoFldGetValue(setHandle,"time",&time);

         adoFldGetValue(setHandle,"duration",&duration);

         adoFldGetValue(setHandle,"telno",&telno);

         adoFldGetValue(setHandle,"cost",&cost);

        applog("Date=",date," Time=",time," Dur=",duration," Telno=",telno," cost=",cost);

       

         // MoveNext

         adoRSetMovefirst(setHandle);

    endwhile

    adoRSetClose(setHandle);

    adoConnClose(contHandle);

endmain

In the following example I create a table called 'billing' using the adoRSetCmd() function...

// This include file is provided with the libary and contains standard constant definitions.

$include "ado.inc"

main

    int conHandle;

    int setHanldle;

    int x;

    // Turn on trace of ado function entry, function exit and events

    adoTrace(1);

    // Get a private adoConnection object handle (named "MyConn")

    conHandle=adoConnection("MyConn",0);

    if(conHandle < 0)

         errlog("Error getting connection handle...err=",conHandle);

         stop;

    endif

    // Open the connection...

    x=adoConnOpen(conHandle,"","","Provider=MSDASQL.1;Password=admin;User ID=postgres;Data Source=MyDSN");

    if(x < 0)

        errlog("Error opening connection...err=",x);

        stop;

    endif

    // Now get a private adRecordset object (named "MySet")

    voslog("About to get adoRecordset() handle...");

    setHandle=adoRecordset(conHandle,"MySet",0);

    if(setHandle < 0)

         errlog("Error getting recordset handle...error=",setHandle);

         stop;

    else

create table customers (Name Text,Balance Float,DOB Date)");

    // Now execute a query on the recordset

    x=adoRSetCmd(setHandle,adOpenStatic,adLockReadOnly,adCmdText,"create table billing (date Date, time Time, duration Integer, telno Text, cost Float");

    if(x < 0)

        errlog("Error executing command...err=",x);

        stop;

    endif

    applog("Billing table has been created successfully!");

    adoRSetClose(setHandle);

    adoConnClose(contHandle);

endmain

There is  a subtle difference between the adoRSetQuery() and adoRSetCmd() functions in how the ado events are handled in order to wake up the calling task after the function completes (this only applies in blocking mode (see adBlockMode() function )).   

For  adoRSetQuery() calls the CXADO.DLL libary ignores the ExecuteComplete Event (which always occurs first even on a query that returns data) and instead waits for the FetchComplete event before waking up the calling task.    The FetchComplete event only triggers on recordsets that return one or more rows of data.     Therefore if a query is executed using the adoRSetQuery() function that does not return any rows of data, then the FetchComplete event will not be triggered and so the task will stay blocked indefinitely.     If we tried to wakeup a call to adoRSetQuery() using the ExecuteComplete event then any attempt to access the rows of data after it returns are prone to generate errors since the recordset has not completed fetching all of the rows.

In the case of the adoRSetCmd(), the calling task will be woken up as soon as the ExecuteComplete event is triggered.           

It is possible to carry out a query that returns data using the adoRSetCmd() function,  but the application would need to poll the recordset state using the adoRSetState() function to wait for the data to be fully fetched before trying to access it.          Similarly one could carry out a query that doesn't return any data using the adoRSetQuery() function so long as non-blocking mode is used (see adoBlockMode() ) and the application polls to wait for the execution to complete using the adoRSetState() function.