Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 1 Introducing Client-Library

Chapter 1

Introducing Client-Library

This chapter provides an overview of Client/Server architecture and Open Server applications:

This chapter does not contain any introductory information on developing Client-Library applications. For that information, see Chapter 1, "Getting Started With Client-Library," in the Open Client Client-Library/C Programmer's Guide.

Sybase Client/Server architecture

Client/server architecture divides the work of computing between "clients" and "servers."

Clients make requests of servers and process the results of those requests. For example, a client application might request data from a database server. Another client application might send a request to an environmental control server to lower the temperature in a room.

Servers respond to requests by returning data or other information to clients, or by taking some action. For example, a database server returns tabular data and information about that data to clients, and an electronic mail server directs incoming mail toward its final destination.

Client/Server architecture has several advantages over traditional program architectures:

• Application size and complexity can be significantly reduced, because common services are handled in a single location, a server. This simplifies client applications, reduces duplicate code, and makes application maintenance easier.

• Client/Server architecture facilitates communication between various applications. Client applications that use dissimilar communications protocols cannot communicate directly, but can communicate through a server that "speaks" both protocols.

• Client/server architecture enables applications to be developed with distinct components, which can be modified or replaced without affecting other parts of the application.

Types of clients

A client is any application that makes requests of a server. Clients include:

• Sybase middleware products such as OmniConnect(TM) and OpenSwitch(TM)

• Standalone utilities provided with Adaptive Server, such as isql and bcp

• Applications written using Open Client libraries

• Java applets and applications written using jConnect(TM) for JDBC(TM)

• Applications written using Embedded SQL(TM)

Types of servers

The Sybase product line includes servers and tools for building servers:

• Adaptive Server is a database server. Adaptive Servers manage information stored in one or more databases.

• Open Server provides the tools and interfaces needed to create a custom server application.

An Open Server application can be any type of server. For example, it can perform specialized calculations, provide access to real-time data or interface with services such as electronic mail. An Open Server application is created individually, using the building blocks provided by Open Server Server-Library.

Adaptive Server and Open Server applications are similar in some ways:

• Both servers respond to client requests.

• Clients communicate with both Adaptive Server and Open Server applications through Open Client products.

But they also differ:

• An application programmer must create an Open Server application, using Server-Library's building blocks and supplying custom code. Adaptive Server is complete and does not require custom code.

• An Open Server application can be any kind of server and can be written to understand any language. Adaptive Server is a database server and understands only Transact-SQL.

• An Open Server application can communicate with non-Sybase protocols, as well as with Sybase applications and servers. Adaptive Server can communicate directly only with Sybase applications and servers; however, Adaptive Server can communicate with non-Sybase applications and servers by using an Open Server gateway application as an intermediary.

The Open Client and Open Server products

Sybase provides two families of products to enable customers to write client and server application programs. They are:

• Open Client

• Open Server

Open Client

Open Client provides customer applications, third-party products, and other Sybase products with the interfaces needed to communicate with Adaptive Server and Open Server.

Open Client can be thought of as comprising two components, programming interfaces and network services.

Open Client provides two core programming interfaces for writing client applications: Client-Library and DB-Library

• Open Client Client-Library/C is described in this book. The Client-Library interface supports server-managed cursors and other features in System 10 and later versions of the product line.

• Open Client DB-Library is a separate API that support older Open Client applications. DB-Library is documented in the Open Client DB-Library/C Reference Manual.

Client-Library programs also depend on CS-Library, which provides routines that are used in both Client-Library and Server-Library applications. Client-Library applications can also use Bulk-Library routines to facilitate high-speed data transfer.

CS-Library and Bulk-Library are both included in the Open Client product. These libraries are described further under "Shared common libraries".

Open Client network services include Sybase Net-Library(TM), which provides support for specific network protocols such as TCP/IP and DECnet. The Net-Library interface is invisible to application programmers. However, on some platforms an application may need a different Net-Library driver for different system network configurations. Depending on your host platform, the Net-Library driver is specified either by the system's Sybase configuration, or when you compile and link your programs. (Instructions for driver configuration are in the Open Client/Server Configuration Guide. Instructions for building Client-Library programs are in the Open Client/Server Programmer's Supplement.)

Open Server

Open Server provides the tools and interfaces needed to create custom servers.

Like Open Client, Open Server consists of an interfaces component and a network services component.

The core programming interface for creating Open Server applications is Server-Library. Server-Library is documented in the Open Server Server-Library/C Reference Manual. Server-Library programs depend on Client/Server-Library (CS-Library for short). Gateway Server-Library applications can also use routines from Client-Library and Bulk-Library. Client-Library, CS-Library, and Bulk-Library are all included in the Open Server product.

Open Server network services are transparent.

Shared common libraries

The Open Client and Open Server products both include Bulk-Library and CS-Library. These libraries provide routines useful to both client applications and server applications. CS-Library and Bulk-Library are both documented in the Open Client and Open Server Common Libraries Reference Manual.

