To connect to the database, you can call the ODBC function OdbcAllocDatabase.

The first arg is the name of the variable where you want OdbcAllocDatabase to store the database handle for this data source. You will need to pass this handle to some other ODBC functions you call. Do not quote the variable name.

The second arg is the name of the variable that you set to your connection string. What is a connection string? At its simpliest, your connection string will contain the Data Source Name prepended by DSN= and terminated with a semi-colon. For example, if your chosen Data Source Name is "Some Database", then your connection string can be:

DSN=Some Database;
When you call OdbcAllocDatabase, if it needs to get a username and password to log onto some server, then it will present a dialog to the user to have him enter that information.

If you happen to know the username and password needed, you can add those to the connection string. The username should be prepended by UID= and terminated with a semi-colon. The password should be prepended by PWD= and terminated with a semi-colon. For example, here is the connection string for the Data Source named "Some Database" with a username of jdoe and a password of blort:

DSN=Some Database;UID=jdoe;PWD=blort;
If you supply both the username and password, then OdbcAllocDatabase will not need to present any dialog to get information from the user, and will directly connect to the server. The good news is that, even if you don't supply the username and password, after OdbcAllocDatabase returns, it will have set your connection string variable to the full connection string (ie, with the username and password in it). You can then use it with OdbcAllocDatabase if you ever need to connect to that same Data Source again, and thereby bypass any connection dialog.

The third arg is the name of the variable where you want OdbcAllocDatabase to store the statement handle for this data source. A statement handle is required by other ODBC functions you call.

The fourth arg is the handle to some window you created, or omitted if none. If you supply a window, then any connection dialog that OdbcAllocDatabase presents will use your window (instead of the desktop) as its parent. This means that the user can use other programs while the connection dialog is showing. For example, you could pass a REXX GUI window handle here (gotten via GuiInfo's 'HANDLE' operation).

Here is an example of connecting to a data source named "Some Database", and letting OdbcAllocDatabase store the database handle in a variable named "MyDatabase", the statement handle in a variable named "MyStatement", and the full connection string in a variable named "ConnectString". Note: We assume ODBC functions will raise ERROR condition on failure.

DO
   /* Connect to the Data Source named "Some Database". */
   ConnectString = "DSN=Some Database;"
   OdbcAllocDatabase("MyDatabase", "ConnectString", "MyStatement")

   /* ConnectString now contains the full connection string. */
   SAY "Full connection string:" ConnectString

   CATCH ERROR
      CONDITION("M")
      RETURN
END
If you pass only the first arg, then OdbcAllocDatabase does not connect to the database. It merely allocates a database handle. You can then follow up with a call to OdbcConnect to actually connect to the database. This is useful if you need to set some connection options with OdbcAllocDatabase before connecting. Here we set the TXN option to the value COMMIT before connecting:
DO
   /* Allocate a database handle. */
   OdbcAllocDatabase("MyDatabase")

   /* Set the TXN option "COMMIT". */
   OdbcSetConnectOpt("TXN", "COMMIT")

   /* Connect to the Data Source named "Some Database". */
   ConnectString = "DSN=Some Database;"
   OdbcConnect("ConnectString", "MyStatement")

   CATCH ERROR
      CONDITION("M")
      RETURN
END