SQL SERVER 6.

5
Chapter-13/1
Copyright Tata Infotech Ltd. : Copying of this document in part or full is not permitted without express authority.
OBJECTIVE
Understanding the DB-Library Interface
SCOPE
Introduction to DB-Library
Required components for DB-Library
Communication with SQL Server
DB-LIB for C and Net-Library interaction
Net-Library Architecture
Programming with DB-Library for C
SQL SERVER 6.5
Chapter-13/2
Copyright Tata Infotech Ltd. : Copying of this document in part or full is not permitted without express authority.
INTRODUCTION TO DB-LIBRARY
Microsoft SQL Server is a powerful SQL database server.
It allows clients running the Windows NT, Windows 95, Windows or MS-DOS operating
systems to access its services.
When developing applications to work with SQL Server, the approach which enters
queries from the ISQL or ISQL/w utilities doesnt prove very useful.
Through client application, which is responsible for information formatting, presentation
and other user interaction, the power of SQL Server is presented to the user.
Developing applications for SQL Server can take many forms. DB-Library is one of the
most common methods of working with SQL Server.
Understanding the DB-Library interface
Developers can write applications for SQL Server by programming with DB-Library for
C.
DB-Library for C is the C language version of the communication library for SQL
Server.
DB-Library or DB-LIB for C is an application programming interface consisting of C
functions and macros that allow to work directly with SQL Server.
The API provides different tools that are needed for sending queries to and receiving
information from SQL Server.
DB-LIB offers a set of functions which are responsible for:
Opening connections
Formatting queries
Sending query batches to the server and retrieving the resulting data.
Using scrollable cursors
Bulk-copying data
Controlling Two-Phase Commit operations
Executing stored procedures or remote stored procedures
SQL SERVER 6.5
Chapter-13/3
Copyright Tata Infotech Ltd. : Copying of this document in part or full is not permitted without express authority.


Required components for DB-LIB

To use DB-LIB, some files need to be included with the project.