CS-Library provides utility routines for Client-Library and Open Server programs. CS-Library allocates the core data structure (the CS_CONTEXT) for Client-Library programs. CS-Library also provides facilities for data conversion and localizing the client character set and language. The type definitions for data sent between the client and server are the same for CS-Library, Client-Library, and Server-Library.

DB-Library is not integrated with CS-Library. DB-Library and CS-Library share no common data structures, and their datatype definitions differ.

Bulk-Library/C provides routines that allow Client-Library and Server-Library applications to use Adaptive Server's bulk copy interface for high speed data transfer. Client-Library programmers do not need to know Bulk-Library unless they want their applications to transfer data with the bulk copy interface. Bulk-Library, Client-Library, and Server-Library share common type definitions for data exchanged between client and server.

DB-Library has its own bulk copy interface and cannot be used with Bulk-Library.

The following diagram illustrates the relationship between the libraries included with Open Client and Open Server:

As an example, a client application might include calls to Client-Library and CS-Library, while an application that acts as both client and server might include calls to Client-Library, CS-Library, and Server-Library.

Although DB-Library is a completely separate interface from Client-Library, CS-Library, and Bulk-Library, it can be used in an Open Server gateway. It does not share Client-Library's advantages of sharing common data structures and type definitions with Server-Library.

Client-Library is a generic interface

Client-Library is a generic interface. Through Open Server and gateway applications, Client-Library applications can run against non-Sybase applications and servers as well as Adaptive Server.

Because it is generic, Client-Library does not enforce or reflect any particular server's restrictions. For example, Client-Library allows text and image stored procedure parameters, but Adaptive Server does not.

When writing a Client-Library application, keep the application's ultimate target server in mind. If you are unsure about what is legal on a server and what is not, consult your server documentation.

An application can call ct_capability to find out what capabilities a particular client/server connection supports.

Comparing the library approach to Embedded SQL

Either an Open Client library application or an Embedded SQL application can be used to send SQL commands to Adaptive Server.

An Embedded SQL application includes SQL commands in-line. The Embedded SQL precompiler processes the commands into calls to Client-Library routines. All Sybase precompilers 11.0 and later use a runtime library composed solely of documented Client-Library and CS-Library calls. Basically, the precompiler transforms an Embedded SQL application into a Client-Library application, which is then compiled using the host-language compiler.

An Open Client library application sends SQL commands through library routines and does not require a precompiler.

Generally, an Embedded SQL application is easier to write and debug, but a library application can take fuller advantage of the flexibility and power of Open Client routines.

What an application developer needs to know

Programming interfaces

New Client-Library programmers will need to learn some or all of following programming interfaces:

• Client-Library, a collection of routines for use in writing client applications. Client-Library routines begin with "ct_", as in ct_init. These are documented in Chapter 3, "Routines".

• CS-Library, a collection of utility routines that are useful to both client and server applications. All Client-Library applications will include at least one call to CS-Library, because Client-Library routines use a structure that is allocated in CS-Library. CS-Library routines begin with "cs_", as in cs_ctx_alloc. These routines are documented in the CS-Library chapters of the Open Client and Open Server Common Libraries Reference Manual.

• Bulk-Library, a collection of routines that allow Client-Library and Server-Library applications to use the Adaptive Server's bulk copy interface for high-speed data transfer. Client-Library programmers do not need to know Bulk-Library unless they want their program to transfer data using the bulk copy interface. Bulk-Library routines begin with "blk_", as in blk_alloc. These routines are documented in the Bulk-Library chapters of the Open Client and Open Server Common Libraries Reference Manual.

Client-Library programmers must also know something about the server to which their client program connects.

• For connections to Adaptive Server, a client application developer should know the Transact-SQL language, Sybase's implementation of Structured Query Language that allows access to Adaptive Server databases. Client application programmers must also be familiar with the tables and stored procedures that are in the Adaptive Server databases used by the application.

• For connections to Open Server gateways or other Open Server applications, the client application developer should know the feature set supported by the server. For example, not all Open Servers support language commands. Some only provide a collection of available registered procedures for RPC commands. When the server does support language commands, the client programmer must know the supported query language.

Getting started

For a quick tour of Client-Library functionality, including a simple example program, see Chapter 1, "Getting Started With Client-Library," in the Open Client Client-Library/C Programmer's Guide.

Changes in this version

Version 12.5 provides the following new features:

• Wide data capability and data for a larger number of columns. See "Wide tables and larger page sizes" in Chapter 2, Topics, for more details.

• LDAP. See the chapters of the Configuration Guide for your platform on directory services for further information.

• SSL. See the chapters of the Configuration Guide for your platform on security services for further information.

• Unichar. See "Unichar datatype" in Chapter 2, Topics, for more details.

New properties

Table 1-1lists new properties and datatypes in this version: