Call Level Interface Guide and Reference

Chapter 5. DB2 CLI Functions

This section provides a description of each DB2 CLI function, ordered alphabetically. There is also a table of functions by category, in the DB2 CLI Function Summary. Each description has the following sections.

• Status
• Purpose
• Syntax
• Arguments
• Usage
• Return Codes
• Diagnostics
• Restrictions
• Example
• References

Each section is described below.

Status of this Function since DB2 CLI Version 5

This section is only included in Version 2 functions that have been replaced with new functions in Version 5.

It describes what new function should be used, and how to use it in place of the old function.

Purpose

This section gives a brief overview of what the function does. It also indicates if any functions should be called before and after calling the function being described.

Each function also has a table, such as the one below which indicates which specification or standard the function conforms to. The first column indicates which level of DB2 CLI the function was first provided, the second column indicates which version (1.0, 2.0, or 3.0) of the ODBC specification the function was first provided. The last column indicates if the function is included in the ISO CLI standard.

Note:

This table indicates support of the function, some functions use a set of options that do not apply to all specifications or standards. The restrictions section will identify any significant differences.

Table 11. Sample Function Specification Table

Specification:

DB2 CLI 1.1

ODBC 1.0

ISO CLI

Syntax

This section contains the generic 'C' prototype. The generic prototype is used for all environments, including Windows.

Note:

All function arguments that are pointers are defined using the macro FAR, this macro is defined out (set to a blank) for all platforms except Windows. On Windows FAR is used to define pointer arguments as far pointers.

Arguments

This section lists each function argument, along with its data type, a description and whether it is an input or output argument.

Only SQLGetInfo() and SQLBindParameter() have parameters that are both input and output.

Some functions contain input or output arguments which are known as deferred or bound arguments.

These arguments are pointers to buffers allocated by the application, and are associated with (or bound to) either a parameter in an SQL statement, or a column in a result set. The data areas specified by the function are accessed by DB2 CLI at a later time. It is important that these deferred data areas are still valid at the time DB2 CLI accesses them.

Usage

This section provides information about how to use the function, and any special considerations. Possible error conditions are not discussed here, but are listed in the diagnostics section instead.

Return Codes

This section lists all the possible function return codes. When SQL_ERROR or SQL_SUCCESS_WITH_INFO is returned, error information can be obtained by calling SQLError().

Refer to Diagnostics for more information about return codes.

Diagnostics

This section contains a table that lists the SQLSTATEs explicitly returned by DB2 CLI (SQLSTATEs generated by the DBMS may also be returned) and indicates the cause of the error. These values are obtained by calling SQLError() after the function returns a SQL_ERROR or SQL_SUCCESS_WITH_INFO.

Refer to Diagnostics for more information about diagnostics.

Restrictions

This section indicates any differences or limitations between DB2 CLI and ODBC that may affect an application.

Example

This section contains either a code fragment, or a reference to a code fragment demonstrating the use of the function, using the generic data type definitions. The complete source used for all code fragments is available in the sqllib/samples/cli (or sqllib\samples\cli) directory. For a list of the included examples, refer to Appendix J, CLI Sample Code.

See Chapter 4, Configuring CLI/ODBC and Running Sample Applications for more information on setting up the DB2 CLI environment and accessing the sample applications.

References

This section lists related DB2 CLI functions.