WINDOWS.H
SQLDB.H
SQLFRONT.H
NTWDBLIB.DLL ( A Dynamic Link Library which stores the DB-LIB functions.
The DLL is included in the same directory as your application )
NTWDLIB.LIB ( An import library containing function definitions that your
application use. This file need to be created )
To create DB-Library applications for Windows NT, following software is needed.
Microsoft Windows NT Workstation / Server version 3.5 or later .
Microsoft Visual C++ version 2.0 or later, or 100% compatible compiler and linker.
Determining the DB-LIB for C version
For Windows and Windows NT, run the SQL Client Configuration Utility to
determine which version of DB-LIB is installed on your computer.
This utility searches the path for the appropriate DLL to load.
Run the utility from the same working directory as your application.
Communicating with SQL Server
Two structures are used to establish connection to SQL Server.
a) DBPROCESS
b) LOGINREC
DB-LIB functions communicate with SQL Server through the DBPROCESS
structure.
dbopen function allocates and initialises a DBPROCESS when it logs on to the SQL
Server.
DBPROCESS serves as the connection between the application and SQL Server.
An application can have more than one DBPROCESS if, for instance, it needs to
update a database while still processing the results of a previous query.
Each DBPROCESS is completely independent of any other.
Another structure, LOGINREC, allocated by dblogin, is the login record that contains
information that dbopen function uses to log on to SQL Server. It contains typical
login information, such as the user name and the password.
In Windows NT, each connection is a separate execution thread that is spawned when
the connection to SQL Server is established with dbopen and terminated when the
connection is closed using dbclose.
SQL SERVER 6.5
Chapter-13/4
Copyright Tata Infotech Ltd. : Copying of this document in part or full is not permitted without express authority.
DB-LIB for C and Net-Library interaction
When a call is made to open a connection to SQL Server (dbopen), DB-LIB
determines which client-side Net-Library should be loaded to communicate with SQL
Server.
Net Libraries are implemented as Dynamic Link Libraries, and multiple Net-Libraries
can be loaded simultaneously.
Net Library Architecture
Microsoft SQL Server Net Library architecture for client/Server applications is based
on the Net-Library concept that abstracts the client and server applications from the
underlying network protocols used.
Tabular Data Stream (TDS) is the data stream protocol used by Microsoft SQL Server
to transfer requests and responses between the client and the server.
TDS is a logical data stream protocol and must be supported by a physical network
interprocess communication mechanism.
The Net-Library architecture provides a method of sending TDS across a physical
network connection, and it provides a transparent interface to DB-Library for C.
Programming with DB-Library for C
Programming with DB-Library involves following steps:
Connect to the SQL Server.
Put Transact-SQL statements into buffer and send them to SQL Server.
Process the results returned from SQL Server, one statement at a time and one row at
a time.
Results can be put in the program variables, where applications can manipulate them.
Handle DB-Library errors and SQL Server messages.
Disconnect from SQL Server.
EXAMPLE
#define DBNTWIN32
#inlude <stdio.h>
#include <windows.h>
#include <sqlfront.h>
#include <sqldb.h>
/* Declarations for the message and error handlers. */
int err_handler(PDBPROCESS, INT, INT, INT, LPCSTR, LPCSTR);
int msg_handler (PDBPROCESS, DBINT, INT, INT, LPCSTR, LPCSTR, LPCSTR,
DBUSMALLINT);
SQL SERVER 6.5
Chapter-13/5
Copyright Tata Infotech Ltd. : Copying of this document in part or full is not permitted without express authority.
main()
{
PDBPROCESS dbproc; /* connection with SQL Server */
PLOGINREC login; /* The login information */
DBCHAR fname[100];
DBCHAR lname[100];
DBCHAR address[100];
/* Installing 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);
/* Retrieves some columns from the member table in the library
database. First put the command into the command buffer */
dbcmd(dbproc, select first_name, last_name, address FROM
library..member);
dbcmd(dbproc, WHERE first_name = ARCHIE);
/* 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, fname);
dbbind(dbproc, 2, NTBSTRINGBIND, 0, lname);
dbbind(dbproc, 3, NTBSTRINGBIND, 0, address);
/*Retrieving and printing the result rows */
while(dbnextrow(dbproc) != NO_MORE_ROWS)
{
printf(%s %s %s\n, fname, lname, address);
}
}
/* Closing the connection */
dbexit();
return(0);
}
SQL SERVER 6.5
Chapter-13/6
Copyright Tata Infotech Ltd. : Copying of this document in part or full is not permitted without express authority.
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 %1d: %s\n, msgno, msgtext);
return(0);
}
Header files
All source files that contain calls to DB-LIB functions require two header files:
(a) SQLDB.H
(b) SQLFRONT.H
Before including SQLFRONT.H and SQLDB.H, the operating system must be
defined with #define as follows:
#define DBNTWIN32
WINDOWS.H file must be included for Windows, Win 95 and Win NT Operating
system, before including SQLFRONT.H and SQLDB.H.

