SQL/CLI - A New Binding Style For SQL

Murali Venkatrao, Microsoft Corp. Michael Pizzo, Microsoft Corp.

email: muraliv @ microsoft.com [email protected]

DBMS vendor. This preprocessor "splits" the

1. Introduction
embedded SQL code between SQL statements and
In July of this year, the American and International statements in the host language. The resulting source
committees responsible for the SQL standard code is then compiled and linked in the usual way.
finalized the specification for new binding style The SQL statements are submitted to the DataBase
called the Call Level Interface (SQL/CLI) [2]. This Management System (DBMS) in some
new binding style is an addendum to the existing implementation defined fashion for execution.
SQL Standard [1], and will comprise a new part in
the next version of that standard. This paper takes a Dynamic SQL is a variant of embedded SQL which
comprehensive look at SQL/CLI and explains why it allows the application to construct SQL statements
is important to today's applications. during run time. However, these Dynamic
statements are themselves executed by Static SQL
The paper is divided into 4 sections. Section 2 statements (PREPARE, EXECUTE and EXECUTE
explains the motivation behind providing a new IMMEDIATE) embedded in the host language and
binding style and its relationship to existing binding precompiled by the DBMS specific preprocessor.
styles. It also discusses the history and evolution of
SQL/CLI. Section 3 gives an overview of SQL/CLI, 2.1.2 M o d u l e Language
exploring its various aspects and functionality. In Module Language, all the SQL statements are
Finally, Section 4 summarizes the main ideas of this present in one or more modules (for example, a
paper and takes a look at the future. compilation unit of PL/1, an object file in C, etc.).
Each module contains one or more procedures; a
2. Motivation For SQL/CLI procedure has a set of parameters and an SQL
The SQL Standard defines a data sublanguage -- statement. Each procedure may be invoked from
that is, it is used in the context of another language other modules within the application. An SQL
(called the host language) in order to perform module is written using module language and
special purpose database management tasks. The compiled and associated through a mechanism
relationship between a host language and the SQL defined by the individual DBMS.
data sublanguage is referred to as a binding style.
2.1.3 Direct Invocation
2.1 Traditional Binding Styles Direct Invocation defines a set of SQL statements
SQL-921 defines three binding styles - Embedded which can be executed directly. In direct invocation,
SQL, Module Language and Direct Invocation. A each DBMS vendor defines the method of invoking
brief discussion of each method is provided, focusing these statements, returning results, raising
only on aspects that are required to establish a conditions, and accessing diagnostic information.
motivation for SQL/CLI. The interested reader is
referred to [ 1] for comprehensive information. 2.2 Why a New Binding Style?

2.1.1 Embedded SQL 2.2.1 D B M S Independence

Embedded SQL is, by far, the most popular of the In early database systems, applications were
three traditional binding styles. In this method, SQL designed and implemented to perform custom
statements are embedded directly into the text of the business functions. Such applications were tightly
host language program. Before application code coupled to the DBMS i t s e l f - frequently, both DBMS
containing embedded SQL can be compiled, it must and the application were run on the same machine.
be precompiled using a preprocessor provided by the In today's world, database systems are increasingly
being structured as clients and servers; applications
run on a client machine with the database running
I
Throughout this paper, the term "SQL-92" refers to the (identical) on a separate server machine. This environment has
documents ANSI X3.135-1992 and ISO/IEC 9075:1992, "Database
Language SQL".
encouraged the development of generic database

72 SIGMOD R e c o r d , Vol. 24, No. 4, D e c e m b e r 1995

applications for which the target database may not be During the late 1980's, several DBMS and
known during application development. Since application vendors began to recognize the need for
embedded SQL requires an implementation specific a way to access data in heterogeneous data sources.
preprocessor, an application must, at a minimum, be Many vendors had generic applications that required
recompiled for each DBMS it is to work with. access to more than one data store. Although the
SQL language was relatively portable and
Similarly, Module and Direct Invocation rely on
interoperable, application developers needed a model
DBMS defined mechanisms for executing the SQL,
in which there was no need to recompile the
and applications written and compiled for one
application every time access to a new data store was
DBMS will not work with any other DBMS.
needed.
SQL/CLI provides DBMS independence by allowing
By late 1989 Microsoft, Lotus, Sybase and DEC had
the development of portable object modules that
jointly developed a specification called SQL
perform database operations via function calls.
Connectivity that defined a set of functions for
These function calls are implemented in a run time
database access. Around the same time, an industry
library, which is referred to as the CLI
consortium of database vendors had formed the SQL
implementation. Thus, no implementation specific Access Group (SAG) whose charter was to promote
transformations on the source code (such as
an interoperable SQL model. In June 1990, SAG
preprocessing) is required.
accepted the SQL Connectivity specification as their
2.2.2 Concurrent Processing base document for a call level interface (or CLI). For
the next two years, SAG worked assiduously on CLI
Many applications have a need to perform
and released a preliminary specification in late 1992.
concurrent operations, including concurrent database
This was adopted by ANSI SQL and ISO DBL
operations. The existence of global data areas in both
committees as the base document for a new binding
embedded SQL and module language raises the
style for SQL.
question of scope and visibility of changes by
concurrent operations to such data. Meanwhile, Microsoft Corp. released a software
development kit based on their extended version of
SQL/CLI eliminates global data areas by introducing
the CLI, called Open DataBase Connectivity (or
the concept of a handle. A handle identifies a data
ODBC). By 1993, a large number of applications
structure that resides in the CLI implementation. All
and database vendors were using the tools provided
data in the CLI implementation that is accessible to
in the ODBC SDK to implement this early version of
the application, is associated with a specific handle.
Concurrent database operations occur on different the CLI.
handles.
By the end of 1994, SAG merged into X/Open and
2.2.3 Multiple Transactions CLI activities became a working group within
The traditional binding styles use COMMIT and X/Open. The X/Open CLI was published in April
ROLLBACK statements to delimit transactions. A 1995. In July 1995, SQL/CLI was approved as an
transaction begins implicitly when the application international standard, officially called "ISO/IEC
operates on a database. This model works well in the 9075-3:1995, Information Technology - Database
case of a single transaction active on a single Languages - SQL - P a r t 3, Call-Level Interface
connection. It is difficult to extend to the case where (SQL/CLI)". ISO plans to publish the standard by
the application wants to have multiple transactions the end of this year.
active on multiple connections.
3. Overview of SQL/CLI
In SQL/CLI, there is an environment handle that SQL/CLI is a set of functions that an application can
provides a global context for database access. Within use to access SQL databases. It contains functions for
an environment, there can be one or more allocating and deallocating resources, connecting
connection handles, each of which pertains to an and disconnecting from SQL-servers, 2 executing
active transaction. While the existence of multiple SQL statements, obtaining diagnostic information,
active transactions is implementation dependent in controlling transaction termination and obtaining
SQL/CLI, the model is designed to be extensible to information about the implementation.
allow for such functionality.

2.3 Evolution o f SQL/CLI 2Throughoutthis paper,the term"SQL-servef'is used to indicate a

sourceof data for whichthereexists a CLI implementation.

SIGMOD R e c o r d , Vol. 24, N o . 4, D e c e m b e r 1995 73

3.1 System Model information, certain pieces of diagnostic
information, and the current values of connection
The SQL/CLI system model consists of three
attributes. A connection is allocated in the context of
components - an Application, a CLI
an environment. An application can be connected to
Implementation, and an SQL-server. The application
several SQL-servers at the same time and/or may
makes calls to functions defined by SQL/CLI. The
establish more than one connection to the same
CLI Implementation is a run time library that
SQL-server.
implements the CLI functions, and is linked to the
application. The CLI Implementation talks to an A statement represents the state of a single SQL
SQL-server, which processes the SQL statements. statement. Associated with a statement handle is
information about the statement's execution such as
3.2 Argument Types
dynamic parameters, the current values of statement
Each parameter to a CLI function is one of the attributes, result values and status information. A
following four types: statement is allocated in the context of a connection,
I. Input arguments let the application pass data to and a connection can contain one or more
the CLI Implementation. statements.
2. Output arguments let the CLI Implementation
return data to the application. A descriptor holds information about either columns
3. Deferred Input arguments are used to pass values or dynamic parameters. A CLI descriptor is
to dynamic parameters in an SQL statement. analogous to the SQL descriptor area in embedded
When a function is called with a deferred input SQL. Descriptors are discussed in more detail in
argument, the CLI Implementation saves the Section 3.8.
address of the argument, and retrieves the
argument value at a later time. Environments, connections and statements are
4. Deferred Output arguments are used to retrieve characterized by certain attributes. The function
column values. The CLI Implementation writes SetEnvAttrO is used to set an environment attribute.
to the deferred output argument at a time other The function GetEnvAttrO is used to obtain the
than when the function is called. current value of an environment attribute.
SetConnectAttrO and GetConnectAttrO perform
3.3 Handles and Attributes similar functions for connection attributes, as do
A handle identifies a data structure within the CLI SetStmtAttrO and GetStmtAttrO for statement
Implementation. There are four types of handles in attributes.
SQL/CLI - environment handle, connection handle,
3.4 Establishing Connections
statement handle and descriptor handle. The
function AllocHandleO is used to allocate a handle of Prior to establishing a connection, the application
any type. For example, the following call in C must allocate an environment handle and then
allocates a connection handle: allocate a connection handle in the context of that
environment. The Connect() function establishes a
SQLAI locHandle (SQL_HANDLE_DBC, connection to an SQL-server. Consider the following
EnvHandle, &ConnectionHandle) ;
call, made in C:
The first argument indicates the type of handle SQLConnect (ConnHandle, SvrName,
desired, the second argument is the handle in whose Lenl, UsrName, Len2, Auth, Len3 )
context the desired handle is to be allocated, and the
third parameter is an output parameter in which the ConnHandle is the connection handle. Every
CLI Implementation will return the desired handle. function operates in the context of one of the 4 types
of handles, and this handle is passed in as an input
An environment is a global context for database argument. SvrName is a character buffer containing
access. It contains any data that must be global to the the server name, and Lenl is the length of this
entire application such as current values of buffer, in octets. Lenl can be set to the manifest
environment attributes, defined connections and constant S Q L h I T S to indicate that SvrName is null-
information on which connection is current. terminated. In general, any string input argument to
A connection represents an association between the a function always has an associated length argument,
application and the SQL-server. Associated with a which can either contain the actual length, or can
connection is any data that must be global to the contain SQL_NTS indicating null termination.
connection as a whole, such as transaction state

74 SIGMOD R e c o r d , Vol. 24, No. 4, D e c e m b e r 1995

SvrName usually contains a "friendly name", such as since other methods of transaction delimitation are
"Payroll Database" or "Accounts Database". This available (see Section 3.11).
name maps to the actual physical server address in
an implementation defined fashion. As a result, the 3.6 Parameterized Execution
application is protected from the complexities of Statements executed through SQL/CLI may contain
networks and server addresses. UsrName and Auth dynamic parameter markers. Dynamic parameter
provide logon information which the SQL-server markers appear as question marks (?) within a
uses to authenticate the user. Len2 and Len3 indicate statement, and the SQL/CLI implementation
the length of these buffers, or contain SQL_NTS. substitutes the current values from application
memory locations at execute time. The association of
The application can allocate another connection parameter markers with application memory
handle and call Connect() to establish a second locations is called parameter binding. As an
connection to the same or different SQL-server. The alternative to binding, the application can specify
number of such connections is implementation parameter data during execute time using the
defined. PutDataO routine.
3.5 Executing SQL Statements Dynamic Parameters are useful for executing a
Once a connection is established, the application single prepared statement multiple times with
allocates a statement handle within the context of an different parameter values.
established connection. SQL/CLI requires that a
connection first be established before allocating a
3.7 CLI Cursor Model
statement handle. Many SQL statements return a set of rows from the
SQL-server. Traditional programming languages are
SQL Statements can be executed in one of two ways: not well equipped to handle such sets of rows.
1. Call Prepare() and then call Execute(). Embedded SQL and module language use the
Prepare() takes three arguments: the statement concept of a cursor to facilitate this task. A cursor is
handle, a character buffer that holds the SQL like a pointer that is positioned on a given row in the
statement to be prepared and the associated returned set of rows (sometimes called a result set).
length argument. The CLI Implementation The cursor moves (or scrolls) through the result set,
submits the statement to the SQL-server, which enabling the application to retrieve one row at a
prepares it for execution. The application then time. An SQL statement that can generate a result
calls Execute() using the same statement handle set is called a cursor specification. Embedded SQL
as it did when calling Prepare() to execute the and module language require that cursor
SQL statement. After preparing the statement, specification be executed by the OPEN statement
the application can call Execute() as many times (which opens a cursor) instead of the EXECUTE or
as it wants for repeated execution. This is EXECUTE IMMEDIATE statements.
equivalent to the PREPARE/EXECUTE
statements in embedded SQL. SQL/CLI also uses the concept of a cursor. However,
unlike embedded SQL or module language, a cursor
2,. Call ExecDirectO. This function takes as specification can be executed just like any other SQL
arguments the statement handle, the SQL statement - by PrepareO/ExecuteO or ExecDirectO.
statement to be executed, and its length. It is A cursor is automatically opened by the CLI
used to execute the statement once. It is similar Implementation. The function Fetch() moves the
to the EXECUTE IMMEDIATE method of cursor in the forward direction - each call to Fetch()
Embedded SQL, except that it can support moves the cursor to the next row in the result set.
dynamic parameters just like the
Prepare/Execute model. By default, cursors are forward-only. That is, they
can move only in the forward direction. The
The SQL statements that can be executed are any application can set the statement attribute
SQL statement that can be prepared using dynamic SQL_A'VrR_CURSOR_SCROLLABLE to
SQL, as specified in SQL-92: CREATE, cursor- SQL_SCROLLABLE, to enable scrollable cursors.
specification, searched DELETE, dynamic This enables the application to move the cursor both
positioned DELETE, DROP, GRANT, INSERT, forwards and backwards. In SQL-92, scrollable
REVOKE, searched UPDATE, dynamic positioned cursors are required to be supported at the
UPDATE. COMMIT and ROLLBACK statements Intermediate SQL level [ 1]. The function
are specifically excluded from execution using CLI

SIGMOD R e c o r d , Vol. 24, N o . 4, D e c e m b e r 1995 75

FetchScrollO is used to move the cursor in any TYPE field is an integer field which contains the
direction. This function takes as arguments the data type code. In the IRD, this field indicates the
statement handle, a flag indicating the direction to data type of the column on the SQL-server. In the
move, and an offset. The flag and offset arguments ARD, this indicates the data type of the application
together determine the row on which the cursor is buffer that will hold this column. By specifying a
positioned. For example, if flag is different type in the ARD, the application can
SQL_FETCH_RELATIVE and offset is 10, then the perform data conversion. Similarly, the TYPE field
cursor is moved 10 rows forward. in IPD contains the data type of a dynamic parameter
as it appears on the SQL-server. The application can
By associating application memory areas with result
specify a different TYPE field in APD to indicate
set columns (known as column binding), the
that the CLI Implementation has to convert data
application can also retrieve a row into its buffers
before performing the execution.
when it calls Fetch() or FetchScrollO. We will
examine this, and other ways of retrieving result set Other fields in a detail record describe a dynamic
columns, in the next section. parameter or a result set column in greater detail.
For example, the LENGTH field in IRD or IPD
3.8 C L I Descriptor Areas indicates the maximum length, in characters, of a
SQL/CLI exposes functions for accessing the character dynamic parameter or result set column.
descriptor areas defined in Dynamic SQL. These The OCTET_LENGTH field in the ARD is set to the
descriptor areas are used to describe dynamic length of the buffer that is bound to a column.
parameters and result columns. Descriptors are
accessed through descriptor handles. A descriptor is The descriptor areas contain 3 deferred fields -
DATA_PTR, INDICATOR_PTR and
describes one of the following:
OCTET_LENGTH_PTR. When an application
1. A set of zero or more dynamic parameters. There
wants to bind to a result set column, it sets the
are 2 types of parameter descriptors:
DATA_PTR field in ARD to the address of a
• The application parameter descriptor or APD, variable which is to hold the data. When Fetch() or
which holds information about the application FetchScrollO is called, the CLI Implementation
variables that supply dynamic parameter populates this buffer with column data. Similarly,
values. the application can set the DATA_PTR field of the
• The implementation parameter descriptor or APD to the address of a buffer which will hold the
IPD, which holds information about the same parameter data. Prior to calling Execute() or
parameters after any specified data conversions. ExecDirectO, the application populates this buffer
with the actual parameter data.
2. A single row of result data. There are 2 types of
row descriptors: The application sets the INDICATOR_PTR field in
• The implementation row descriptor or IRD, the ARD or APD to the address of a variable which
which contains a description of a row from the will contain indicator information. An indicator
database. variable is used to transmit the SQL NULL value to
and from host languages that may not have
• The application row descriptor or ARD, which
representations for NULL character or numeric
contains the row, after any data conversions
values. The application sets the
that the application may specify.
OCTET LENGTH_PTR field in the ARD or APD to
A descriptor is a conceptual table with a header the address of a variable which will contain the
record and one or more detail records. The header actual number of octets for a result set column or
record contains fields which describe the table as a dynamic parameter.
whole, such as a COUNT field indicating the
number of detail records available. For ARD and When a statement handle is allocated, the CLI
IRD, this is the number of columns in the result set. Implementation automatically allocates 4 descriptors
For APD and IPD, this is the number dynamic - the IRD, IPD, ARD and APD - and associates
parameters. them with the statement handle. The application can
also call AllocHandleO to explicitly allocate a
Each detail record describes one result set column or descriptor. Explicitly allocated descriptors can be
dynamic parameter. There are many fields in a detail associated as the ARD or APD on a statement handle
record, and we will not attempt to cover all of them through SetStmtAttrO. The IRD and the IPD cannot
here. The interested reader is referred to [2]. The be replaced. The CopyDescO function copies fields

