| |
Home |
![[Table of Contents]](/dwicons/b_toc.gif)
|
(Workplace UNIX) Introducing SQL Server |
![[-]](/dwicons/i_colpse.gif)
| Chapter 6: Building Client/ServerApplications |
SQL Server for Workplace UNIX includes products that make it easy for C programmers to develop customized client applications to access SQL Server. This chapter discusses these Sybase connectivity products, including:
SQL Server for Workplace UNIX also includes 16-bit and 32-bit ODBC Driver Kits for accessing SQL Server data from a variety of Windows or Windows NT front-end applications.
Open Client is a programming application interface (API) used to develop customized client applications that access SQL Server. The Open Client libraries manage all communications between a client application or tool and SQL Server databases.
In addition, if you purchase the Sybase Open Server product, you can develop applications that allow any data source, information application, or system service to respond to Open Client requests as if it were SQL Server.
The Open Client connectivity products:
Using Open Client for client application development ensures that when you port an application to another operating system, the application can provide the same functions, whether or not the underlying operating system supports them.
The SQL Server installation includes the following Open Client products:
These products offer a choice of interfaces to the Sybase architecture for use with third- or fourth-generation programming languages, including development tools from Sybase or other vendors.
Client-Library includes routines that you include in a C-language client application to:
A Client-Library program is compiled and run in the same way as any other C program.
Client-Library uses asynchronous processing, so that applications can make server requests while continuing to process other work. Asynchronous processing provides the following capabilities:
Client-Library is a generic interface. As such, Client-Library does not enforce or reflect any restrictions of SQL Server.
When writing a Client-Library application, keep in mind the application's ultimate target server (for example, SQL Server or an Open Server application). If you are unsure about what is legal for a particular server application, consult its documentation.
Client-Library provides the following features for developing client/server applications:
The following steps describe the basic procedure required for implementing an Open Client/C application.
Most applications use callback routines to handle Client-Library and server error and informational messages.
To send commands to SQL Server, a Client-Library application allocates three types of control structure, as shown below.
Structure | Function |
|---|---|
CS_CONTEXT | Defines a specific application "context" or operating environment |
CS_CONNECTION | Defines a specific client/server connection |
CS_COMMAND | Defines a "command space" in which commands are sent to a server |
Through these structures, a client application sets up its environment, connects to servers, sends commands, and processes results.
Clients connect to SQL Server or Open Server applications across a network. To connect with a server, the client application must:
Use Client-Library routines to connect to the server. There are several ways to determine the name of the server with which to connect. You may:
This method provides more flexibility and is particularly useful for applications that connect to several servers.
The server name is then determined by the run-time value of the DSQUERY environment variable or, if this variable is not set, the server name defaults to "SYBASE."
After Open Client learns which server to connect to, it must figure out how to make the connection. Open Client obtains this information from the network configuration files, which contain network address information for clients and servers. These files consist of entries for all servers to which a client might connect as well as Net-Library driver information. As such, they serve as the "address book" for the client.
The files used to specify client and server addresses and network drivers vary somewhat by platform. Refer to the platform-specific Open Client/Server Supplement for complete information.
After an Open Client application sends a command to a server, it processes any results generated by the command or by the server. Listed below are the results that Client-Library routine calls can return.
Result Type | Description |
|---|---|
Regular row results | Generated when SQL Server executes a Transact-SQL select statement; contains zero or more rows of data. |
Cursor row results | Generated when an application executes a Client-Library cursor open command; contains zero or more rows of data. |
Parameter results | Contains a single row of parameters (for example, message parameters or stored procedure return parameters). |
Stored procedure return status results | Generated by the execution of a stored procedure; consists of a single row containing a return status. |
Compute row results | Generated by the execution of a Transact-SQL select statement that contains a compute clause; consists of a single row containing a number of columns equal to the number of row aggregates in the compute clause. |
Message results | Contains an id, which an application can retrieve. If parameters are associated with a message, they are returned as a separate parameter result set following the message result set. |
Describe results | Indicates the existence of descriptive information returned as the result of a Dynamic SQL statement. |
Format results | Makes advance format information available to an application that needs format information before the result set is processed (for example, a gateway application that repackages SQL Server results before sending them to a foreign client). |
A single command can generate more than one type of result. For example, a Transact-SQL statement that executes a stored procedure can generate multiple regular row and compute row result sets, a parameter result set, and a return status result set. For this reason, it is important that applications be coded to handle all results that SQL Server can generate.
The simplest way for an application to process all possible results is by using a loop construct. Inside the loop, a set of switch statements implements processing of whatever type of result is currently available for processing.
Client-Library supports a wide range of datatypes. A header file provided with Open Client contains type definitions for all of the Open Client datatypes. Using type definitions hides variations in datatype implementations on different platforms, making Open Client programs more portable.
A client application declaring program variables uses Open Client type definitions in its declaration section. For example:
CS_CHAR buffer[40];
CS_INT result_type, count;
CS_MONEY profit;
In most cases, Open Client datatypes correspond directly to SQL Server datatypes.
Callbacks are user-supplied routines that are automatically called by Client-Library whenever certain triggering events, known as callback events, occur. For example, a client message callback event occurs when Client-Library generates an error message. When Client-Library recognizes a callback event, it automatically calls the appropriate callback routine.
Listed below are the types of callbacks:
Type of Callback | When Called |
|---|---|
Client Message | In response to a Client-Library error or informational message |
Completion | When an asynchronous Client-Library routine completes |
Encryption | During the connection process, in response to a SQL Server request for an encrypted password |
Negotiation | During the connection process:
|
Server Message | In response to a SQL Server error or informational message. |
Signal | In response to an operating-system SIGIO or SIGPOLL signal |
Both SQL Server and Client-Library generate messages in response to a wide range of error and informational conditions. Each error message has a number, text, and severity level.
An application can handle Client-Library and SQL Server messages using one of two methods:
Inline error handling has the advantage of being under an application's direct control, allowing the application to check for messages at times that it specifies
Advantages of callbacks are:
Most applications use callbacks to handle messages, but an application that is running on a platform and language combination that does not support callbacks must use the inline method.
To compile a Client-Library/C application, use a Sybase-certified C compiler for your platform. Compile and link your application as specified by your compiler and operating-system documentation.
All Client-Library applications require the header file provided with Open Client that contains type definitions and declarations required by Client-Library routines.
You can localize an application to run in a specific national language environment. An application that is localized typically:
The localization information of an application is described by a locale name. A locale name is a character string that represents a language/character set/sort order combination. For example, the locale name "fr" might represent the combination french/ iso_1/binary. Sybase provides some pre-defined locale names, and you can define others, as well.
When a localized Client-Library application connects to SQL Server, the server checks to see if it supports the application's language, character set, and sort order. If it does, then SQL Server handles the translation and issues messages in the client's language and character set. If SQL Server does not support the application's language, character set, or sort order, it issues a warning and does not make the connection.
Open Client Client-Library/C includes sample programs that illustrate how to use the Client-Library routines. These programs access the pubs2 sample database, which is also provided as part of your SQL Server for Workplace UNIX installation.
Net-Library furnishes a standard interface to most of the available network protocol implementations and provides transport protocol and operating system independence.
Because data can reside on any hardware platform supported by Sybase and can be accessed with common communications protocols, Net-Library's capabilities enable application development and deployment independent of the network. By specifying a Net-Library at run time, you can choose network protocols as needed.
DB-Library is the programming interface that Sybase provided with earlier releases. SQL Server for Workplace UNIX includes
DB-Library for compatibility with existing applications.
Although you can make calls to both DB-Library and Client-Library in a single application, you must treat the libraries as separate within the application. That is, you cannot use functions in one library with the structures, datatypes, commands, or result sets from the other library.
You can convert DB-Library programs to their Client-Library equivalents.
The table below lists sources of information for topics discussed in this chapter.
Topic | Source(s) of Information |
|---|---|
Callbacks |
|
Client-Library API |
|
Connection routines |
|
Control structures |
|
Client-Library Datatypes |
|
DB-Library API |
|
Error handling |
|
Localization |
|
Message handling |
|
Net-Library |
|
Results Processing |
|
|
|