SQLFRONT.H must be included before SQLDB.H.
SQLFRONT.H file
It defines symbolic constants, such as function return values and exit values
STDEXIT and ERREXIT.
Exit values can be used as the parameter for the C standard Library function exit.
The file also includes type definitions for datatypes that can be used in the program
variable declarations.
SQL SERVER 6.5
Chapter-13/7
Copyright Tata Infotech Ltd. : Copying of this document in part or full is not permitted without express authority.
SQLDB.H file
Contains additional type definitions and DB-Library function prototypes.
They should not be accessed directly by the program.
dberrhandle and dbmsghandle
dberrhandle installs a user-supplied error-handling function.
The function is called automatically whenever the application encounters a DB-
Library error.
dbmsghandle installs a message handling function.
The function is called in response to informational or error messages returned from
SQL Server.
dblogin
Supplies a LOGINREC structure, which DB-LIB uses to log into the SQL Server.
Two functions set entries in LOGINREC.
(a) DBSETLPWD Sets the password that DB-LIB uses when logging in.
(b) DBSETLAPP Sets the name of the application, which appears in SQL Server
sysprocess table.
dbopen
Opens a connection between the application and SQL Server.
It uses LOGINREC supplied by dblogin to log into the server.
Runs a DBPROCESS structure which serves as a conduit for information between the
application and the server.
After this function has been called, application is connected with SQL Server and can
send Transact-SQL statements to SQL Server and process the results.
Simultaneous transactions must have a distinct DBPROCESS.
Serial transactions can use the same DBPROCESS.
dbcmd
It fills the command buffer with Transact-SQL statements.
The statements then can be sent to SQL Server.
Each call, after the first, to dbcmd, adds the supplied text to the end of any text
already in the buffer.
It allows an application to send multiple statements to SQL Server and process each
statements set of results separately.
SQL SERVER 6.5
Chapter-13/8
Copyright Tata Infotech Ltd. : Copying of this document in part or full is not permitted without express authority.
dbsqlexec
Executes the command buffer.
Sends the command in the buffer to SQL Server.
Causes DB-Library to wait until SQL Server has completed execution of the query.
dbresults
Gets the results of current Transact-SQL statement ready for processing.
After dbresults returns SUCCEED, column data of the current results set is available.
dbbind
Binds result columns to program variables.
In the example, the first call to dbbind binds the first result column to the fname
variable.
When the program reads a result row by calling dbnextrow, the contents of the first
column in the result row are placed.
The datatype of the binding is NTBSTRINGBIND, one of the several binding types
available for character data.
The second call binds the second result column to the lname variable.
dbnextrow
Reads a row and places the results in the program variables specified by the earlier
dbbind calls.
Each successive call to dbnextrow reads another result row until the last row has
been read and NO_MORE_ROWS is returned.
Processing of the results must take place inside the dbnextrow loop.
This is because each call to dbnextrow overwrites the previous values in the bound
program variables.
dbexit
Closes all SQL Server connections and frees all DBPROCESS structures created
because of the application.
It is usually the last DB-Library function in the program.
SQL SERVER 6.5
Chapter-13/9
Copyright Tata Infotech Ltd. : Copying of this document in part or full is not permitted without express authority.
DB-Library Datatypes
DB-Library defines datatype tokens for SQL Server data.

These datatype constants begin with SQL (for example, SQLINT4, SQLCHAR).

DB-LIB also provides type definitions for use in program variable declarations.

These type definitions begin with the prefix DB (for example, DBINT, DBCHAR).

By using them, it is ensured that program variables will be compatible with SQL
Server datatypes.

The dbconvert function provides a way to convert data from one SQL Server
datatype to another.
Advantages Vs disadvantages of using DB Library
Disadvantages
DB-LIB is an SQL Server-specific interface layer.
Out of the other methods of working with SQL Server (ODBC and SQL OLE), this
is the least portable between back-end database servers.

Advantages

Out of the other methods of working with SQL Server (ODBC and OLE), this is a
faster way to access the information, because development is directly in the host
language.
The other options, ODBC and SQL OLE offer similar services but impose an
abstraction layer between the application and the calls to SQL Server.
There is complete control over the error trapping associated with the transactions.
SQL SERVER 6.5
Chapter-13/10
Copyright Tata Infotech Ltd. : Copying of this document in part or full is not permitted without express authority.
LAB EXERCISE
1. Write a DB-LIB application which should store the publisher details in the publishers
table.
2. Try the example given in the book after creating the relevant table.
SQL SERVER 6.5
Chapter-13/11
Copyright Tata Infotech Ltd. : Copying of this document in part or full is not permitted without express authority.
SUMMARY
DB-Library or DB-LIB for C is an application programming interface consisting of C
functions and macros that allow to work directly with SQL Server.
Two structures are used to establish connection to SQL Server.
a) DBPROCESS
b) LOGINREC
To use DB-LIB, some files need to be included with the project.

WINDOWS.H
SQLDB.H
SQLFRONT.H
NTWDBLIB.DLL
NTWDLIB.LIB
dblogin supplies a LOGINREC structure, which DB-LIB uses to log into the SQL
Server.
dbopen opens a connection between the application and SQL Server.