This chapter gives an overview of programming with DB-Library for C. It groups functions into categories, and gives a quick reference to the bulk copy and two-phase commit service special libraries.
Programming with DB-Library for C typically involves the following steps:
The following example shows the basic framework of many DB-Library for C applications. The program connects to SQL Server, sends a Transact-SQL SELECT statement to SQL Server, and processes the set of rows resulting from the SELECT.
For information about defining the target operating system prior to compiling your application, see Building Applications.
#define DBNTWIN32
#include <stdio.h>
#include <windows.h>
#include <sqlfront.h>
#include <sqldb.h>
// Forward declarations of the error handler and message handler.
int err_handler(PDBPROCESS, INT, INT, INT, LPCSTR, LPCSTR);
int msg_handler(PDBPROCESS, DBINT, INT, INT, LPCSTR, LPCSTR,
LPCSTR, DBUSMALLINT);
main()
{
PDBPROCESS dbproc; // The connection with SQL Server.
PLOGINREC login; // The login information.
DBCHAR name[100];
DBCHAR city[100];
// Install user-supplied error- and message-handling functions.
dberrhandle (err_handler);
dbmsghandle (msg_handler);
// Initialize DB-Library.
dbinit ();
// Get a LOGINREC.
login = dblogin ();
DBSETLUSER (login, "my_login");
DBSETLPWD (login, "my_password");
DBSETLAPP (login, "example");
// Get a DBPROCESS structure for communication with SQL Server.
dbproc = dbopen (login, "my_server");
// Retrieve some columns from the "authors" table in the
// "pubs" database.
// First, put the command into the command buffer.
dbcmd (dbproc, "select au_lname, city from pubs..authors");
dbcmd (dbproc, " where state = 'CA' ");
// Send the command to SQL Server and start execution.
dbsqlexec (dbproc);
// Process the results.
if (dbresults (dbproc) == SUCCEED)
{
// Bind column to program variables.
dbbind (dbproc, 1, NTBSTRINGBIND, 0, name);
dbbind (dbproc, 2, NTBSTRINGBIND, 0, city);
// Retrieve and print the result rows.
while (dbnextrow (dbproc) != NO_MORE_ROWS)
{
printf ("%s from %s\n", name, city);
}
}
// Close the connection to SQL Server.
dbexit ();
return (0);
}
int err_handler (PDBPROCESS dbproc, INT severity,
INT dberr, INT oserr, LPCSTR dberrstr, LPCSTR oserrstr)
{
printf ("DB-Library Error %i: %s\n", dberr, dberrstr);
if (oserr != DBNOERR)
{
printf ("Operating System Error %i: %s\n", oserr, oserrstr);
}
return (INT_CANCEL);
}
int msg_handler (PDBPROCESS dbproc, DBINT msgno, INT msgstate,
INT severity, LPCSTR msgtext, LPCSTR server,
LPCSTR procedure, DBUSMALLINT line)
{
printf ("SQL Server Message %ld: %s\n", msgno, msgtext);
return (0);
}
This example illustrates features common to most DB-Library for C applications, including:
Before including the SQLFRONT.H and SQLDB.H files, define the target operating system with #define:
Or put DBMSDOS, DBMSWIN, or DBNTWIN32 on the compilation command lines. For more information, see the examples in "Include Files," in Building Applications.
For Windows, Windows 95, and Windows NT, you must include WINDOWS.H before including the SQLFRONT.H and SQLDB.H files.
Include SQLFRONT.H before SQLDB.H. SQLFRONT.H defines symbolic constants, such as function return values and the exit values STDEXIT and ERREXIT. These exit values can be used as the parameter for the C standard library function exit. The exit values are defined appropriately for the operating system running the program. The SQLFRONT.H file also includes type definitions for datatypes that can be used in program variable declarations. These datatypes are described in Appendix B: DB-Library Datatypes.
The SQLDB.H file contains additional type definitions and DB-Library function prototypes, most of which are meant to be used only by the DB-Library functions. They should not be accessed directly by the program. To ensure compatibility with future releases of DB-Library, use the contents of SQLDB.H only as documented in this documentation.
dbcmd(dbproc, " where state = 'CA' ");
Although multiple statements can be included in the buffer, this example only shows how to send and process a single statement. DB-Library allows an application to send multiple statements (called a command batch) to SQL Server and process each statement's set of results separately.