76 SIGMOD R e c o r d , Vol. 24, No. 4, D e c e m b e r 1995

from one descriptor to another. including the 5 character SQLSTATE 3,
MESSAGE_TEXT and the implementation
3.9 Concise Functions dependent error or warning text.
The operation of binding to a result set column using
SetDescFieldO requires obtaining a descriptor The application can call GetDiagFieldO to read an
handle and making multiple calls to set the individual field in the diagnostics area, or
individual descriptor fields. The function BindColO GetDiagRecO to read multiple fields in a single call.
specifies all of these values on a statement without 3.11 Transaction Demarcation
obtaining the descriptor handle. Similarly
When an application connects to an SQL-server and
BindParamO specifies multiple descriptor fields
performs work, a transaction is implicitly started.
associated with parameter binding in a single call.
The application commits or rolls back a transaction
SetDescRecO and GetDescRecO set and get multiple by calling the EndTranO function, which operates on
descriptor fields in a single call, but require a a connection handle. It is implementation defined
descriptor handle. whether it is possible to have more than one
connection, each of which has an active transaction.
Note that while these concise functions are a useful
shorthand, they are not extensible. This is because, 4. Summary and Future Directions
the fields that they can read are hard coded in their
parameter lists. GetDescFieldO and SetDescFieldO SQL/CLI defines a programming interface that
however, are extensible. consists of function calls used to do database work.
The handle based design of SQL/CLI means that
3.10 Diagnostics there is no need for global data areas - the
SQL/CLI has a rich diagnostic model to handle error application gains access to all information through a
conditions. Every function returns a return code of handle. This binding style does not need a pre-
SQL_SUCCESS when it was executed successfully. processor and hence is useful for developing portable
If a function executes successfully, but some applications.
warnings are generated (for example, when Fetch() This binding style has gained wide industry
results in column data being truncated), the function acceptance. Microsoft has announced plans for a new
returns with SQL_SUCCESS_WITH_INFO. When version of ODBC to align with the SQL/CLI
there is an error in executing the function, it returns Standard. Several new enhancements are under
SQL_ERROR. active development for the next version of SQL/CLI,
Associated with each handle in SQL/CLI is a such as the efficient handling of large data through
diagnostics area. This is a conceptual table that is locators, and improved support in the CLI for
equivalent to the diagnostics area used in embedded persistent stored modules, which provide
SQL. When a function that uses a given handle is performance gains by avoiding recompilation of SQL
called, the diagnostics area associated with this code.
handle is cleared and new diagnostic information is
written into the diagnostic area. References
[1] IS 9075 International Standard for Database
The diagnostics area has a header record and one or
Language SQL, document ISO/IEC 9075:1992,
more detail records. The header record has several
equivalent to American National Standard ANSI
fields which return information such as the return
X3.135-1992, J.Melton, Editor. October 1992
code of the underlying function, the number of detail
records, and the number of rows affected by an SQL [2] IS 9075-3 International Standard for Database
Update or Delete function. The fields in the header Language SQL - Part 3: Call Level Interface,
record are available regardless of what the return document ISO/IEC 9075-3:1995, equivalent to
code of the underlying function is. American National Standard ANSI/ISO/IEC 9075-
3:1995, J.Melton, Editor. Publication expected Fall
When the underlying function returns a code of
1995.
SQL_SUCCESS_WITH_INFO or SQL_ERROR,
additional diagnostic information is available in one
oi" more detail records of the associated diagnostics
area. Each detail record contains several fields, 3 SQLSTATE refers to 5 character codes that denote
standard error/warning situations. They are defined in
SQL-92.

a l ~ l V l t . J D l ~ e c o r d , Vol. 24, t'~o. 4, D e c e m b e r 1995 77