ibm i: sql call level interface

IBM iVersion 7.2

DatabaseSQL call level interface

IBM

NoteBefore using this information and the product it supports, read the information in “Notices” on page 323.

This document may contain references to Licensed Internal Code. Licensed Internal Code is Machine Code and islicensed to you under the terms of the IBM License Agreement for Machine Code.

© Copyright IBM Corporation 1999, 2013.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

SQL call level interface . . . . . . . . 1What's new for IBM i 7.2 . . . . . . . . . . 1PDF file for SQL call level interface . . . . . . . 2Getting started with Db2 for i CLI . . . . . . . 2

Differences between Db2 for i CLI and embeddedSQL . . . . . . . . . . . . . . . . 2Advantages of using Db2 for i CLI instead ofembedded SQL . . . . . . . . . . . . 5Deciding between Db2 for i CLI, dynamic SQL,and static SQL . . . . . . . . . . . . . 6

Writing a Db2 for i CLI application . . . . . . . 6Initialization and termination tasks in a Db2 for iCLI application . . . . . . . . . . . . 7

Example: Initialization and connection in a Db2for i CLI application . . . . . . . . . . 9

Transaction processing task in a Db2 for i CLIapplication . . . . . . . . . . . . . 10

Allocating statement handles in a Db2 for iCLI application . . . . . . . . . . . 12Preparing and processing tasks in a Db2 for iCLI application . . . . . . . . . . . 12Processing results in a Db2 for i CLIapplication . . . . . . . . . . . . 13

Processing SELECT statements in a Db2 fori CLI application . . . . . . . . . 14Processing UPDATE, DELETE, MERGE,and INSERT statements in a Db2 for i CLIapplication . . . . . . . . . . . 15Processing other SQL statements in a Db2for i CLI application . . . . . . . . 15

Freeing statement handles in a Db2 for i CLIapplication . . . . . . . . . . . . 15Committing or rolling back in a Db2 for i CLIapplication . . . . . . . . . . . . 15

When to call SQLTransact() in a Db2 for iCLI application . . . . . . . . . . 16Effects of calling SQLTransact() in a Db2 fori CLI application . . . . . . . . . 16

Diagnostics in a Db2 for i CLI application . . . 16Return codes from a Db2 for i CLI application 16Db2 for i CLI SQLSTATE values . . . . . 17

Data types and data conversion in Db2 for i CLIfunctions . . . . . . . . . . . . . . 17

Other C data types in Db2 for i CLI functions 18Data conversion in Db2 for i CLI functions . . 19

Working with the XML data type . . . . . . 19Working with Extended Timestamp Precision . . 21Working with string arguments in Db2 for i CLIfunctions . . . . . . . . . . . . . . 22

Length of string arguments in Db2 for i CLIfunctions . . . . . . . . . . . . . 22String truncation in Db2 for i CLI functions . 23Interpretation of strings in Db2 for i CLIfunctions . . . . . . . . . . . . . 23

Db2 for i CLI functions . . . . . . . . . . 23Categories of Db2 for i CLI functions . . . . . 24

SQLAllocConnect - Allocate connection handle 27SQLAllocEnv - Allocate environment handle . . 30SQLAllocHandle - Allocate handle. . . . . . 33SQLAllocStmt - Allocate a statement handle . . 34SQLBindCol - Bind a column to an applicationvariable. . . . . . . . . . . . . . . 36SQLBindFileToCol - Bind LOB file reference toLOB column . . . . . . . . . . . . . 41SQLBindFileToParam - Bind LOB file reference toLOB parameter . . . . . . . . . . . . 44SQLBindParam - Bind a buffer to a parametermarker . . . . . . . . . . . . . . . 47SQLBindParameter - Bind a parameter marker toa buffer. . . . . . . . . . . . . . . 52SQLCancel - Cancel statement . . . . . . . 61SQLCloseCursor - Close cursor statement . . . 62SQLColAttribute - Return a column attribute . . 63SQLColAttributes - Obtain column attributes . . 69SQLColumnPrivileges - Get privileges associatedwith the columns of a table . . . . . . . . 70SQLColumns - Get column information for atable. . . . . . . . . . . . . . . . 73SQLConnect - Connect to a data source . . . . 77SQLCopyDesc - Copy description statement . . 80SQLDataSources - Get list of data sources . . . 81SQLDescribeCol - Describe column attributes . . 85SQLDescribeParam - Return description of aparameter marker . . . . . . . . . . . 89SQLDisconnect - Disconnect from a data source 91SQLDriverConnect - Connect to a data source . . 93SQLEndTran - Commit or roll back a transaction 97SQLError - Retrieve error information . . . . 99SQLExecDirect - Execute a statement directly 102SQLExecute - Execute a statement . . . . . 104SQLExtendedFetch - Fetch array of rows . . . 106SQLFetch - Fetch next row . . . . . . . . 108SQLFetchScroll - Fetch from a scrollable cursor 114SQLForeignKeys - Get the list of foreign keycolumns . . . . . . . . . . . . . . 116SQLFreeConnect - Free connection handle . . . 121SQLFreeEnv - Free environment handle . . . 122SQLFreeHandle - Free a handle . . . . . . 123SQLFreeStmt - Free (or reset) a statement handle 124SQLGetCol - Retrieve one column of a row ofthe result set . . . . . . . . . . . . 126SQLGetConnectAttr - Get the value of aconnection attribute . . . . . . . . . . 132SQLGetConnectOption - Return current settingof a connect option . . . . . . . . . . 133SQLGetCursorName - Get cursor name. . . . 135SQLGetData - Get data from a column . . . . 139SQLGetDescField - Get descriptor field . . . . 140SQLGetDescRec - Get descriptor record . . . 143SQLGetDiagField - Return diagnosticinformation (extensible) . . . . . . . . . 145

© Copyright IBM Corp. 1999, 2013 iii

||

SQLGetDiagRec - Return diagnostic information(concise) . . . . . . . . . . . . . . 148SQLGetEnvAttr - Return current setting of anenvironment attribute . . . . . . . . . 151SQLGetFunctions - Get functions . . . . . . 152SQLGetInfo - Get general information . . . . 155SQLGetLength - Retrieve length of a stringvalue . . . . . . . . . . . . . . . 167SQLGetPosition - Return starting position ofstring . . . . . . . . . . . . . . . 169SQLGetStmtAttr - Get the value of a statementattribute . . . . . . . . . . . . . . 172SQLGetStmtOption - Return current setting of astatement option . . . . . . . . . . . 174SQLGetSubString - Retrieve portion of a stringvalue . . . . . . . . . . . . . . . 176SQLGetTypeInfo - Get data type information 179SQLLanguages - Get SQL dialect orconformance information . . . . . . . . 184SQLMoreResults - Determine whether there aremore result sets . . . . . . . . . . . 186SQLNativeSql - Get native SQL text . . . . . 188SQLNextResult - Process the next result set . . 190SQLNumParams - Get number of parameters inan SQL statement . . . . . . . . . . . 192SQLNumResultCols - Get number of resultcolumns . . . . . . . . . . . . . . 194SQLParamData - Get next parameter for whicha data value is needed . . . . . . . . . 196SQLParamOptions - Specify an input array for aparameter . . . . . . . . . . . . . 198SQLPrepare - Prepare a statement . . . . . 200SQLPrimaryKeys - Get primary key columns ofa table . . . . . . . . . . . . . . . 204SQLProcedureColumns - Get input/outputparameter information for a procedure . . . . 206SQLProcedures - Get list of procedure names 212SQLPutData - Pass data value for a parameter 215SQLReleaseEnv - Release all environmentresources . . . . . . . . . . . . . . 217

SQLRowCount - Get row count . . . . . . 218SQLSetConnectAttr - Set a connection attribute 220SQLSetConnectOption - Set connection option 233SQLSetCursorName - Set cursor name . . . . 235SQLSetDescField - Set a descriptor field . . . 237SQLSetDescRec - Set a descriptor record . . . 239SQLSetEnvAttr - Set environment attribute . . 241SQLSetParam - Set parameter . . . . . . . 246SQLSetStmtAttr - Set a statement attribute. . . 247SQLSetStmtOption - Set statement option . . . 253SQLSpecialColumns - Get special (rowidentifier) columns . . . . . . . . . . 255SQLStatistics - Get index and statisticsinformation for a base table . . . . . . . 259SQLTablePrivileges - Get privileges associatedwith a table . . . . . . . . . . . . . 263SQLTables - Get table information . . . . . 266SQLTransact - Commit or roll back a transaction 269

Db2 for i CLI include file . . . . . . . . . 270Running Db2 for i CLI in server mode . . . . . 305

Starting Db2 for i CLI in SQL server mode . . 305Restrictions for running Db2 for i CLI in servermode . . . . . . . . . . . . . . . 306

Unicode in Db2 for i CLI . . . . . . . . . 307Examples: Db2 for i CLI applications . . . . . 308

Example: Embedded SQL and the equivalentDb2 for i CLI function calls. . . . . . . . 308Example: Using the CLI XA transactionconnection attributes . . . . . . . . . . 311Example: Interactive SQL and the equivalentDb2 for i CLI function calls. . . . . . . . 314

Notices . . . . . . . . . . . . . . 323Programming interface information . . . . . . 325Trademarks . . . . . . . . . . . . . . 325Terms and conditions. . . . . . . . . . . 325

Index . . . . . . . . . . . . . . . 327

iv IBM i: SQL call level interface

SQL call level interface

Db2® for i call level interface (CLI) is a callable Structured Query Language (SQL) programming interfacethat is supported in all DB2® environments.

A callable SQL interface is a programming interface (API) for database access that uses function calls to rundynamic SQL statements.

Db2 for i CLI is an alternative to embedded dynamic SQL. The important difference between embeddeddynamic SQL and Db2 for i CLI is how the SQL statements are run. On the IBM® i operating system, thisinterface is available to any of the Integrated Language Environment® (ILE) languages.

Db2 for i CLI also provides full Level 1 Microsoft Open Database Connectivity (ODBC) support, plusmany Level 2 functions. For the most part, ODBC is a superset of the American National StandardsInstitute (ANSI) and ISO SQL CLI standard.

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321.

What's new for IBM i 7.2Read about new or significantly changed information for the SQL CLI topic collection.v Support for Extended Timestamp Precision. See the SQLSetConnectAttr() function

SQL_ATTR_TIMESTAMP_PREC attribute for more information on how the new connection attributecan be used to tailor the behavior of CLI applications that use Timestamps. For more information onusing extended timestamp precision, see “Working with Extended Timestamp Precision” on page 21.

v SQL MetaData API changes.– SQLProcedureColumns. As part of the support for specifying default values for function and

procedure parameters, the SQLProcedureColumns function has changed the attributes of theCOLUMN_DEF result set column from a VARCHAR(3) to a DBCLOB(65535). Prior to this release,defaults for parameters were not supported so the COLUMN_DEF column was a VARCHAR(3) witha value of NULL for all parameters. In addition, the result set column REMARKS on theSQLProcedureColumns function was changed to a NVARCHAR(2000) to reflect new length limits inthe underlying, metadata catalogs in Db2 for i.

– SQLColumnAttribute. The SQLColumnAttribute function has changed the attributes of the REMARKSresult set column to NVARCHAR(2000).

How to see what's new or changed

To help you see where technical changes have been made, this information uses:v The

image to mark where new or changed information begins.

v The

image to mark where new or changed information ends.

In PDF files, you might see revision bars (|) in the left margin of new and changed information.

To find other information about what's new or changed this release, see the Memo to users.

© Copyright IBM Corp. 1999, 2013 1

PDF file for SQL call level interfaceYou can view and print a PDF file of this information.

To view or download the PDF version of this document, select SQL call level interface.

Saving PDF files

To save a PDF on your workstation for viewing or printing:1. Right-click the PDF link in your browser.2. Click the option that saves the PDF locally.3. Navigate to the directory in which you want to save the PDF.4. Click Save.

Downloading Adobe Reader

You need Adobe Reader installed on your system to view or print these PDFs. You can download a free

copy from the Adobe Web site (http://get.adobe.com/reader/) .

Getting started with Db2 for i CLITo get started with Db2 for i CLI , you must know the basics of Db2 for i CLI, how it compares toembedded SQL, and how to select the best interface for your programming needs.

It is important to understand what Db2 for i CLI, or any callable SQL interface, is based on, and compareit with existing interfaces.

ISO standard 9075:1999 – Database Language SQL Part 3: Call-Level Interface provides the standarddefinition of CLI. The goal of this interface is to increase the portability of applications by enabling themto become independent of any one database server.

ODBC provides a Driver Manager for Windows, which offers a central point of control for each ODBCdriver (a dynamic link library (DLL) that implements ODBC function calls and interacts with a specificDatabase Management System (DBMS)).

Where to find answers to additional Db2 for i CLI questions

An FAQ, which elaborates on some items discussed in this topic collection, is available on the Db2 for i

Web site .

Differences between Db2 for i CLI and embedded SQLDb2 for i CLI and embedded SQL differ in many ways.

An application that uses an embedded SQL interface requires a precompiler to convert the SQLstatements into code. Code is compiled, bound to the database, and processed. In contrast, a Db2 for iCLI application does not require precompilation or binding, but instead uses a standard set of functionsto run SQL statements and related services at run time.

This difference is important because, traditionally, precompilers have been specific to a database product,which effectively ties your applications to that product. Db2 for i CLI enables you to write portableapplications that are independent of any particular database product. This independence means that aDb2 for i CLI application does not need to be recompiled or rebound to access-different databaseproducts. An application selects the appropriate database products at run time.

SQL CLI

2 IBM i: SQL call level interface

http://get.adobe.com/reader/

http://www.ibm.com/servers/eserver/iseries/db2/clifaq.htm

http://www.ibm.com/servers/eserver/iseries/db2/clifaq.htm

Db2 for i CLI and embedded SQL also differ in the following ways:v Db2 for i CLI does not require the explicit declaration of cursors. Db2 for i CLI generates them as

needed. The application can then use the generated cursor in the normal cursor fetch model formultiple row SELECT statements and positioned UPDATE and DELETE statements.

v The OPEN statement is not necessary in Db2 for i CLI. Instead, the processing of a SELECT automaticallycauses a cursor to be opened.

v Unlike embedded SQL, Db2 for i CLI allows the use of parameter markers on the equivalent of theEXECUTE IMMEDIATE statement (the SQLExecDirect() function).

v A COMMIT or ROLLBACK in Db2 for i CLI is issued through the SQLTransact() or SQLEndTran() functioncall rather than by passing it as an SQL statement.

v For some statements, a corresponding connection attribute is provided as a different means ofaccomplishing the same function as running the statement would. For example, CLI provides aconnection attribute that can be used to free locators allocated in the CLI application. This connectionattribute is more convenient to use that the statement because it allows for an array of locators to bepassed on the SQLSetConnectAttr() API call.

v Db2 for i CLI manages statement-related information on behalf of the application, and provides astatement handle to refer to it as an abstract object. This handle avoids the need for the application touse product-specific data structures.

v Similar to the statement handle, the environment handle and connection handle provide a means to referto all global variables and connection specific information.

v Db2 for i CLI uses the SQLSTATE values defined by the X/Open SQL CAE specification. Although theformat and many of the values are consistent with values that are used by the IBM relational databaseproducts, there are differences.

v CLI uses the SQLSTATE values defined by the X/Open SQL CAE specification. Although the formatand many of the values are consistent with values that are used by the IBM relational databaseproducts, there are differences.

Despite these differences, there is an important common concept between embedded SQL and Db2 for iCLI:v Db2 for i CLI can process any SQL statement that can be prepared dynamically in embedded SQL. This

is guaranteed because Db2 for i CLI does not actually process the SQL statement itself, but passes it tothe Database Management System (DBMS) for dynamic processing.

Table 1 lists each SQL statement, and whether it can be processed using Db2 for i CLI.

Table 1. SQL statements

SQL statement Dyn 1 CLI 3

ALLOCATE CURSOR

ALLOCATE DESCRIPTOR

ASSOCIATE LOCATORS

ALTER PROCEDURE X

ALTER SEQUENCE X

ALTER TABLE X X

BEGIN DECLARE SECTION 2

CALL X X

CLOSE SQLFreeStmt()

COMMENT ON X X

COMMIT X SQLTransact(), SQLEndTran()

CONNECT (Type 1) SQLConnect()

SQL CLI

SQL call level interface 3

Table 1. SQL statements (continued)


CONNECT (Type 2) SQLConnect()

CREATE ALIAS X

CREATE FUNCTION X

CREATE INDEX X X

CREATE PROCEDURE X

CREATE SCHEMA X

CREATE SEQUENCE X

CREATE TABLE X X

CREATE TRIGGER X

CREATE TYPE X

CREATE VARIABLE X X

CREATE VIEW X X

DEALLOCATE DESCRIPTOR

DECLARE CURSOR b SQLAllocStmt()

DECLARE GLOBAL TEMPORARY TABLE X

DELETE X X

DESCRIBE SQLDescribeCol(), SQLColAttribute()

DESCRIBE CURSOR

DESCRIBE PROCEDURE

DISCONNECT SQLDisconnect()

DROP X X

END DECLARE SECTION b

EXECUTE SQLExecute()

EXECUTE IMMEDIATE SQLExecDirect()

FETCH SQLFetch()

FREE LOCATOR X SQLSetConnectAttr()

GET DESCRIPTOR

GET DIAGNOSTICS

GRANT X X

HOLD LOCATOR X

INCLUDE b

INSERT X X

LABEL X

LOCK TABLE X X

MERGE X X

OPEN SQLExecute(), SQLExecDirect()

PREPARE SQLPrepare()

REFRESH TABLE X

RELEASE SQLDisconnect()

RELEASE SAVEPOINT X

SQL CLI


Table 1. SQL statements (continued)


RENAME X

REVOKE X X

ROLLBACK X SQLTransact(), SQLEndTran()

SAVEPOINT X

SELECT X X

SET CONNECTION

SET CURRENT DEBUG MODE X

SET CURRENT DEGREE X

SET CURRENT IMPLICIT XMLPARSE OPTION X SQLSetConnectAttr()

SET DESCRIPTOR

SET ENCRYPTION PASSWORD X

SET PATH X

SET SCHEMA X

SET SESSION AUTHORIZATION X

SET RESULT SETS

SET TRANSACTION X

SIGNAL

UPDATE X X

VALUES INTO X

WHENEVER 2

Notes:1 Dyn stands for dynamic. All statements in this list can be coded as static SQL, but only those marked with

X can be coded as dynamic SQL.2 This is a non-executable statement.3 An X indicates that this statement can be processed using either SQLExecDirect() or SQLPrepare() and

SQLExecute(). If there is an equivalent Db2 for i CLI function, the function name is listed.

Each DBMS might have additional statements that can be dynamically prepared, in which case Db2 for iCLI passes them to the DBMS. There is one exception, COMMIT and ROLLBACK can be dynamicallyprepared by some DBMSs but are not passed. Instead, the SQLTransact() or SQLEndTran() should be usedto specify either COMMIT or ROLLBACK.

Advantages of using Db2 for i CLI instead of embedded SQLThe Db2 for i CLI has several key advantages over embedded SQL.v It is ideally suited for a client-server environment, in which the target database is not known when the

application is built. It provides a consistent interface for executing SQL statements, regardless of whichdatabase server to which the application is connected.

v It increases the portability of applications by removing the dependence on precompilers. Applicationsare distributed not as compiled applications or runtime libraries but as source code that ispreprocessed for each database product.

v Db2 for i CLI applications do not need to be bound to each database to which they connect.v Db2 for i CLI applications can connect to multiple databases simultaneously.

SQL CLI


v Db2 for i CLI applications are not responsible for controlling global data areas, such as the SQLDiagnostics Area and SQL descriptors, as they are with embedded SQL applications. Instead, Db2 for iCLI allocates and controls the necessary data structures, and provides a handle for the application torefer to them.

Deciding between Db2 for i CLI, dynamic SQL, and static SQLWhich interfaces you choose depends on your application.

Db2 for i CLI is ideally suited for query-based applications that require portability but not require theAPIs or utilities offered by a particular Database Management System (DBMS) (for example, catalogdatabase, backup, restore). This does not mean that using Db2 for i CLI calls DBMS-specific APIs from anapplication. It means that the application is no longer portable.

Another important consideration is the performance comparison between dynamic and static SQL.Dynamic SQL is prepared at run time, while static SQL is prepared at the precompile stage. Becausepreparing statements requires additional processing time, static SQL might be more efficient. If youchoose static over dynamic SQL, then Db2 for i CLI is not an option.

In most cases the choice between either interface is open to personal preference. Your previous experiencemight make one alternative seem more intuitive than the other.

Writing a Db2 for i CLI applicationA Db2 for i CLI application consists of a set of tasks; each task consists of a set of discrete steps. Othertasks might occur throughout the application when it runs. The application calls one or more Db2 for iCLI functions to carry out each of these tasks.

Every Db2 for i CLI application contains the three main tasks that are shown in the following figure. Ifthe functions are not called in the sequence that is shown in the figure, an error results.

The initialization task allocates and initializes resources in preparation for the main Transaction Processingtask.

The transaction processing task, the main task of the application, passes queries and modifications to theSQL to Db2 for i CLI.

The termination task frees allocated resources. The resources generally consist of data areas that areidentified by unique handles. After freeing the resources, other tasks can use these handles.

Figure 1. Conceptual view of a Db2 for i CLI application

SQL CLI


In addition to the three central tasks that control a Db2 for i CLI application, there are numerous generaltasks, such as diagnostic message handlers, throughout an application.

See “Categories of Db2 for i CLI functions” on page 24 for an overview of how the CLI functions fit intothese key task areas.Related concepts:“Db2 for i CLI functions” on page 23These Db2 for i call level interface APIs are available for database access on the IBM i operating system.Each of the Db2 for i CLI function descriptions is presented in a consistent format.

Initialization and termination tasks in a Db2 for i CLI applicationThe initialization task allocates and initializes environment handles and connection handles.

The following figure shows the function call sequences for both the initialization and termination tasks.The transaction processing task in the middle of the diagram is shown in “Transaction processing task ina Db2 for i CLI application” on page 10.

SQL CLI


The termination task frees handles. A handle is a variable that refers to a data object that is controlled byCLI. . Using handles frees the application from having to allocate and manage global variables or datastructures, such as descriptor areas, or the SQL Diagnostic Area used in embedded SQL interfaces forIBM Database Management Systems (DBMSs). An application then passes the appropriate handle when itcalls other Db2 for i CLI functions. Here are the types of handles:

Environment handle The environment handle refers to the data object that contains global information regarding thestate of the application. This handle is allocated by calling SQLAllocEnv(), and freed by callingSQLFreeEnv(). An environment handle must be allocated before a connection handle can beallocated. Only one environment handle can be allocated per application.

Figure 2. Conceptual view of initialization and termination tasks

SQL CLI


Connection handleA connection handle refers to a data object that contains information that is associated with aconnection that is managed by Db2 for i CLI. This includes general status information,transaction status, and diagnostic information. Each connection handle is allocated by callingSQLAllocConnect() and freed by calling SQLFreeConnect(). An application must allocate aconnection handle for each connection to a database server.

Statement handleStatement handles are discussed in “Transaction processing task in a Db2 for i CLI application”on page 10.

Descriptor handleA descriptor handle is available for applications that want to use certain CLI functions forreading and modifying individual bound parameter attributes on a API call basis for statementsthat have parameters or result sets associated with them. These functions can be used asalternatives to SQLBindCol() and SQLBindParameter() functions. See SQLGetDescField(),SQLGetDescRec(), SQLSetDescField(), and SQLSetDescRec() functions for more information.

Example: Initialization and connection in a Db2 for i CLI applicationThis example shows how initialization and connection work in a Db2 for iCLI application.

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./********************************************************* file = basiccon.c** - demonstrate basic connection to two datasources.** - error handling ignored for simplicity**** Functions used:**** SQLAllocConnect SQLDisconnect** SQLAllocEnv SQLFreeConnect** SQLConnect SQLFreeEnv************************************************************/

#include <stdio.h>#include <stdlib.h>#include "sqlcli.h"

intconnect(SQLHENV henv,

SQLHDBC * hdbc);

#define MAX_DSN_LENGTH 18#define MAX_UID_LENGTH 10#define MAX_PWD_LENGTH 10#define MAX_CONNECTIONS 5

intmain(){

SQLHENV henv;SQLHDBC hdbc[MAX_CONNECTIONS];

/* allocate an environment handle */SQLAllocEnv(&henv);

/* Connect to first data source */connect(henv, &hdbc[0]);

/* Connect to second data source */connect(henv, &hdbc[1]);

SQL CLI


/********* Start Processing Step *************************//* allocate statement handle, execute statement, and so forth *//********* End Processing Step ***************************/

printf("\nDisconnecting .....\n");SQLDisconnect(hdbc[0]); /* disconnect first connection */SQLDisconnect(hdbc[1]); /* disconnect second connection */SQLFreeConnect(hdbc[0]); /* free first connection handle */SQLFreeConnect(hdbc[1]); /* free second connection handle */SQLFreeEnv(henv); /* free environment handle */

return (SQL_SUCCESS);}

/********************************************************************** connect - Prompt for connect options and connect **********************************************************************/


SQLHDBC * hdbc){

SQLRETURN rc;SQLCHAR server[MAX_DSN_LENGTH + 1], uid[MAX_UID_LENGTH + 1],

pwd[MAX_PWD_LENGTH+ 1];

SQLCHAR buffer[255];SQLSMALLINT outlen;

printf("Enter Server Name:\n");gets((char *) server);printf("Enter User Name:\n");gets((char *) uid);printf("Enter Password Name:\n");gets((char *) pwd);

SQLAllocConnect(henv, hdbc);/* allocate a connection handle */

rc = SQLConnect(*hdbc, server, SQL_NTS, uid, SQL_NTS, pwd, SQL_NTS);if (rc != SQL_SUCCESS) {

printf("Error while connecting to database\n");return (SQL_ERROR);

} else {printf("Successful Connect\n");return (SQL_SUCCESS);

}}

Transaction processing task in a Db2 for i CLI applicationThe figure shows the typical order of function calls in a Db2 for i CLI application. The figure does notshow all functions or possible paths.

SQL CLI


The figure shows the steps and the Db2 for i CLI functions in the transaction processing task. This taskcontains these steps:1. “Allocating statement handles in a Db2 for i CLI application” on page 12

Figure 3. Transaction processing

SQL CLI


2. “Preparing and processing tasks in a Db2 for i CLI application”3. “Processing results in a Db2 for i CLI application” on page 134. “Freeing statement handles in a Db2 for i CLI application” on page 155. “Committing or rolling back in a Db2 for i CLI application” on page 15

The SQLAllocStmt() or SQLAllocHandle()function is needed to obtain a statement handle that is used toprocess the SQL statement. There are two methods of statement processing that can be used. By usingSQLPrepare()and SQLExecute() , the program can break the process into two steps. TheSQLBindParameter()function is used to bind program addresses to host variables used in the preparedSQL statement. The second method is the direct processing method in which SQLPrepare()andSQLExecute() are replaced by a single call toSQLExecDirect()

As soon as the statement is processed, the remaining processing depends on the type of SQL statement.For SELECT statements, the program uses functions like SQLNumResultCols(), SQLDescribeCol(),SQLBindCol(), SQLFetch(), and SQLCloseCursor() to process the result set. For statements that updatedata, SQLRowCount()can be used to determine the number of affected rows. For other types of SQLstatements, the processing is complete after the statement is processed. SQLFreeStmt()is then used in allcases to indicate that the handle is no longer needed.

Allocating statement handles in a Db2 for i CLI applicationSQLAllocStmt() allocates a statement handle. A statement handle refers to the data object that containsinformation about an SQL statement that is managed by Db2 for i call level interface (CLI).

The information about an SQL statement that is managed by Db2 for i CLI includes dynamic arguments,cursor information, bindings for dynamic arguments and columns, result values, and status information(these are discussed later). Each statement handle is associated with a connection handle.

Allocate a statement handle to run a statement. You can concurrently allocate up to 160 000 handles. Thisapplies to all types of handles, including descriptor handles that are implicitly allocated by theimplementation code.

Preparing and processing tasks in a Db2 for i CLI applicationAfter a statement handle has been allocated, there are two methods of specifying and running SQLstatements.1. Prepare, and then execute:

a. Call SQLPrepare() with an SQL statement as an argument.b. Call SQLBindParameter(), if the SQL statement contains parameter markers.c. Call SQLExecute().

2. Execute direct:a. Call SQLBindParameter(), if the SQL statement contains parameter markers.b. Call SQLExecDirect() with an SQL statement as an argument.

The first method splits the preparation of the statement from the processing. This method is used when:v The statement is processed repeatedly (typically with different parameter values). This avoids having

to prepare the same statement more than once.v The application requires information about the columns in the result set before statement processing.

The second method combines the preparation step and the processing step into one. This method is usedwhen:v The statement is processed once. This avoids having to call two functions to process the statement.v The application does not require information about the columns in the result set before the statement is

processed.

SQL CLI


Binding parameters in SQL statements in a Db2 for i call level interface (CLI) application

Both processing methods allow the use of parameter markers in place of an expression (or host variable inembedded SQL) in an SQL statement.

Parameter markers are represented by the '?' character and indicate the position in the SQL statementwhere the contents of application variables are to be substituted when the statement is processed. Themarkers are referenced sequentially, from left to right, starting at 1.

When an application variable is associated with a parameter marker, it is bound to the parameter marker.Binding is carried out by calling the SQLBindParameter() function with:v The number of the parameter markerv A pointer to the application variablev The SQL type of the parameterv The data type and length of the variable

The application variable is called a deferred argument because only the pointer is passed whenSQLBindParameter() is called. No data is read from the variable until the statement is processed. Thisapplies to both buffer arguments and arguments that indicate the length of the data in the buffer.Deferred arguments allow the application to modify the contents of the bound parameter variables, andrepeat the processing of the statement with the new values.

When calling SQLBindParameter(), it is possible to bind a variable of a different type from that requiredby the SQL statement. In this case Db2 for i CLI converts the contents of the bound variable to the correcttype. For example, the SQL statement might require an integer value, but your application has a stringrepresentation of an integer. The string can be bound to the parameter, and Db2 for i CLI converts thestring to an integer when you process the statement.

If the SQL statement uses parameter markers instead of expressions (or host variables in embedded SQL),you must bind the application variable to the parameter marker.Related concepts:“Data types and data conversion in Db2 for i CLI functions” on page 17The table shows all of the supported SQL types and their corresponding symbolic names. The symbolicnames are used in SQLBindParam() , SQLBindParameter(), SQLSetParam(), SQLBindCol(), andSQLGetData() to indicate the data types of the arguments.Related reference:“SQLBindParameter - Bind a parameter marker to a buffer” on page 52SQLBindParameter() is used to associate (bind) parameter markers in an SQL statement to applicationvariables. Data is transferred from the application to the Database Management System (DBMS) whenSQLExecute() or SQLExecDirect() is called. Data conversion might occur when the data is transferred.“SQLPrepare - Prepare a statement” on page 200SQLPrepare() associates an SQL statement with the input statement handle and sends the statement tothe DBMS to be prepared. The application can reference this prepared statement by passing the statementhandle to other functions.“SQLExecute - Execute a statement” on page 104SQLExecute() runs a statement that was successfully prepared using SQLPrepare() once or multiple times.The statement is processed with the current values of any application variables that were bound toparameter markers by SQLBindParam().“SQLExecDirect - Execute a statement directly” on page 102SQLExecDirect() directly runs the specified SQL statement. The statement can only be processed once.Also, the connected database server must be able to prepare the statement.

Processing results in a Db2 for i CLI applicationThe next step after the statement has been processed depends on the type of SQL statement.

SQL CLI


Processing SELECT statements in a Db2 for i CLI application:

If the statement is SELECT, these steps are generally needed to retrieve each row of the result set.1. Establish the structure of the result set, number of columns, column types and lengths.2. Bind application variables to columns in order to receive the data.3. Repeatedly fetch the next row of data, and receive it into the bound application variables.

Columns that were not previously bound can be retrieved by calling SQLGetData() after eachsuccessful fetch.

Note: Each of the above steps requires some diagnostic checks.

The first step requires analyzing the processed or prepared statement. If the SQL statement is generatedby the application, this step is not necessary. This is because the application knows the structure of theresult set and the data types of each column. If the SQL statement is generated (for example, entered by auser) at run time, the application needs to query:v The number of columnsv The type of each columnv The names of each column in the result set

This information can be obtained by calling SQLNumResultCols() and SQLDescribeCol() (orSQLColAttribute()) after preparing the statement or after executing the statement.

The second step allows the application to retrieve column data directly into an application variable on thenext call to SQLFetch(). For each column to be retrieved, the application calls SQLBindCol() to bind anapplication variable to a column in the result set. Similar to variables bound to parameter markers usingSQLSetParam(), columns are bound using deferred arguments. This time the variables are outputarguments, and data is written to them when SQLFetch() is called. SQLGetData() can also be used toretrieve data, so calling SQLBindCol() is optional.

The third step is to call SQLFetch() to fetch the first or next row of the result set. If any columns havebeen bound, the application variable is updated. If any data conversion is indicated by the data typesspecified on the call to SQLBindCol, the conversion occurs when SQLFetch() is called.

The last (optional) step is to call SQLGetData() to retrieve any columns that were not previously bound.All columns can be retrieved this way, provided they were not bound, or a combination of both methodscan be used. SQLGetData() is also useful for retrieving variable length columns in smaller pieces, whichcannot be done with bound columns. Data conversion can also be indicated here, as in SQLBindCol().Related concepts:“Data types and data conversion in Db2 for i CLI functions” on page 17The table shows all of the supported SQL types and their corresponding symbolic names. The symbolicnames are used in SQLBindParam() , SQLBindParameter(), SQLSetParam(), SQLBindCol(), andSQLGetData() to indicate the data types of the arguments.Related reference:“SQLBindCol - Bind a column to an application variable” on page 36SQLBindCol() is used to associate (bind) columns in a result set to application variables (storage buffers)for all data types. Data is transferred from the Database Management System (DBMS) to the applicationwhen SQLFetch() is called.“SQLColAttribute - Return a column attribute” on page 63SQLColAttribute() obtains an attribute for a column of the result set, and is also used to determine thenumber of columns. SQLColAttribute() is a more extensible alternative to the SQLDescribeCol() function.

“SQLDescribeCol - Describe column attributes” on page 85SQLDescribeCol() returns the result descriptor information (column name, type, precision) for the

SQL CLI


indicated column in the result set generated by a SELECT statement.“SQLFetch - Fetch next row” on page 108SQLFetch() advances the cursor to the next row of the result set, and retrieves any bound columns.“SQLGetData - Get data from a column” on page 139SQLGetData() retrieves data for a single column in the current row of the result set. This is an alternativeto SQLBindCol(), which transfers data directly into application variables on a call to SQLFetch().SQLGetData() can also be used to retrieve large character-based data in pieces.“SQLNumResultCols - Get number of result columns” on page 194SQLNumResultCols() returns the number of columns in the result set associated with the input statementhandle.

Processing UPDATE, DELETE, MERGE, and INSERT statements in a Db2 for i CLI application:

If the statement modifies data (UPDATE, DELETE, MERGE, or INSERT), no action is required other thanthe normal check for diagnostic messages. In this case, SQLRowCount() can be used to obtain the numberof rows affected by the SQL statement.

If the SQL statement is a Positioned UPDATE or DELETE, it is necessary to use a cursor. A cursor is amoveable pointer to a row in the result table of a SELECT statement. In embedded SQL, cursors are usedto retrieve, update or delete rows. When using Db2 for i CLI, it is not necessary to define a cursor,because one is generated automatically.

In the case of Positioned UPDATE or DELETE statements, you need to specify the name of the cursorwithin the SQL statement. You can either define your own cursor name using SQLSetCursorName(), orquery the name of the generated cursor using SQLGetCursorName(). It is best to use the generated name,because all error messages refer to this name, and not the one defined by SQLSetCursorName().Related reference:“SQLNumResultCols - Get number of result columns” on page 194SQLNumResultCols() returns the number of columns in the result set associated with the input statementhandle.

Processing other SQL statements in a Db2 for i CLI application:

If the statement neither queries nor modifies data, there is no further action other than the normal checkfor diagnostic messages.

Freeing statement handles in a Db2 for i CLI applicationSQLFreeStmt() ends processing for a particular statement handle.

This function can be used to do one or more of the following tasks:v Unbind all columnsv Unbind all parametersv Close any cursors and discard the resultsv Drop the statement handle, and release all associated resources

The statement handle can be reused provided it is not dropped.

Committing or rolling back in a Db2 for i CLI applicationThe last step for the transaction processing task is to either commit or roll back the transaction usingSQLTransact().

A transaction is a recoverable unit of work, or a group of SQL statements that can be treated as oneatomic operation. This means that all the operations within the group are to be completed (committed) orundone (rolled back), as if they were a single operation.

SQL CLI


When using Db2 for i call level interface (CLI), transactions are started implicitly with the first access tothe database using SQLPrepare(), SQLExecDirect(), or SQLGetTypeInfo(). The transaction ends when youuse SQLTransact() to either roll back or commit the transaction. This means that any SQL statementsprocessed between these are treated as one unit of work.

When to call SQLTransact() in a Db2 for i CLI application:

If you want to decide when to end a transaction, consider this information.v You can only commit or roll back the current transaction, so keep dependent statements within the

same transaction.v Various locks are held while you have an outstanding transaction. Ending the transaction releases the

locks, and allows access to the data by other users. This is the case for all SQL statements, includingSELECT statements.

v As soon as a transaction has successfully been committed or rolled back, it is fully recoverable from thesystem logs (this depends on the Database Management System (DBMS)). Open transactions are notrecoverable.

Effects of calling SQLTransact() in a Db2 for i CLI application:

Here are some effects of calling SQLTransact() in a Db2 for i call level interface (CLI) application.

When a transaction ends:v All statements must be prepared before they can be used again.v Cursor names, bound parameters, and column bindings are maintained from one transaction to the

next.v All open cursors are closed.Related reference:“SQLTransact - Commit or roll back a transaction” on page 269SQLTransact() commits or rolls back the current transaction in the connection.

Diagnostics in a Db2 for i CLI applicationThere are two levels of diagnostics for Db2 for i call level interface (CLI) functions.v Return codes from a Db2 for i CLI applicationv DB2 CLI SQLSTATEs (diagnostic messages)

Return codes from a Db2 for i CLI applicationPossible return codes for Db2 for i call level interface (CLI) functions include SQL_SUCCESS,SQL_SUCCESS_WITH_INFO, SQL_NO_DATA_FOUND, SQL_ERROR, and SQL_INVALID_HANDLE.

Each function description in “Db2 for i CLI functions” on page 23 lists the possible codes returned foreach function.

Table 2. Db2 for i CLI function return codes

Return code Value Explanation

SQL_SUCCESS 0 The function is completed successfully, no additional SQLSTATE informationavailable.

SQL_SUCCESS_WITH_INFO 1 The function is completed successfully, with a warning or other information. CallSQLError() to receive the SQLSTATE and any other error information. TheSQLSTATE has a class of 01.

SQL_NO_DATA_FOUND 100 The function returned successfully, but no relevant data is found.

SQL_ERROR -1 The function fails. Call SQLError() to receive the SQLSTATE and any other errorinformation.

SQL CLI


Table 2. Db2 for i CLI function return codes (continued)

Return code Value Explanation

SQL_INVALID_HANDLE -2 The function fails because an input handle is not valid (environment, connection orstatement handle).

SQL_NEED_DATA 99 The application tries to run an SQL statement, but Db2 for i CLI lacks parameterdata that the application indicates will be passed at run time.

Db2 for i CLI SQLSTATE valuesBecause different database servers often have different diagnostic message codes, Db2 for i call levelinterface (CLI) provides a standard set of SQLSTATE values that are defined by the X/Open SQL CAEspecification. This allows consistent message handling across different database servers.

SQLSTATE values are alphanumeric strings of 5 characters (bytes) with a format of ccsss, where ccindicates class and sss indicates subclass. Any SQLSTATE that has a class of:v 01, is a warning.v HY, is generated by the CLI driver (either Db2 for i CLI or ODBC).

The SQLError() function also returns an error code if the code is generated by the system. When theapplication is connected to an IBM database server, the error code is SQLCODE. If the code is generatedby Db2 for i CLI instead of on the system, the error code is set to -99999.

Db2 for i CLI SQLSTATE values include both additional IBM-defined SQLSTATE values that are returnedby the database server, and Db2 for i CLI-defined SQLSTATE values for conditions that are not defined inthe X/Open specification. This allows for the maximum amount of diagnostic information to be returned.When applications are run in Windows using ODBC, it is also possible to receive ODBC-definedSQLSTATE values.

Follow these guidelines for using SQLSTATE values within your application:v Always check the function return code before calling SQLError() to determine if diagnostic information

is available.v Use the SQLSTATE values rather than the error code.v To increase your application's portability, build dependencies only on the subset of Db2 for i CLI

SQLSTATE values that are defined by the X/Open specification, and return the additional Db2 for iCLI SQLSTATE values as information only. (Dependencies refers to the application making logic flowdecisions based on specific SQLSTATE values.)

v For maximum diagnostic information, return the text message along with the SQLSTATE (if applicable,the text message includes the IBM-defined SQLSTATE). It is also useful for the application to print outthe name of the function that returned the error.

Data types and data conversion in Db2 for i CLI functionsThe table shows all of the supported SQL types and their corresponding symbolic names. The symbolicnames are used in SQLBindParam() , SQLBindParameter(), SQLSetParam(), SQLBindCol(), andSQLGetData() to indicate the data types of the arguments.

Each column is described as follows:

SQL typeThis column contains the SQL data type as it appears in an SQL statement. The SQL data typesare dependent on the Database Management System (DBMS).

SQL symbolicThis column contains an SQL symbolic name that is defined (in sqlcli.h) as an integer value.This value is used by various functions to identify an SQL data type in the first column.

SQL CLI


Table 3. SQL data types and SQL symbolic names

SQL type SQL symbolic

BIGINT SQL_BIGINT

BINARY SQL_BINARY

BLOB SQL_BLOB

CHAR SQL_CHAR, SQL_WCHAR1

CLOB SQL_CLOB

DATE SQL_DATE

DBCLOB SQL_DBCLOB

DECFLOAT(7)2 SQL_DECFLOAT

DECFLOAT(16) SQL_DECFLOAT

DECFLOAT(34) SQL_DECFLOAT

DECIMAL SQL_DECIMAL

DOUBLE SQL_DOUBLE

FLOAT SQL_FLOAT

GRAPHIC SQL_GRAPHIC

INTEGER SQL_INTEGER

NUMERIC SQL_NUMERIC

REAL SQL_REAL

SMALLINT SQL_SMALLINT

TIME SQL_TIME

TIMESTAMP SQL_TIMESTAMP

VARBINARY SQL_VARBINARY

VARCHAR SQL_VARCHAR, SQL_WVARCHAR1

VARGRAPHIC SQL_VARGRAPHIC

XML SQL_XML

1 SQL_WCHAR and SQL_WVARCHAR can be used to indicate Unicode data.2 Note that there is no DECFLOAT(7) data type. However, DB2 will accept this data type from applications.

Other C data types in Db2 for i CLI functionsAs well as the data types that map to SQL data types, there are also C symbolic types used for otherfunction arguments, such as pointers and handles.

Table 4. Generic data types and actual C data types

Symbolic type Actual C type Typical usage

SQLHDBC long int Handle referencing database connection information.

SQLHENV long int Handle referencing environment information.

SQLHSTMT long int Handle referencing statement information.

SQLPOINTER void * Pointers to storage for data and parameters.

SQLRETURN long int Return code from Db2 for i CLI functions.

SQL CLI


Data conversion in Db2 for i CLI functionsDb2 for i call level interface (CLI) manages the transfer and any required conversion of data between theapplication and the Database Management System (DBMS).

Before the data transfer actually takes place, the source, target or both data types are indicated whencalling SQLBindParam(), SQLBindParameter(), SQLSetParam(), SQLBindCol() or SQLGetData(). Thesefunctions use the symbolic type names shown in Table 3 on page 18, to identify the data types involved.See “SQLFetch - Fetch next row” on page 108, or “SQLGetCol - Retrieve one column of a row of theresult set” on page 126 for examples of the functions that use the symbolic data types.

For a list of supported data type conversions in Db2 for i CLI, see the data type compatibility table inAssignments and comparisons. Other conversions can be achieved by using SQL scalar functions or theSQL CAST function in the SQL syntax of the statement being processed.

The functions mentioned in the previous paragraph can be used to convert data to other types. Not alldata conversions are supported or make sense.

Whenever truncation that is rounding or data type incompatibilities occur on a function call, eitherSQL_ERROR or SQL_SUCCESS_WITH_INFO is returned. Further information is then indicated by theSQLSTATE value and other information returned by SQLError().

Working with the XML data typeThese conventions can help you handle various aspects of using the XML data type in Db2 for i CLIfunctions.

XML data handling in CLI applications

DB2 CLI applications can retrieve and store XML data using the SQL_XML data type. This data typecorresponds to the native XML data type of the Db2 for i database, which is used to define columns thatstore well-formed XML documents. The SQL_XML type can be bound to the following C types:SQL_C_BINARY, SQL_VARBINARY, SQL_C_CHAR, SQL_VARCHAR, SQL_C_WCHAR, andSQL_WVARCHAR. Using binary types, however, instead of character types, is recommended to avoidpossible data loss or corruption resulting from CCSID conversion when character types are used. To storeXML data in an XML column, bind a binary (SQL_C_BINARY or SQL_VARBINARY) or character(SQL_C_CHAR, SQL_VARCHAR, SQL_C_WCHAR, or SQL_WVARCHAR) buffer that contains the XMLvalue to the SQL_XML SQL type and execute the INSERT or UPDATE SQL statements. To retrieve XMLdata from the database, bind the result set to a binary (SQL_C_BINARY or SQL_VARBINARY) orcharacter (SQL_C_CHAR, SQL_VARCHAR, SQL_C_WCHAR, or SQL_WVARCHAR) type. Charactertypes should be used with caution because of encoding issues. When an XML value is retrieved into anapplication data buffer, the DB2 server performs an implicit serialization on the XML value to convert itfrom its internal form to the serialized string form. For character typed buffers, the XML value isimplicitly serialized to the application CCSID associated with the character type. By default, an XMLdeclaration is included in the output serialized string. This default behavior can be changed by settingthe SQL_ATTR_XML_DECLARATION connection attribute.

XML column inserts and updates in CLI applications

When you update or insert data into XML columns of a table, the input data must be in the serializedstring format. For XML data, when you use SQLBindParameter() to bind parameter markers to input databuffers, you can specify the data type of the input data buffer as SQL_C_BINARY, SQL_VARBINARY,SQL_C_CHAR, SQL_VARCHAR_, SQL_C_WCHAR, SQL_BLOB, SQL_CLOB, SQL_BLOB_LOCATOR,SQL_CLOB_LOCATOR or SQL_VARCHAR. When you bind a data buffer that contains XML data asSQL_C_BINARY or SQL_VARBINARY, Db2 for i CLI processes the XML data as internally encoded data.This is the preferred method because it avoids the overhead and potential data loss of character

SQL CLI


conversion when character types are used. When you bind a data buffer that contains XML data asSQL_C_CHAR, SQL_VARCHAR, SQL_C_WCHAR, or SQL_WVARCHAR, DB2 CLI processes the XMLdata as externally encoded data.

Db2 for i CLI determines the encoding of the data as follows:v If the C type is SQL_C_WCHAR or SQL_WVARCHAR, CLI assumes that the data is encoded as

UCS-2.v If the C type is SQL_C_CHAR or SQL_C_VARCHAR, CLI assumes that the data is encoded in the job

CCSID.

The following example shows how to update XML data in an XML column using the recommendedSQL_C_BINARY type.char xmlBuffer[10240];integer length;

// Assume a table named dept has been created with the following statement:// CREATE TABLE dept (id CHAR(8), deptdoc XML)

// xmlBuffer contains an internally encoded XML document that is to replace// the existing XML documentlength = strlen (xmlBuffer);SQLPrepare (hStmt, "UPDATE dept SET deptdoc = ? WHERE id = ’001’", SQL_NTS);SQLBindParameter (hStmt, 1, SQL_PARAM_INPUT, SQL_C_BINARY, SQL_XML, 0, 0,

xmlBuffer, 10240, &length); SQLExecute (hStmt);

XML data retrieval in CLI applications

When you select data from XML columns in a table, the output data is in the serialized string format. ForXML data, when you use SQLBindCol() API to bind columns in a query result set to application variables,you can specify the data type of the application variables as SQL_C_BINARY, SQL_VARBINARY,SQL_C_CHAR, SQL_VARCHAR, SQL_C_WCHAR, SQL_BLOB, SQL_CLOB, SQL_BLOB_LOCATOR,SQL_CLOB_LOCATOR or SQL_WVARCHAR. When retrieving a result set from an XML column, it isrecommended that you bind your application variable to the SQL_C_BINARY or SQL_VARBINARY type.Binding to character types can result in possible data loss resulting from code page conversion. Data losscan occur when characters in the source code page cannot be represented in the target code page. Bindingyour variable to the binary types avoids these issues. XML data is returned to the application asinternally encoded data.

CLI determines the encoding of the data as follows:v If the C type is SQL_C_BINARY or SQL_VARBINARY, Db2 for i CLI returns the data in the encoding

of the column.v If the C type is SQL_C_CHAR or SQL_VARCHAR, Db2 for i CLI returns the data in job CCSID.v If the C type is SQL_C_WCHAR or SQL_WVARCHAR, Db2 for i CLI returns the data in the UCS-2

encoding scheme.

The database server performs an implicit serialization of the data before returning it to the application.You can explicitly serialize the XML data to a specific data type by calling the XMLSERIALIZE function.Implicit serialization is recommended, however, because explicitly serializing to character types withXMLSERIALIZE can introduce encoding issues.

The following example shows how to retrieve XML data from an XML column into a binary applicationvariable.char xmlBuffer[10240];// xmlBuffer is used to hold the retrieved XML documentinteger length;

// Assume a table named dept has been created with the following statement:// CREATE TABLE dept (id CHAR(8), deptdoc XML)

SQL CLI


length = sizeof (xmlBuffer);SQLExecute (hStmt, "SELECT deptdoc FROM dept WHERE id=’001’", SQL_NTS);SQLBindCol (hStmt, 1, SQL_C_BINARY, xmlBuffer, &length, NULL);SQLFetch (hStmt);SQLCloseCursor (hStmt);// xmlBuffer now contains a valid XML document encoded in UTF-8

Working with Extended Timestamp PrecisionProvides information on using the Timestamp data type with extended timestamp precision, which isavailable in release 7.2 and later, with the Db2 for i CLI functions.

Extended Timestamp Precision in CLI applications

In Db2 for i, timestamps now have increased and variable precision, with timestamp precision having arange of 0-12. To accommodate this change, CLI has been updated to allow the user to specify andretrieve the precision for timestamp parameters and columns. These changes include a means to preservethe existing behavior, since there can be unexpected side effects to your CLI applications if they are notcoded to take advantage of this new support. To preserve existing behavior, use theSQL_ATTR_TIMESTAMP_PREC connection attribute.

Using the new SQL_ATTR_TIMESTAMP_PREC connection attribute

Since changing applications to take advantage of the increased timestamp precision can take a long timeto implement and test, there is a new connection attribute, SQL_ATTR_TIMESTAMP_PREC, which can beset to SQL_TRUE to cause APIs to revert to the prior release behavior for timestamp types. This is meantas a temporary measure to allow existing applications to run with minimal modification on IBM i 7.2 ,until they can be updated to comply with the new behavior. With this attribute set, timestamps arealways treated as a 26 byte, fixed length value with a precision of 6. Applications using this attribute willbe unable to insert timestamps with a precision greater than 6 using parameter markers and anytimestamp columns fetched with greater than 6 precision will be truncated (and any column with lessthan 6 precision will be padded with zeroes).

Examples of necessary changes for Existing CLI Applications

If you do not set the new SQL_ATTR_TIMESTAMP_PREC connection attribute to SQL_TRUE, then anexisting application may see these side effects when running against a Db2 for i database in a 7.2 releaseor later, if that application binds parameters using the SQL_TYPE_TIMESTAMP type.

For example, an application calling SQLBindParameter may have passed the value 0 for the ColumnSizeparameter, since it was ignored for timestamps in earlier releases:

:char *ts = "1970-01-01 12:34:56.123456";SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_TYPE_TIMESTAMP, SQL_TYPE_TIMESTAMP, 0, 6, ts, 0, &ind);SQLExecute(hstmt);

:// If a timestamp that is bound as shown above is then passed on the SQLExecute call, it will fail with// SQLCODE -303 "Variable *N not compatible or value too long", because of the ColumnSize parameter being 0.// To correct this problem, bind the parameter as follows, with a ColumnSize parameter of 26 :

:char *ts = "1970-01-01 12:34:56.123456";SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_TYPE_TIMESTAMP, SQL_TYPE_TIMESTAMP,26, 6, ts, 0, &ind);SQLExecute(hstmt);

:

Perhaps instead, the timestamp was stored in a large buffer and the size of the buffer was passed in::

char buffer[50] = "1970-01-01 12:34:56.123456";SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_TYPE_TIMESTAMP, SQL_TYPE_TIMESTAMP, sizeof(buffer), 6, buffer, 0, &ind);

SQL CLI


|

||

|

||||||

|

|||||||||

|

|||

||

|||||||||||||

|

|||

SQLExecute(hstmt);:

// If a timestamp that is bound as shown above is then passed on the SQLExecute call, it will fail with// SQLCODE -180 ""Syntax of date, time, or timestamp value not valid.", because of the ColumnSize parameter being// sizeof(buffer), or 50.// To correct this problem, bind the parameter as follows, with a ColumnSize parameter of 26 :

:char buffer[50] = "1970-01-01 12:34:56.123456";SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_TYPE_TIMESTAMP, SQL_TYPE_TIMESTAMP,26, 6, ts, 0, &ind);SQLExecute(hstmt);

:

Note that the same problem occurs when binding timestamp types on Db2 for i CLI SQLBindParam andSQLBindCol functions.

To fix the problems described in the examples above, use either the corrective action shown in theexample or something similar to insure the ColumnSize parameter is set properly. Here are the details onthe changes for the parameters for the SQLBindParameter, SQLBindParam, and the SQLBindColfunctions:v SQLBindParameter, ColumnSize must be between 19 and 32 and DecimalDigits must be between 0 and

12.v SQLBindParam, cbParamDef must be between 19 and 32 and ibScale must be between 0 and 12.v SQLBindCol, cbValueMax must be greater than or equal to 19.

The easiest way to always ensure these values are correct is to use the information retrieved usingSQLDescribeParam for parameter markers and SQLDescribeCol or SQLColAttribute for columns.

Working with string arguments in Db2 for i CLI functionsThese conventions can help you handle various aspects of string arguments in Db2 for i call levelinterface (CLI) functions.

Length of string arguments in Db2 for i CLI functionsInput string arguments have an associated length argument.

The length argument indicates to Db2 for i call level interface (CLI) either the length of the allocatedbuffer (not including the null byte terminator) or the special value SQL_NTS. If SQL_NTS is passed, Db2for i CLI determines the length of the string by locating the null terminating character.

Output string arguments have two associated length arguments, one to specify the length of the allocatedbuffer and one to return the length of the string returned by Db2 for i CLI. The returned length value isthe total length of the string available for return, whether it fits in the buffer or not.

For SQL column data, if the output is an empty string, SQL_NULL_DATA is returned in the lengthargument.

If a function is called with a null pointer for an output length argument, Db2 for i CLI does not return alength. This might be useful when it is known that the buffers are large enough for all possible results. IfDb2 for i CLI attempts to return the SQL_NULL_DATA value to indicate a column contains null data andthe output length argument is a null pointer, the function call fails.

Every character string that Db2 for i CLI returns is terminated with a null terminating character(hexadecimal 00), except for strings that are returned from graphic data types. This requires that allbuffers allocate enough space for the maximum number that is expected, plus one for thenull-terminating character.

SQL CLI


|||||||||||

||

||||

||

|

|

||

String truncation in Db2 for i CLI functionsIf an output string does not fit into a buffer, Db2 for i call level interface (CLI) truncates the string to alength that is one less than the size of the buffer, and writes the null terminator.

If truncation occurs, the function returns SQL_SUCCESS_WITH_INFO and an SQLSTATE by indicatingtruncation. The application can then compare the buffer length to the output length to determine whichstring is truncated.

For example, if SQLFetch() returns SQL_SUCCESS_WITH_INFO, and an SQLSTATE of 01004, at least oneof the buffers bound to a column is too small to hold the data. For each buffer that is bound to a column,the application can compare the buffer length with the output length and determine which column istruncated.

Interpretation of strings in Db2 for i CLI functionsDb2 for i call level interface (CLI) ignores case and removes leading and trailing blanks for all stringinput arguments, such as column names and cursor names.

There are also some exceptions for this rule:v Any database datav Delimited identifiers that are enclosed in double quotation marks)v Password arguments

Db2 for i CLI functionsThese Db2 for i call level interface APIs are available for database access on the IBM i operating system.Each of the Db2 for i CLI function descriptions is presented in a consistent format.

See Categories of Db2 for i CLIs for a categorical listing of the functions.

How the CLI functions are described

The following table shows the type of information that is described in each section of the functiondescription.

Type Description

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

Syntax This section contains the C language prototype for the IBM i environment.

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

Each Db2 for i CLI argument is either an input or output argument. With the exceptionof SQLGetInfo(), Db2 for i CLI only modifies arguments that are indicated as output.

Some functions contain input or output arguments which are known as deferred or boundarguments. These arguments are pointers to buffers allocated by the application. Thesearguments are associated with (or bound to) either a parameter in an SQL statement, ora column in a result set. The data areas specified by the function are accessed by Db2 fori CLI at a later time. It is important that these deferred data areas are still valid at thetime Db2 for i CLI accesses them.

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

SQL CLI


Type Description

Return codes This section lists all the possible function return codes. When SQL_ERROR orSQL_SUCCESS_WITH_INFO is returned, error information can be obtained by callingSQLError().

Refer to “Diagnostics in a Db2 for i CLI application” on page 16 for more informationabout return codes.

Diagnostics This section contains a table that lists the SQLSTATEs explicitly returned by Db2 for iCLI (SQLSTATEs generated by the Database Management System (DBMS) might also bereturned) and indicates the cause of the error. These values are obtained by callingSQLError() after the function returns SQL_ERROR or SQL_SUCCESS_WITH_INFO.

An * in the first column indicates that the SQLSTATE is returned only by Db2 for i CLI,and is not returned by other ODBC drivers.

Refer to “Diagnostics in a Db2 for i CLI application” on page 16 for more informationabout diagnostics.

Restrictions This section indicates any differences or limitations between Db2 for i CLI and ODBCthat might affect an application.

Example This section is a code fragment demonstrating the use of the function. The completesource used for all code fragments is listed in “Examples: Db2 for i CLI applications” onpage 308.

References This section lists related Db2 for i CLI functions.

Categories of Db2 for i CLI functionsThe list shows the Db2 for i CLI functions by category.v Connecting

– “SQLConnect - Connect to a data source” on page 77– “SQLDataSources - Get list of data sources” on page 81– “SQLDisconnect - Disconnect from a data source” on page 91– “SQLDriverConnect - Connect to a data source” on page 93

v Diagnostics

– “SQLError - Retrieve error information” on page 99– “SQLGetDiagField - Return diagnostic information (extensible)” on page 145– “SQLGetDiagRec - Return diagnostic information (concise)” on page 148

v MetaData

– “SQLColumns - Get column information for a table” on page 73– “SQLColumnPrivileges - Get privileges associated with the columns of a table” on page 70– “SQLForeignKeys - Get the list of foreign key columns” on page 116– “SQLGetInfo - Get general information” on page 155– “SQLGetTypeInfo - Get data type information” on page 179– “SQLLanguages - Get SQL dialect or conformance information” on page 184– “SQLPrimaryKeys - Get primary key columns of a table” on page 204– “SQLProcedureColumns - Get input/output parameter information for a procedure” on page 206– “SQLProcedures - Get list of procedure names” on page 212– “SQLSpecialColumns - Get special (row identifier) columns” on page 255– “SQLStatistics - Get index and statistics information for a base table” on page 259– “SQLTablePrivileges - Get privileges associated with a table” on page 263– “SQLTables - Get table information” on page 266

SQL CLI


v Processing SQL statements

– “SQLBindCol - Bind a column to an application variable” on page 36– “SQLBindFileToCol - Bind LOB file reference to LOB column” on page 41– “SQLBindFileToParam - Bind LOB file reference to LOB parameter” on page 44– “SQLBindParam - Bind a buffer to a parameter marker” on page 47– “SQLBindParameter - Bind a parameter marker to a buffer” on page 52– “SQLCancel - Cancel statement” on page 61– “SQLCloseCursor - Close cursor statement” on page 62– “SQLColAttributes - Obtain column attributes” on page 69– “SQLDescribeCol - Describe column attributes” on page 85– “SQLDescribeParam - Return description of a parameter marker” on page 89– “SQLEndTran - Commit or roll back a transaction” on page 97– “SQLExecDirect - Execute a statement directly” on page 102– “SQLExecute - Execute a statement” on page 104– “SQLExtendedFetch - Fetch array of rows” on page 106– “SQLFetch - Fetch next row” on page 108– “SQLFetchScroll - Fetch from a scrollable cursor” on page 114– “SQLGetCursorName - Get cursor name” on page 135– “SQLGetData - Get data from a column” on page 139– “SQLGetDescField - Get descriptor field” on page 140– “SQLGetDescRec - Get descriptor record” on page 143– “SQLMoreResults - Determine whether there are more result sets” on page 186– “SQLNativeSql - Get native SQL text” on page 188– “SQLNextResult - Process the next result set” on page 190– “SQLNumParams - Get number of parameters in an SQL statement” on page 192– “SQLNumResultCols - Get number of result columns” on page 194– “SQLParamData - Get next parameter for which a data value is needed” on page 196– “SQLParamOptions - Specify an input array for a parameter” on page 198– “SQLPrepare - Prepare a statement” on page 200– “SQLPutData - Pass data value for a parameter” on page 215– “SQLRowCount - Get row count” on page 218– “SQLSetCursorName - Set cursor name” on page 235– “SQLTransact - Commit or roll back a transaction” on page 269

v Working with attributes

– “SQLGetCol - Retrieve one column of a row of the result set” on page 126– “SQLGetConnectAttr - Get the value of a connection attribute” on page 132– “SQLGetConnectOption - Return current setting of a connect option” on page 133– “SQLGetCursorName - Get cursor name” on page 135– “SQLGetData - Get data from a column” on page 139– “SQLGetDescField - Get descriptor field” on page 140– “SQLGetDescRec - Get descriptor record” on page 143– “SQLGetEnvAttr - Return current setting of an environment attribute” on page 151– “SQLGetFunctions - Get functions” on page 152– “SQLGetInfo - Get general information” on page 155– “SQLGetLength - Retrieve length of a string value” on page 167

SQL CLI


– “SQLGetPosition - Return starting position of string” on page 169– “SQLGetStmtAttr - Get the value of a statement attribute” on page 172– “SQLGetStmtOption - Return current setting of a statement option” on page 174– “SQLGetSubString - Retrieve portion of a string value” on page 176– “SQLGetTypeInfo - Get data type information” on page 179– “SQLSetConnectAttr - Set a connection attribute” on page 220– “SQLSetConnectOption - Set connection option” on page 233– “SQLSetCursorName - Set cursor name” on page 235– “SQLSetDescField - Set a descriptor field” on page 237– “SQLSetDescRec - Set a descriptor record” on page 239– “SQLSetEnvAttr - Set environment attribute” on page 241– “SQLSetParam - Set parameter” on page 246– “SQLSetStmtAttr - Set a statement attribute” on page 247– “SQLSetStmtOption - Set statement option” on page 253

v Working with handles

– “SQLAllocConnect - Allocate connection handle” on page 27– “SQLAllocEnv - Allocate environment handle” on page 30– “SQLAllocHandle - Allocate handle” on page 33– “SQLAllocStmt - Allocate a statement handle” on page 34– “SQLCopyDesc - Copy description statement” on page 80– “SQLFreeConnect - Free connection handle” on page 121– “SQLFreeEnv - Free environment handle” on page 122– “SQLFreeHandle - Free a handle” on page 123– “SQLFreeStmt - Free (or reset) a statement handle” on page 124– “SQLReleaseEnv - Release all environment resources” on page 217

SQL CLI


SQLAllocConnect - Allocate connection handleSQLAllocConnect() allocates a connection handle and associated resources within the environment that isidentified by the input environment handle. Call SQLGetInfo() with fInfoType set toSQL_ACTIVE_CONNECTIONS to query the number of connections that can be allocated at any one time.

SQLAllocEnv() must be called before calling this function.

SyntaxSQLRETURN SQLAllocConnect (SQLHENV henv,

SQLHDBC *phdbc);

Function arguments

Table 5. SQLAllocConnect arguments

Data type Argument Use Description

SQLHENV henv Input Environment handle

SQLHDBC * phdbc Output Pointer to connection handle

Usage

The output connection handle is used by Db2 for i CLI to reference all information related to theconnection, including general status information, transaction state, and error information.

If the pointer to the connection handle (phdbc) points to a valid connection handle allocated bySQLAllocConnect(), the original value is overwritten as a result of this call. This is an applicationprogramming error and is not detected by Db2 for i CLI

Return codesv SQL_SUCCESSv SQL_ERRORv SQL_INVALID_HANDLE

If SQL_ERROR is returned, the phdbc argument is set to SQL_NULL_HDBC. The application should callSQLError() with the environment handle (henv), with hdbc set to SQL_NULL_HDBC, and with hstmt setto SQL_NULL_HSTMT.

Diagnostics

Table 6. SQLAllocConnect SQLSTATEs

CLI SQLSTATE Description Explanation

HY001 Memory allocation failure The driver is unable to allocate memory required tosupport the processing or completion of the function.

HY009 Argument value that is notvalid

phdbc is a null pointer.

Example

The following example shows how to obtain diagnostic information for the connection and theenvironment. For more examples of using SQLError(), refer to “Example: Interactive SQL and theequivalent Db2 for i CLI function calls” on page 314 for a complete listing of typical.c.

SQLAllocConnect


Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./********************************************************************* initialize** - allocate environment handle** - allocate connection handle** - prompt for server, user id, & password** - connect to server*******************************************************************/

int initialize(SQLHENV *henv,SQLHDBC *hdbc)

{SQLCHAR server[SQL_MAX_DSN_LENGTH],

uid[30],pwd[30];

SQLRETURN rc;

SQLAllocEnv (henv); /* allocate an environment handle */if (rc != SQL_SUCCESS )

check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);

SQLAllocConnect (*henv, hdbc); /* allocate a connection handle */if (rc != SQL_SUCCESS )


printf("Enter Server Name:\n");gets(server);printf("Enter User Name:\n");gets(uid);printf("Enter Password Name:\n");gets(pwd);

if (uid[0] == ’\0’){ rc = SQLConnect (*hdbc, server, SQL_NTS, NULL, SQL_NTS, NULL, SQL_NTS);

if (rc != SQL_SUCCESS )check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);

}else{ rc = SQLConnect (*hdbc, server, SQL_NTS, uid, SQL_NTS, pwd, SQL_NTS);


}}/* end initialize */

/*******************************************************************/int check_error (SQLHENV henv,

SQLHDBC hdbc,SQLHSTMT hstmt,SQLRETURN frc)

{SQLRETURN rc;

print_error(henv, hdbc, hstmt);

switch (frc){case SQL_SUCCESS : break;case SQL_ERROR :case SQL_INVALID_HANDLE:

printf("\n ** FATAL ERROR, Attempting to rollback transaction **\n");rc = SQLTransact(henv, hdbc, SQL_ROLLBACK);if (rc != SQL_SUCCESS)

printf("Rollback Failed, Exiting application\n");else

printf("Rollback Successful, Exiting application\n");

SQLAllocConnect


terminate(henv, hdbc);exit(frc);break;

case SQL_SUCCESS_WITH_INFO :printf("\n ** Warning Message, application continuing\n");break;

case SQL_NO_DATA_FOUND :printf("\n ** No Data Found ** \n");break;

default :printf("\n ** Invalid Return Code ** \n");printf(" ** Attempting to rollback transaction **\n");SQLTransact(henv, hdbc, SQL_ROLLBACK);terminate(henv, hdbc);exit(frc);break;

}return(SQL_SUCCESS);

}

Referencesv “SQLAllocEnv - Allocate environment handle” on page 30v “SQLConnect - Connect to a data source” on page 77v “SQLDisconnect - Disconnect from a data source” on page 91v “SQLFreeConnect - Free connection handle” on page 121v “SQLGetConnectAttr - Get the value of a connection attribute” on page 132v “SQLSetConnectOption - Set connection option” on page 233

SQLAllocConnect


SQLAllocEnv - Allocate environment handleSQLAllocEnv() allocates an environment handle and associated resources.

An application must call this function before SQLAllocConnect() or any other Db2 for i CLI functions.The henv value is passed in all later function calls that require an environment handle as input.

SyntaxSQLRETURN SQLAllocEnv (SQLHENV *phenv);

Function arguments

Table 7. SQLAllocEnv arguments


SQLHENV * phenv Output Pointer to environment handle

Usage

There can be only one active environment at any one time per application. Any later call toSQLAllocEnv() returns the existing environment handle.

By default, the first successful call to SQLFreeEnv() releases the resources associated with the handle. Thisoccurs no matter how many times SQLAllocEnv() is successfully called. If the environment attributeSQL_ATTR_ENVHNDL_COUNTER is set to SQL_TRUE, SQLFreeEnv() must be called once for eachsuccessful SQLAllocEnv() call before the resources associated with the handle are released.

To ensure that all Db2 for i CLI resources are kept active, the program that calls SQLAllocEnv() shouldnot stop or leave the stack. Otherwise, the application loses open cursors, statement handles, and otherresources it has allocated.

Return codesv SQL_SUCCESSv SQL_ERROR

If SQL_ERROR is returned and phenv is equal to SQL_NULL_HENV, then SQLError() cannot be calledbecause there is no handle with which to associate additional diagnostic information.

If the return code is SQL_ERROR and the pointer to the environment handle is not equal toSQL_NULL_HENV, then the handle is a restricted handle. This means the handle can only be used in a callto SQLError() to obtain more error information, or to SQLFreeEnv().

Diagnostics

Table 8. SQLAllocEnv SQLSTATEs

SQLSTATE Description Explanation

58004 System error Unrecoverable system error

Example

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./********************************************************* file = basiccon.c** - demonstrate basic connection to two datasources.

SQLAllocEnv


** - error handling ignored for simplicity**** Functions used:**** SQLAllocConnect SQLDisconnect** SQLAllocEnv SQLFreeConnect** SQLConnect SQLFreeEnv************************************************************/

#include <stdio.h>#include <stdlib.h>#include "sqlcli.h"


SQLHDBC * hdbc);

#define MAX_DSN_LENGTH 18#define MAX_UID_LENGTH 10#define MAX_PWD_LENGTH 10#define MAX_CONNECTIONS 5

intmain(){

SQLHENV henv;SQLHDBC hdbc[MAX_CONNECTIONS];

/* allocate an environment handle */SQLAllocEnv(&henv);

/* Connect to first data source */connect(henv, &hdbc[0];);

/* Connect to second data source */connect(henv, &hdbc[1];);

/********* Start Processing Step *************************//* allocate statement handle, execute statement, and so on *//********* End Processing Step ***************************/

printf("\nDisconnecting .....\n");SQLFreeConnect(hdbc[0]); /* free first connection handle */SQLFreeConnect(hdbc[1]); /* free second connection handle */SQLFreeEnv(henv); /* free environment handle */

return (SQL_SUCCESS);}

/********************************************************************** connect - Prompt for connect options and connect **********************************************************************/


SQLHDBC * hdbc){

SQLRETURN rc;SQLCHAR server[MAX_DSN_LENGTH + 1], uid[MAX_UID_LENGTH + 1],

pwd[MAX_PWD_LENGTH+ 1];

SQLCHAR buffer[255];SQLSMALLINT outlen;

printf("Enter Server Name:\n");

SQLAllocEnv


gets((char *) server);printf("Enter User Name:\n");gets((char *) uid);printf("Enter Password Name:\n");gets((char *) pwd);

SQLAllocConnect(henv, hdbc);/* allocate a connection handle */

rc = SQLConnect(*hdbc, server, SQL_NTS, uid, SQL_NTS, pwd, SQL_NTS);if (rc != SQL_SUCCESS) {

printf("Error while connecting to database\n");return (SQL_ERROR);


}}

Referencesv “SQLAllocConnect - Allocate connection handle” on page 27v “SQLFreeEnv - Free environment handle” on page 122v “SQLAllocStmt - Allocate a statement handle” on page 34

SQLAllocEnv


SQLAllocHandle - Allocate handleSQLAllocHandle() allocates any type of handle.

SyntaxSQLRETURN SQLAllocHandle (SQLSMALLINT htype,

SQLINTEGER ihandle,SQLINTEGER *handle);

Function arguments

Table 9. SQLAllocHandle arguments


SQLSMALLINT htype Input Type of handle to allocate. Must be eitherSQL_HANDLE_ENV, SQL_HANDLE_DBC,SQL_HANDLE_DESC, orSQL_HANDLE_STMT.

SQLINTEGER ihandle Input The handle that describes the context inwhich the new handle is allocated; however,if htype is SQL_HANDLE_ENV, this isSQL_NULL_HANDLE.

SQLINTEGER * handle Output Pointer to the handle.

Usage

This function is an alternative to the functions SQLAllocEnv(), SQLAllocConnect(), and SQLAllocStmt().In addition, it can be used to allocate a descriptor handle.

If htype is SQL_HANDLE_ENV, ihandle must be SQL_NULL_HANDLE. If htype is SQL_HANDLE_DBC,ihandle must be a valid environment handle. If htype is either SQL_HANDLE_DESC orSQL_HANDLE_STMT, ihandle must be a valid connection handle.


Diagnostics

SQL_ERROR is returned if the argument handle is a null pointer.

Table 10. SQLAllocHandle SQLSTATEs


58004 System error Unrecoverable system error.

HY014 Too many handles The maximum number of handles has been allocated.

Referencesv “SQLAllocConnect - Allocate connection handle” on page 27v “SQLAllocEnv - Allocate environment handle” on page 30v “SQLAllocStmt - Allocate a statement handle” on page 34

SQLAllocHandle


SQLAllocStmt - Allocate a statement handleSQLAllocStmt() allocates a new statement handle and associates it with the connection specified by theconnection handle. There is no defined limit to the number of statement handles that can be allocated atany one time.

SQLConnect() must be called before calling this function.

This function must be called before SQLBindParam(), SQLPrepare(), SQLExecute(), SQLExecDirect(), orany other function that has a statement handle as one of its input arguments.

SyntaxSQLRETURN SQLAllocStmt (SQLHDBC hdbc,

SQLHSTMT *phstmt);

Function arguments

Table 11. SQLAllocStmt arguments


SQLHDBC hdbc Input Connection handle

SQLHSTMT * phstmt Output Pointer to statement handle

Usage

Db2 for i CLI uses each statement handle to relate all the descriptors, result values, cursor information,and status information to the SQL statement processed. Although each SQL statement must have astatement handle, you can reuse the handles for different statements.

A call to this function requires that hdbc references an active database connection.

To process a positioned UPDATE or DELETE statement, the application must use different statementhandles for the SELECT statement and the UPDATE or DELETE statement.

If the input pointer to the statement handle (phstmt) points to a valid statement handle allocated by aprevious call to SQLAllocStmt(), then the original value is overwritten as a result of this call. This is anapplication programming error and is not detected by Db2 for i CLI.


If SQL_ERROR is returned, the phstmt argument is set to SQL_NULL_HSTMT. The application should callSQLError() with the same hdbc argument and with the hstmt argument set to SQL_NULL_HSTMT.

Diagnostics

Table 12. SQLAllocStmt SQLSTATEs


08003 Connection not open The connection specified by the hdbc argument is notopen. The connection must be established successfully(and the connection must be open) for the driver toallocate an hstmt.

SQLAllocStmt


Table 12. SQLAllocStmt SQLSTATEs (continued)


40003 * Statement completionunknown

The communication link between the CLI and the datasource fails before the function completes processing.




phstmt is a null pointer.

HY013 * Memory managementproblem

The driver is unable to access memory required tosupport the processing or completion of the function.

Example

Refer to the example in “SQLFetch - Fetch next row” on page 108.

Referencesv “SQLConnect - Connect to a data source” on page 77v “SQLFreeStmt - Free (or reset) a statement handle” on page 124v “SQLGetStmtOption - Return current setting of a statement option” on page 174v “SQLSetStmtOption - Set statement option” on page 253

SQLAllocStmt


SQLBindCol - Bind a column to an application variableSQLBindCol() is used to associate (bind) columns in a result set to application variables (storage buffers)for all data types. Data is transferred from the Database Management System (DBMS) to the applicationwhen SQLFetch() is called.

This function is also used to specify any data conversion that is required. It is called once for eachcolumn in the result set that the application needs to retrieve.

SQLPrepare() or SQLExecDirect() is typically called before this function. It might also be necessary to callSQLDescribeCol() or SQLColAttribute() to get the attributes of the corresponding result set column.

SQLBindCol() must be called before SQLFetch() to transfer data to the storage buffers that are specified bythis call.

SyntaxSQLRETURN SQLBindCol (SQLHSTMT hstmt,

SQLSMALLINT icol,SQLSMALLINT fCType,SQLPOINTER rgbValue,SQLINTEGER cbValueMax,SQLINTEGER *pcbValue);

Function arguments

Table 13. SQLBindCol arguments


SQLHSTMT hstmt Input Statement handle.

SQLSMALLINT icol Input Number identifying the column. Columnsare numbered sequentially, from left to right,starting at 1.

SQLBindCol


Table 13. SQLBindCol arguments (continued)


SQLSMALLINT fCType Input Application data type for column numbericol in the result set. The following types aresupported:

v SQL_C_BIGINT

v SQL_C_BINARY

v SQL_C_BLOB

v SQL_C_BLOB_LOCATOR

v SQL_C_CHAR

v SQL_C_CLOB

v SQL_C_CLOB_LOCATOR

v SQL_C_DATE

v SQL_TYPE_DATE

v SQL_C_DATETIME

v SQL_C_DBCHAR

v SQL_C_DBCLOB

v SQL_C_DBCLOB_LOCATOR

v SQL_C_DECFLOAT128

v SQL_C_DECFLOAT64

v SQL_C_DECFLOAT32

v SQL_C_DOUBLE

v SQL_C_FLOAT

v SQL_C_LONG

v SQL_C_SLONG

v SQL_C_REAL

v SQL_C_SHORT

v SQL_C_TIME

v SQL_C_TIMESTAMP

v SQL_C_STINYINT

v SQL_C_UTINYINT

v SQL_TYPE_TIME

v SQL_TYPE_TIMESTAMP

v SQL_C_WCHAR

Specifying SQL_DEFAULT causes data to betransferred to its default data type; refer toTable 3 on page 18 for more information.

The SQL data type constants , such asSQL_DECIMAL, may also be used for theapplication data type in many cases.

SQLPOINTER rgbValue Output (deferred) Pointer to buffer where Db2 for i CLI is tostore the column data when the fetch occurs.

If rgbValue is null, the column is unbound.

SQLBindCol


Table 13. SQLBindCol arguments (continued)


SQLINTEGER cbValueMax Input Size of rgbValue buffer in bytes available tostore the column data.

If fCType is either SQL_CHAR orSQL_DEFAULT, then cbValueMax must be >0 otherwise an error is returned.

If fCType is either SQL_DECIMAL orSQL_NUMERIC, cbValueMax must actuallybe a precision and scale. The method tospecify both values is to use (precision * 256)+ scale. This is also the value returned as theLENGTH of these data types when usingSQLColAttribute().

If fCType is either SQL_C_TIMESTAMP orSQL_TYPE_TIMESTAMP, the precision willbe based on the value of cbValueMax. WhencbValueMax is between 20 and 32, theprecision will be cbValueMax - 20. WhencbValueMax is less than 20, the precision willbe 0. When cbValueMax is greater than 32,the precision will be 12.

If fcType specifies any form of double-bytecharacter data, then cbValueMax must be thenumber of double-byte characters, not thenumber of bytes.

SQLINTEGER * pcbValue Output (deferred) Pointer to value which indicates the numberof bytes Db2 for i CLI has available to returnin the rgbValue buffer.

SQLFetch() returns SQL_NULL_DATA in thisargument if the data value of the column isnull. SQL_NTS is returned in this argumentif the data value of the column is returned asa null-terminated string.

Note:

For this function, both rgbValue and pcbValue are deferred outputs, meaning that the storage locationsthese pointers point to are not updated until SQLFetch() is called. The locations referred to by thesepointers must remain valid until SQLFetch() is called.

Usage

The application calls SQLBindCol() once for each column in the result set that it wants to retrieve. WhenSQLFetch() is called, the data in each of these bound columns is placed in the assigned location (given bythe pointers rgbValue and pcbValue).

The application can query the attributes (such as data type and length) of the column by first callingSQLDescribeCol() or SQLColAttribute(). This information can then be used to specify the correct datatype of the storage locations, or to indicate data conversion to other data types. Refer to “Data types anddata conversion in Db2 for i CLI functions” on page 17 for more information.

SQLBindCol


||||||||

For subsequent Fetch requests, the application can change the binding of these columns or bind unboundcolumns by calling FSQLBindCol(). The new binding does not apply to data fetched, it is used when thenext SQLFetch() is called. To unbind a single column, call SQLBindCol() with rgbValue set to NULL. Tounbind all the columns, the application should call SQLFreeStmt() with the fOption input set toSQL_UNBIND.

Columns are identified by a number, assigned sequentially from left to right as they appear in the resultset, starting at 1. The number of columns in the result set can be determined by callingSQLNumResultCols() or SQLColAttribute() with the FieldIdentifier argument set to SQL_DESC_COUNT.

All character data is treated as the default job coded character set identifier (CCSID) if theSQL_ATTR_UTF8 environment attribute is not set to SQL_TRUE.

An application can choose to bind anywhere from zero columns to all columns. The data in the unboundcolumns (and only the unbound columns) can be retrieved using SQLGetData() after SQLFetch() has beencalled. SQLBindCol() is more efficient than SQLGetData(), and should be used whenever possible.

The application must ensure enough storage is allocated for the data to be retrieved. If the buffer is tocontain variable length data, the application must allocate as much storage as the maximum length of thebound column requires; otherwise, the data might be truncated.

The default is null termination for output character strings. To change this you must set theSQLSetEnvAttr() attribute SQL_ATTR_OUTPUT_NTS to SQL_FALSE. The output values for pcbValue aftera call to SQLFetch() behave in the following way for character data types:v If the SQL_ATTR_OUTPUT_NTS attribute is set to SQL_TRUE (the default), then SQL_NTS is returned

in the pcbValue.v If the SQL_ATTR_OUTPUT_NTS attribute is set to SQL_FALSE, then the value of cbValueMax, which is

the maximum bytes available, is returned in pcbValue.v If truncation occurs, then the value of cbValueMax, which is the actual bytes available, is returned in

pcbValue.

If truncation occurs and the SQLSetEnvAttr() attribute SQL_ATTR_TRUNCATION_RTNC is set toSQL_FALSE (which is the default), then SQL_SUCCESS is returned in the SQLFetch() return code. Iftruncation occurs and the attribute is SQL_TRUE, then SQL_SUCCESS_WITH_INFO is returned.SQL_SUCCESS is returned in both cases if no truncation occurs.

Truncation occurs when argument cbValueMax does not allocate space for the amount of fetched data. Ifthe environment is set to run with null terminated strings, make sure to allocate space for the additionalbyte in cbValueMax. For additional truncation information, refer to “SQLFetch - Fetch next row” on page108.

Db2 for i CLI differs from DB2 CLI for Linux, UNIX, and Windows in the way it returns lengthinformation in the pcbValue argument. After a fetch for an SQL_VARCHAR column, Db2 for i CLI returnsthe bytes that are fetched in the first 2 bytes of the VARCHAR structure that is bound. Db2 for i CLI doesnot return the length in pcbValue as it does for SQL_CHAR. This is different from DB2 CLI for Linux,UNIX, and Windows, which have no representation of C VARCHAR and include the length informationin the pcbValue buffer when the application binds to the SQL_CHAR column.

For decimal floating point data types, a precision of 32, 64, or 128 can be specified by using the defaultsymbolic C data type constants. For example, to specify a decimal floating point data type with aprecision of 128 bytes, fCType can be set to SQL_C_DECIMAL128.

Return codesv SQL_SUCCESSv SQL_ERROR

SQLBindCol


v SQL_INVALID_HANDLE

Diagnostics

Table 14. SQLBindCol SQLSTATEs






HY002 Column number that is notvalid

The value specified for the argument icol is 0.

The value specified for the argument icol exceeded themaximum number of columns supported by the datasource.

HY003 Program type out of range fCType is not a valid data type.


rgbValue is a null pointer.

The value specified for the argument cbValueMax is lessthan 1, and the argument fCType is either SQL_CHAR orSQL_DEFAULT.



HY014 Too many handles The maximum number of handles has been allocated,and use of this function requires an additional descriptorhandle.

HY021 Internal descriptor that isnot valid

The internal descriptor cannot be addressed or allocated,or it contains a value that is not valid.

HYC00 Driver not capable The driver recognizes, but does not support the datatype specified in the argument fCType (see also HY003).

Example


Referencesv “SQLExecDirect - Execute a statement directly” on page 102v “SQLExecute - Execute a statement” on page 104v “SQLFetch - Fetch next row” on page 108v “SQLPrepare - Prepare a statement” on page 200

SQLBindCol


SQLBindFileToCol - Bind LOB file reference to LOB columnSQLBindFileToCol() is used to associate (bind) a LOB column in a result set to a file reference or an arrayof file references. In this way, data in the LOB column can be transferred directly into a file when eachrow is fetched for the statement handle.

The LOB file reference arguments (file name, file name length, file reference options) refer to a file withinthe application's environment (on the client). Before fetching each row, the application must make surethat these variables contain the name of a file, the length of the file name, and a file option(new/overwrite/append). These values can be changed between each fetch.

SyntaxSQLRETURN SQLBindFileToCol (SQLHSTMT StatementHandle,

SQLSMALLINT ColumnNumber,SQLCHAR *FileName,SQLSMALLINT *FileNameLength,SQLINTEGER *FileOptions,SQLSMALLINT MaxFileNameLength,SQLINTEGER *StringLength,SQLINTEGER *IndicatorValue);

Function arguments

Table 15. SQLBindFileToCol arguments


SQLHSTMT StatementHandle Input Statement handle.

SQLSMALLINT ColumnNumber Input Number identifying the column. Columns arenumbered sequentially, from left to right, starting at1.

SQLCHAR * FileName Input(deferred)

Pointer to the location that contains the file name oran array of file names at the time of the next fetchusing the StatementHandle. This is either the completepath name of the file(s) or a relative file name(s). Ifrelative file name(s) are provided, they are appendedto the current path of the running application. Thispointer cannot be NULL.

SQLSMALLINT * FileNameLength Input(deferred)

Pointer to the location that contains the length of thefile name (or an array of lengths) at the time the nextfetch using the StatementHandle. If this pointer isNULL, then a length of SQL_NTS is assumed.

The maximum value of the file name length is 255.

SQLBindFileToCol


Table 15. SQLBindFileToCol arguments (continued)


SQLINTEGER * FileOptions Input(deferred)

Pointer to the location that contains the file option tobe used when writing the file at the time of the nextfetch using the StatementHandle. The followingFileOptions are supported:

SQL_FILE_CREATECreate a new file. If a file by this namealready exists, SQL_ERROR is returned.

SQL_FILE_OVERWRITEIf the file already exists, overwrite it.Otherwise, create a new file.

SQL_FILE_APPENDIf the file already exists, append the data toit. Otherwise, create a new file.

Only one option can be chosen per file, there is nodefault.

SQLSMALLINT MaxFileNameLength Input This specifies the length of the FileName buffer.

SQLINTEGER * StringLength Output(deferred)

Pointer to the location that contains the length inbytes of the LOB data that is returned. If this pointeris NULL, nothing is returned.

SQLINTEGER * IndicatorValue Output(deferred)

Pointer to the location that contains an indicatorvalue.

Usage

The application calls SQLBindFileToCol() once for each column that should be transferred directly to afile when a row is fetched. LOB data is written directly to the file without any data conversion, andwithout appending null-terminators.

FileName, FileNameLength, and FileOptions must be set before each fetch. When SQLFetch() orSQLFetchScroll() is called, the data for any column which has been bound to a LOB file reference iswritten to the file or files pointed to by that file reference. Errors associated with the deferred inputargument values of SQLBindFileToCol() are reported at fetch time. The LOB file reference, and thedeferred StringLength and IndicatorValue output arguments are updated between fetch operations.

Return codesv SQL_SUCCESSv SQL_SUCCESS_WITH_INFOv SQL_ERRORv SQL_INVALID_HANDLE

Error conditions

Table 16. SQLBindFileToCol SQLSTATEs


58004 Unexpected system failure Unrecoverable system error.

SQLBindFileToCol


Table 16. SQLBindFileToCol SQLSTATEs (continued)


HY002 Column number that is notvalid

The value specified for the argument icol is less than 1.

The value specified for the argument icol exceeded themaximum number of columns supported by the datasource.


FileName, StringLength, or FileOptions is a null pointer.

HY010 Function sequence error The function is called while in a data-at-processing(SQLParamData(), SQLPutData()) operation.

The function is called while within a BEGINCOMPOUND and END COMPOUND SQL operation.



HY090 String or buffer length thatis not valid

The value specified for the argument MaxFileNameLengthis less than 0.

HYC00 Driver not capable The application is currently connected to a data sourcethat does not support large objects.

Restrictions

This function is not available when connected to DB2 servers that do not support Large Object datatypes.

Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLFetch - Fetch next row” on page 108v “SQLBindFileToParam - Bind LOB file reference to LOB parameter” on page 44

SQLBindFileToCol


SQLBindFileToParam - Bind LOB file reference to LOB parameterSQLBindFileToParam() is used to associate (bind) a parameter marker in an SQL statement to a filereference or an array of file references. In this way, data from the file can be transferred directly into aLOB column when that statement is subsequently processed.

The LOB file reference arguments (file name, file name length, file reference options) refer to a file withinthe application's environment (on the client). Before calling SQLExecute() or SQLExecDirect(), theapplication must make sure that this information is available in the deferred input buffers. These valuescan be changed between SQLExecute() calls.

SyntaxSQLRETURN SQLBindFileToParam (SQLHSTMT StatementHandle,

SQLSMALLINT ParameterNumber,SQLSMALLINT DataType,SQLCHAR *FileName,SQLSMALLINT *FileNameLength,SQLINTEGER *FileOptions,SQLSMALLINT MaxFileNameLength,SQLINTEGER *IndicatorValue);

Function arguments

Table 17. SQLBindFileToParam arguments



SQLSMALLINT ParameterNumber Input Parameter marker number. Parameters are numberedsequentially, from left to right, starting at 1.

SQLSMALLINT DataType Input SQL data type of the column. The data type must beone of:

v SQL_BLOB

v SQL_CLOB

v SQL_DBCLOB

SQLCHAR * FileName Input(deferred)

Pointer to the location that contains the file name oran array of file names when the statement(StatementHandle) is processed. This is either thecomplete path name of the file or a relative filename. If a relative file name is provided, it isappended to the current path of the client process.

This argument cannot be NULL.

SQLSMALLINT * FileNameLength Input(deferred)

Pointer to the location that contains the length of thefile name (or an array of lengths) at the time the nextSQLExecute() or SQLExecDirect() function is runusing the StatementHandle.

If this pointer is NULL, then a length of SQL_NTS isassumed.

The maximum value of the file name length is 255.

SQLBindFileToParam


Table 17. SQLBindFileToParam arguments (continued)


SQLINTEGER * FileOptions Input(deferred)

Pointer to the location that contains the file option(or an array of file options) to be used when readingthe file. The location is accessed when the statement(StatementHandle) is processed. Only one option issupported (and it must be specified):

SQL_FILE_READ A regular file that can be opened, read andclosed. (The length is computed when thefile is opened)

This pointer cannot be NULL.

SQLSMALLINT MaxFileNameLength Input This specifies the length of the FileName buffer. If theapplication calls SQLParamOptions() to specifymultiple values for each parameter, this is the lengthof each element in the FileName array.

SQLINTEGER * IndicatorValue Input(deferred),output(deferred)

Pointer to the location that contains an indicatorvalue (or array of values), which is set toSQL_NULL_DATA if the data value of the parameteris to be null. It must be set to 0 (or the pointer canbe set to null) when the data value is not null.

Usage

The application calls SQLBindFileToParam() once for each parameter marker whose value should beobtained directly from a file when a statement is processed. Before the statement is processed, FileName,FileNameLength, and FileOptions values must be set. When the statement is processed, the data for anyparameter that has been bound with SQLBindFileToParam() is read from the referenced file and passed tothe data source.

A LOB parameter marker can be associated with (bound to) an input file using SQLBindFileToParam(), orwith a stored buffer using SQLBindParameter(). The most recent bind parameter function call determinesthe type of binding that is in effect.


Error conditions

Table 18. SQLBindFileToParam SQLSTATEs



HY004 SQL data type out of range The value specified for DataType is not a valid SQL type for thisfunction call.

HY009 Argument value that is not valid FileName, FileOptions, or FileNameLength is a null pointer.

SQLBindFileToParam


Table 18. SQLBindFileToParam SQLSTATEs (continued)


HY010 Function sequence error The function is called while in a data-at-processing(SQLParamData()or SQLPutData()) operation.

The function is called while within a BEGIN COMPOUND andEND COMPOUND SQL operation.

HY021 Internal descriptor that is notvalid

The internal descriptor cannot be addressed or allocated, or itcontains a value that is not valid.

HY090 String or buffer length that is notvalid

The value specified for the input argument MaxFileNameLength isless than 0.

HY093 Parameter number that is notvalid

The value specified for ParameterNumber is either less than 1 orgreater than the maximum number of parameters supported.

HYC00 Driver not capable The data source does not support large object data types.

Restrictions

This function is not available when the application is connected to DB2 servers that do not support largeobject data types.

Referencesv “SQLBindParam - Bind a buffer to a parameter marker” on page 47v “SQLExecute - Execute a statement” on page 104v “SQLParamOptions - Specify an input array for a parameter” on page 198

SQLBindFileToParam


SQLBindParam - Bind a buffer to a parameter markerSQLBindParam() has been deprecated and replaced by SQLBindParameter(). Although this version of Db2for i CLI continues to support SQLBindParam(), it is recommended that you begin usingSQLBindParameter() in your Db2 for i CLI programs so that they conform to the latest standards.

SQLBindParam() binds an application variable to a parameter marker in an SQL statement. This functioncan also be used to bind an application variable to a parameter of a stored procedure CALL statementwhere the parameter can be input or output.

SyntaxSQLRETURN SQLBindParam (SQLHSTMT hstmt,

SQLSMALLINT ipar,SQLSMALLINT fCType,SQLSMALLINT fSqlType,SQLINTEGER cbParamDef,SQLSMALLINT ibScale,SQLPOINTER rgbValue,SQLINTEGER *pcbValue);

Function arguments

Table 19. SQLBindParam arguments



SQLSMALLINT ipar Input Parameter marker number, orderedsequentially left to right, starting at 1.

SQLBindParam


Table 19. SQLBindParam arguments (continued)


SQLSMALLINT fCType Input Application data type of the parameter. Thefollowing types are supported:

v SQL_BIGINT

v SQL_BINARY

v SQL_BLOB

v SQL_BLOB_LOCATOR

v SQL_CHAR

v SQL_CLOB

v SQL_CLOB_LOCATOR

v SQL_DATETIME

v SQL_DBCLOB

v SQL_DBCLOB_LOCATOR

v SQL_DECFLOAT

v SQL_DECIMAL

v SQL_DOUBLE

v SQL_FLOAT

v SQL_GRAPHIC

v SQL_INTEGER

v SQL_NUMERIC

v SQL_REAL

v SQL_SMALLINT

v SQL_TYPE_DATE

v SQL_TYPE_TIME


v SQL_VARBINARY

v SQL_VARCHAR

v SQL_VARGRAPHIC

v SQL_WCHAR

v SQL_WVARCHAR

Specifying SQL_DEFAULT causes data to betransferred from its default application datatype to the type indicated in fSqlType.

SQLBindParam




SQLSMALLINT fSqlType Input SQL data type of the parameter. Thesupported types are:

v SQL_BIGINT

v SQL_BINARY

v SQL_BLOB

v SQL_BLOB_LOCATOR

v SQL_CHAR

v SQL_CLOB

v SQL_CLOB_LOCATOR

v SQL_DATETIME

v SQL_DBCLOB


v SQL_DECFLOAT

v SQL_DECIMAL

v SQL_DOUBLE

v SQL_FLOAT

v SQL_GRAPHIC

v SQL_INTEGER

v SQL_NUMERIC

v SQL_REAL

v SQL_SMALLINT

v SQL_TYPE_DATE

v SQL_TYPE_TIME


v SQL_VARBINARY

v SQL_VARCHAR

v SQL_VARGRAPHIC

v SQL_WCHAR

v SQL_WVARCHAR

SQLINTEGER cbParamDef Input Precision of the corresponding parametermarker.

v If fCType denotes a single-byte characterstring (for example, SQL_CHAR), this isthe maximum length in bytes sent for thisparameter. This length includes thenull-termination character.

v If fCType denotes a double-byte characterstring (for example, SQL_GRAPHIC), thisis the maximum length in double-bytecharacters for this parameter.

v If fCType denotes SQL_DECIMAL orSQL_NUMERIC, this is the maximumdecimal precision.

v If fCType denotes SQL_TYPE_TIMESTAMP,this is the maximum length in bytes sentfor this parameter.

v Otherwise, this argument is unused.

SQLBindParam


|||



SQLSMALLINT ibScale Input Scale of the corresponding parameter iffSqlType is SQL_DECIMAL orSQL_NUMERIC. If fSqlType isSQL_TIMESTAMP, this is the number ofdigits to the right of the decimal point in thecharacter representation of a timestamp (forexample, the scale of yyyy-mm-ddhh:mm:ss.fff is 3).

Other than for the fSqlType values mentionedhere, ibScale is unused.

SQLPOINTER rgbValueInput (deferred)oroutput (deferred)

At processing time, if pcbValue does notcontain SQL_NULL_DATA orSQL_DATA_AT_EXEC, then rgbValue pointsto a buffer that contains the actual data forthe parameter.

If pcbValue contains SQL_DATA_AT_EXEC,then rgbValue is an application-defined 32-bitvalue that is associated with this parameter.This 32-bit value is returned to theapplication through a later SQLParamData()call.

SQLINTEGER * pcbValue Input (deferred), oroutput (deferred), orboth

A variable whose value is interpreted whenthe statement is processed:

v If a null value is used as the parameter,pcbValue must contain the valueSQL_NULL_DATA.

v If the dynamic argument is supplied atexecute-time by calling ParamData() andPutData(), pcbValue must contain the valueSQL_DATA_AT_EXEC.

v If fcType is SQL_CHAR and the data inrgbValue contains a null-terminated string,pcbValue must either contain the length ofthe data in rgbValue or contain the valueSQL_NTS.

v If fcType is SQL_CHAR and the data inrgbValue is not null-terminated, pcbValuemust contain the length of the data inrgbValue.

v If fcType is a LOB type, pcbValue mustcontain the length of the data in rgbValue.This length value must be specified inbytes, not the number of double bytecharacters.

v Otherwise, pcbValue must be zero.

Usage

When SQLBindParam() is used to bind an application variable to an output parameter for a storedprocedure, Db2 for i CLI provides some performance enhancement if the rgbValue buffer is placedconsecutively in memory after the pcbValue buffer.

SQLBindParam


For decimal floating point data types, a precision of 32, 64, or 128 can be specified by using the defaultsymbolic C data type constants. For example, to specify a decimal floating point data type with aprecision of 128 bytes, fCType can be set to SQL_C_DECIMAL128.


Diagnostics

Table 20. SQLBindParam SQLSTATEs


07006 Restricted data typeattribute violation

Same as SQLSetParam().





HY003 Program type out of range Same as SQLSetParam().

HY004 SQL data type out of range Same as SQLSetParam().


Both rgbValue and pcbValue are null pointers, or ipar isless than one.

HY010 Function sequence error Function is called after SQLExecute() or SQLExecDirect()has returned SQL_NEED_DATA, but data has not beensent for all data-at-execution parameters.






References

“SQLBindParameter - Bind a parameter marker to a buffer” on page 52

SQLBindParam


SQLBindParameter - Bind a parameter marker to a bufferSQLBindParameter() is used to associate (bind) parameter markers in an SQL statement to applicationvariables. Data is transferred from the application to the Database Management System (DBMS) whenSQLExecute() or SQLExecDirect() is called. Data conversion might occur when the data is transferred.

This function must also be used to bind application storage to a parameter of a stored procedure wherethe parameter can be input, output, or both.

SyntaxSQLRETURN SQLBindParameter(SQLHSTMT StatementHandle,

SQLSMALLINT ParameterNumber,SQLSMALLINT InputOutputType,SQLSMALLINT ValueType,SQLSMALLINT ParameterType,SQLINTEGER ColumnSize,SQLSMALLINT DecimalDigits,SQLPOINTER ParameterValuePtr,SQLINTEGER BufferLength,SQLINTEGER *StrLen_or_IndPtr);

Function arguments

Table 21. SQLBindParameter arguments



SQLSMALLINT ParameterNumber Input Parameter marker number, ordered sequentiallyleft to right, starting at 1.

SQLBindParameter


Table 21. SQLBindParameter arguments (continued)


SQLSMALLINT InputOutputType Input The type of parameter. The value of theSQL_DESC_PARAMETER_TYPE field of theimplementation parameter descriptor is also setto this argument. The supported types are:

v SQL_PARAM_INPUT: The parameter markeris associated with an SQL statement that isnot a stored procedure CALL; or, it marks aninput parameter of a stored procedure.

When the statement is processed, the actualdata value for the parameter is sent to thedata source: the ParameterValuePtr buffer mustcontain valid input data values; theStrLen_or_IndPtr buffer must contain thecorresponding length value or SQL_NTS,SQL_NULL_DATA, or (if the value should besent via SQLParamData() and SQLPutData())SQL_DATA_AT_EXEC.

v SQL_PARAM_INPUT_OUTPUT: Theparameter marker is associated with aninput/output parameter of a storedprocedure.

When the statement is processed, actual datavalue for the parameter is sent to the datasource: the ParameterValuePtr buffer mustcontain valid input data values; theStrLen_or_IndPtr buffer must contain thecorresponding length value or SQL_NTS,SQL_NULL_DATA, or (if the value should besent via SQLParamData() and SQLPutData())SQL_DATA_AT_EXEC.

v SQL_PARAM_OUTPUT: The parametermarker is associated with an outputparameter of a stored procedure.

After the statement is processed, data for theoutput parameter is returned to theapplication buffer specified byParameterValuePtr and StrLen_or_IndPtr,unless both are NULL pointers, in which casethe output data is discarded. If an outputparameter does not have a return value thenStrLen_or_IndPtr is set to SQL_NULL_DATA.

SQLBindParameter




SQLSMALLINT ValueType Input C data type of the parameter. The followingtypes are supported:

v SQL_BIGINT

v SQL_BINARY

v SQL_BLOB

v SQL_BLOB_LOCATOR

v SQL_CHAR

v SQL_CLOB

v SQL_CLOB_LOCATOR

v SQL_DATETIME

v SQL_DBCLOB


v SQL_DECFLOAT

v SQL_DECIMAL

v SQL_DOUBLE

v SQL_FLOAT

v SQL_GRAPHIC

v SQL_INTEGER

v SQL_NUMERIC

v SQL_REAL

v SQL_SMALLINT

v SQL_TYPE_DATE

v SQL_TYPE_TIME


v SQL_VARBINARY

v SQL_VARCHAR

v SQL_VARGRAPHIC

v SQL_WCHAR

v SQL_WVARCHAR

Specifying SQL_C_DEFAULT causes data to betransferred from its default C data type to thetype indicated in ParameterType.

SQLBindParameter




SQLSMALLINT ParameterType Input SQL data type of the parameter. The supportedtypes are:

v SQL_BIGINT

v SQL_BINARY

v SQL_BLOB

v SQL_BLOB_LOCATOR

v SQL_CHAR

v SQL_CLOB

v SQL_CLOB_LOCATOR

v SQL_DATETIME

v SQL_DBCLOB


v SQL_DECFLOAT

v SQL_DECIMAL

v SQL_DOUBLE

v SQL_FLOAT

v SQL_GRAPHIC

v SQL_INTEGER

v SQL_NUMERIC

v SQL_REAL

v SQL_SMALLINT

v SQL_TYPE_DATE

v SQL_TYPE_TIME


v SQL_VARBINARY

v SQL_VARCHAR

v SQL_VARGRAPHIC

v SQL_WCHAR

v SQL_WVARCHAR

v SQL_XML

SQLINTEGER ColumnSize Input Precision of the corresponding parametermarker.

v If ValueType denotes a binary or single-bytecharacter string (for example, SQL_CHAR),this is the maximum length in bytes for thisparameter marker.

v If ValueType denotes a double-byte characterstring (for example, SQL_GRAPHIC), this isthe maximum length in double-bytecharacters for this parameter.

v If ValueType denotes SQL_DECIMAL orSQL_NUMERIC, this is the maximumdecimal precision.

v If ValueType denotes SQL_TYPE_TIMESTAMP,this is the maximum length in bytes sent forthis parameter.

v Otherwise, this argument is ignored.

SQLBindParameter


|

|

|

|||



SQLSMALLINT DecimalDigits Input Scale of the corresponding parameter ifParameterType is SQL_DECIMAL orSQL_NUMERIC. If ParameterType isSQL_TYPE_TIMESTAMP, this is the number ofdigits to the right of the decimal point in thecharacter representation of a timestamp (forexample, the scale of yyyy-mm-dd hh:mm:ss.fffis 3).

Other than for the ParameterType valuesmentioned here, DecimalDigits is ignored.

SQLPOINTER ParameterValuePtr Input(deferred),or output(deferred),or both

v On input (InputOutputType set toSQL_PARAM_INPUT, orSQL_PARAM_INPUT_OUTPUT), thefollowing situations are true:

At processing time, if StrLen_or_IndPtr doesnot contain SQL_NULL_DATA orSQL_DATA_AT_EXEC, then ParameterValuePtrpoints to a buffer that contains the actualdata for the parameter.

If StrLen_or_IndPtr containsSQL_DATA_AT_EXEC, then ParameterValuePtris an application-defined 32-bit value that isassociated with this parameter. This 32-bitvalue is returned to the application via asubsequent SQLParamData() call.

If SQLParamOptions() is called to specifymultiple values for the parameter, thenParameterValuePtr is a pointer to an inputbuffer array of BufferLength bytes.

v On output (InputOutputType set toSQL_PARAM_OUTPUT, orSQL_PARAM_INPUT_OUTPUT), thefollowing situations are true:

ParameterValuePtr points to the buffer wherethe output parameter value of the storedprocedure is stored.

If InputOutputType is set toSQL_PARAM_OUTPUT, and bothParameterValuePtr and StrLen_or_IndPtr areNULL pointers, then the output parametervalue or the return value from the storedprocedure call is discarded.

SQLINTEGER BufferLength Input Not used.

SQLBindParameter




SQLINTEGER * StrLen_or_IndPtr Input(deferred),output(deferred)

If this is an input or input/output parameter,this is the pointer to the location that contains(when the statement is processed) the length ofthe parameter marker value stored atParameterValuePtr.

To specify a null value for a parameter marker,this storage location must containSQL_NULL_DATA.

To specify an extended indicator value for aparameter marker, this storage location mustcontain SQL_UNASSIGNED orSQL_DEFAULT_PARAM. TheSQL_ATTR_EXTENDED_INDICATORSconnection attribute must be set to SQL_TRUEfor either of these values to be honored.

If ValueType is SQL_C_CHAR, this storagelocation must contain either the exact length ofthe data stored at ParameterValuePtr, orSQL_NTS if the content at ParameterValuePtr isnull-terminated.

For all values of ParameterValuePtr, if ValueTypeindicates LOB data, this storage location mustcontain the length of the data stored atParameterValuePtr. This length value must bespecified in bytes, not the number ofdouble-byte characters.

If ValueType indicates character data (explicitly,or implicitly using SQL_C_DEFAULT), and thispointer is set to NULL, it is assumed that theapplication always provides a null-terminatedstring in ParameterValuePtr. This also impliesthat this parameter marker never has a nullvalue.

If ValueType specifies any form of double-bytecharacter data, then StrLen_or_IndPtr must bethe number of double-byte characters, not thenumber of bytes.

When SQLExecute() or SQLExecDirect() iscalled, and StrLen_or_IndPtr points to a value ofSQL_DATA_AT_EXEC, the data for theparameter is sent with SQLPutData(). Thisparameter is referred to as a data-at-executionparameter.

Usage

A parameter marker is represented by a "?" character in an SQL statement and is used to indicate aposition in the statement where an application supplied value is to be substituted when the statement isprocessed. This value is obtained from an application variable.

SQLBindParameter


The application must bind a variable to each parameter marker in the SQL statement before executing theSQL statement. For this function, ParameterValuePtr and StrLen_or_IndPtr are deferred arguments; thestorage locations must be valid and contain input data values when the statement is processed. Thismeans either keeping the SQLExecDirect() or SQLExecute() call in the same procedure scope as theSQLBindParameter() calls, or these storage locations must be dynamically allocated or declared staticallyor globally.

Parameter markers are referred to by number (ParameterNumber) and are numbered sequentially from leftto right as the corresponding ? appears in the statement text, starting at 1.

All parameters bound by this function remain in effect until SQLFreeStmt() is called with either theSQL_DROP or SQL_RESET_PARAMS option, or until SQLBindParameter() is called again for the sameparameter ParameterNumber number.

After the SQL statement and the results have been processed, the application might want to reuse thestatement handle to process a different SQL statement. If the parameter marker specifications are different(number of parameters, length or type), then SQLFreeStmt() should be called with SQL_RESET_PARAMSto reset or clear the parameter bindings.

The C buffer data type that is given by ValueType must be compatible with the SQL data type that isindicated by ParameterType, or an error occurs.

Because the data in the variables referenced by ParameterValuePtr and StrLen_or_IndPtr is not verifieduntil the statement is processed, data content or format errors are not detected or reported untilSQLExecute() or SQLExecDirect() is called.

SQLBindParameter() essentially extends the capability of the SQLSetParam() function by providing amethod of specifying whether a parameter is input, input and output, or output. This information isnecessary for the proper handling of parameters for stored procedures.

The InputOutputType argument specifies the type of the parameter. All parameters in the SQL statementsthat do not call procedures are input parameters. Parameters in stored procedure calls can be input,input/output, or output parameters. Even though the DB2 stored procedure argument conventiontypically implies that all procedure arguments are input/output, the application programmer can stillchoose to specify more exactly the input or output nature on the SQLBindParameter() to follow a morerigorous coding style. Also, note that these types should be consistent with the parameter types specifiedwhen the stored procedure is registered with the SQL CREATE PROCEDURE statement.v If an application cannot determine the type of a parameter in a procedure call, set InputOutputType to

SQL_PARAM_INPUT; if the data source returns a value for the parameter, Db2 for i CLI discards it.v If an application has marked a parameter as SQL_PARAM_INPUT_OUTPUT or

SQL_PARAM_OUTPUT and the data source does not return a value, Db2 for i CLI sets theStrLen_or_IndPtr buffer to SQL_NULL_DATA.

v If an application marks a parameter as SQL_PARAM_OUTPUT, data for the parameter is returned tothe application after the CALL statement has been processed. If the ParameterValuePtr andStrLen_or_IndPtr arguments are both null pointers, Db2 for i CLI discards the output value. If the datasource does not return a value for an output parameter, Db2 for i CLI sets the StrLen_or_IndPtr bufferto SQL_NULL_DATA.

v For this function, both ParameterValuePtr and StrLen_or_IndPtr are deferred arguments. In the casewhere InputOutputType is set to SQL_PARAM_INPUT or SQL_PARAM_INPUT_OUTPUT, the storagelocations must be valid and contain input data values when the statement is processed. This meanseither keeping the SQLExecDirect() or SQLExecute() call in the same procedure scope as theSQLBindParameter() calls, or, these storage locations must be dynamically allocated or statically /globally declared.

SQLBindParameter


Similarly, if InputOutputType is set to SQL_PARAM_OUTPUT or SQL_PARAM_INPUT_OUTPUT, theParameterValuePtr and StrLen_or_IndPtr buffer locations must remain valid until the CALL statementhas been processed.

When SQLBindParameter() is used to bind an application variable to an output parameter for a storedprocedure, Db2 for i CLI can provide some performance enhancement if the ParameterValuePtr buffer isplaced consecutively in memory after the StrLen_or_IndPtr buffer. For example:

struct { SQLINTEGER StrLen_or_IndPtr;SQLCHAR ParameterValuePtr[MAX_BUFFER];

} column;

For decimal floating point data types, a precision of 32, 64, or 128 can be specified by using the defaultsymbolic C data type constants. For example, to specify a decimal floating point data type with aprecision of 128 bytes, ValueType can be set to SQL_C_DECIMAL128.


Error conditions

Table 22. SQLBindParameter SQLSTATEs


07006 Conversion not valid The conversion from the data value identified by the ValueTypeargument to the data type identified by the ParameterTypeargument is not a meaningful conversion. (For example,conversion from SQL_C_DATE to SQL_DOUBLE.)

40003 08S01 Communication link failure The communication link between the application and data sourcefails before the function is completed.


HY001 Memory allocation failure Db2 for i CLI is unable to allocate memory required to supportthe processing or completion of the function.

HY003 Program type out of range The value specified by the argument ParameterNumber not a validdata type or SQL_C_DEFAULT.

HY004 SQL data type out of range The value specified for the argument ParameterType is not a validSQL data type.

HY009 Argument value not valid The argument ParameterValuePtr is a null pointer and theargument StrLen_or_IndPtr is a null pointer, and InputOutputTypeis not SQL_PARAM_OUTPUT.

HY010 Function sequence error Function is called after SQLExecute() or SQLExecDirect() hasreturned SQL_NEED_DATA, but data has not been sent for alldata-at-execution parameters.

HY013 Unexpected memory handlingerror

Db2 for i CLI is unable to access memory required to support theprocessing or completion of the function.


HY021 Inconsistent descriptorinformation

The descriptor information checked during a consistency check isnot consistent.

HY090 String or buffer length not valid The value specified for the BufferLength argument is less than 0.

SQLBindParameter


Table 22. SQLBindParameter SQLSTATEs (continued)


HY093 Parameter number not valid The value specified for the ValueType argument is less than 1 orgreater than the maximum number of parameters supported bythe data source.

HY094 Scale value not valid The value specified for ParameterType is either SQL_DECIMAL orSQL_NUMERIC and the value specified for DecimalDigits is lessthan 0 or greater than the value for the argument ParamDef(precision).

The value specified for ParameterType is SQL_C_TIMESTAMP andthe value for ParameterType is either SQL_CHAR orSQL_VARCHAR and the value for DecimalDigits is less than 0 orgreater than 12.

HY104 Precision value not valid The value specified for ParameterType is either SQL_DECIMAL orSQL_NUMERIC and the value specified for ParamDef is less than1.

HY105 Parameter type not valid InputOutputType is not one of SQL_PARAM_INPUT,SQL_PARAM_OUTPUT, or SQL_PARAM_INPUT_OUTPUT.

HYC00 Driver not capable Db2 for i CLI or data source does not support the conversionspecified by the combination of the value specified for theargument ValueType and the value specified for the argumentParameterType.

The value specified for the argument ParameterType is notsupported by either Db2 for i CLI or the data source.

Referencesv “SQLExecDirect - Execute a statement directly” on page 102v “SQLExecute - Execute a statement” on page 104v “SQLParamData - Get next parameter for which a data value is needed” on page 196v “SQLPutData - Pass data value for a parameter” on page 215

SQLBindParameter


SQLCancel - Cancel statementSQLCancel() is used to end the processing of an SQL statement operation that is running synchronously.To cancel the function, the application calls SQLCancel() with the same statement handle that is used bythe target function, but on a different thread. How the function is canceled depends on the operatingsystem.

SyntaxSQLRETURN SQLCancel (SQLHSTMT hstmt);

Function arguments

Table 23. SQLCancel arguments


SQLHSTMT hstmt Input Statement handle

Usage

A successful return code indicates that the implementation has accepted the cancel request; it does notensure that the processing is canceled.

Return codesv SQL_SUCCESSv SQL_INVALID_HANDLEv SQL_ERROR

Diagnostics

Table 24. SQLCancel SQLSTATEs


HY009 * Argument value that is notvalid

hstmt is not a statement handle.

Restrictions

Db2 for i CLI does not support asynchronous statement processing.

SQLCancel


SQLCloseCursor - Close cursor statementSQLCloseCursor() closes the open cursor on a statement handle.

SyntaxSQLRETURN SQLCloseCursor (SQLHSTMT hstmt);

Function arguments

Table 25. SQLCloseCursor arguments



Usage

Calling SQLCloseCursor() closes any cursor associated with the statement handle and discards anypending results. If no open cursor is associated with the statement handle, the function has no effect.

If the statement handle references a stored procedure that has multiple result sets, the SQLCloseCursor()closes only the current result set. Any additional result sets remain open and usable.


Diagnostics

Table 26. SQLCloseCursor SQLSTATEs


08003 * Connection not open The connection for hstmt is not established.

HY009 * Argument value that is notvalid

hstmt is not a statement handle.



SQLCloseCursor


SQLColAttribute - Return a column attributeSQLColAttribute() obtains an attribute for a column of the result set, and is also used to determine thenumber of columns. SQLColAttribute() is a more extensible alternative to the SQLDescribeCol() function.

Either SQLPrepare() or SQLExecDirect() must be called before calling this function.

This function (or SQLDescribeCol()) must be called before SQLBindCol(), if the application does not knowthe various attributes (such as data type and length) of the column.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLColAttributeW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLColAttribute (SQLHSTMT StatementHandle,

SQLSMALLINT ColumnNumber,SQLSMALLINT FieldIdentifier,SQLPOINTER CharacterAttributePtr,SQLSMALLINT BufferLength,SQLSMALLINT *StringLengthPtr,SQLPOINTER NumericAttributePtr);

Function arguments

Table 27. SQLColAttribute arguments



SQLSMALLINT ColumnNumber Input The number of the record in the IRD fromwhich the field value is to be retrieved. Thisargument corresponds to the column numberof result data, ordered sequentially from leftto right, starting at 1. Columns can bedescribed in any order.

Column 0 can be specified in this argument,but all values except SQL_DESC_TYPE andSQL_DESC_OCTET_LENGTH will returnundefined values.

SQLSMALLINT FieldIdentifier Input The field in row ColumnNumber of the IRDthat is to be returned Table 28 on page 64.

SQLPOINTER CharacterAttributePtr Output Pointer to a buffer in which to return thevalue in the FieldIdentifier field of theColumnNumber row of the IRD, if the fieldis a character string. Otherwise, the field isunused.

SQLSMALLINT BufferLength Input Number of SQLCHAR elements (orSQLWCHAR elements for the Unicodevariant of this function) needed to store the*CharacterAttributePtr buffer, if the field is acharacter string. Otherwise, the field isignored.

SQLColAttribute


Table 27. SQLColAttribute arguments (continued)


SQLSMALLINT * StringLengthPtr Output Pointer to a buffer in which to return thetotal number of bytes (excluding the bytecount of the null termination character forcharacter data) available to return in*CharacterAttributePtr.

For character data, if the number of bytesavailable to return is greater than or equal toBufferLength, the descriptor information in*CharacterAttributePtr is truncated toBufferLength minus the length of a nulltermination character and is null-terminatedby DB2 CLI.

For all other types of data, the value ofBufferLength is ignored and DB2 CLIassumes the size of *CharacterAttributePtr is32 bits.

SQLPOINTER NumericAttributePtr Output Pointer to a buffer in which to return thevalue in the FieldIdentifier field of theColumnNumber row of the IRD, if the fieldis a numeric descriptor type, such asSQL_DESC_COLUMN_LENGTH. Otherwise,the field is unused.

Table 28. Field Identifier descriptor types

Descriptor Type Description

SQL_DESC_AUTO_INCREMENT INTEGER This is SQL_TRUE if the column can be incrementedautomatically upon insertion of a new row to thetable. SQL_FALSE if the column cannot beincremented automatically.

SQL_DESC_BASE_COLUMN CHAR(128) The name of the actual column in the underlyingtable over which this column is built.

For this attribute to be retrieved, the attributeSQL_ATTR_EXTENDED_COL_INFO must havebeen set to SQL_TRUE for either the statementhandle or the connection handle.

SQL_DESC_BASE_SCHEMA CHAR(128) The schema name of the underlying table overwhich this column is built.


SQL_DESC_BASE_TABLE CHAR(128) The name of the underlying table over which thiscolumn is built.


SQLColAttribute


Table 28. Field Identifier descriptor types (continued)


SQL_DESC_COLUMN_CCSID INTEGER The CCSID of the column identified inColumnNumber is returned in NumericAttributePtr.This is the CCSID of the result set column data as itis known to the database before the column isbound out to the application, and may not containthe CCSID of the data returned for the column tothe application. For instance, for a result set columnconsisting simply of a base table's column, this fieldwill contain the CCSID of the column - the sameCCSID value as shown in the CCSID column of theSYSCOLUMNS view. On the other hand, the CCSIDfor a derived result set column, such as one thatcontains an expression, will be set based on theexpression and the job environment in which thestatement is run. For data types where the CCSID isnot applicable, a value of 0 is returned.

SQL_DESC_COUNT INTEGER The number of columns in the result set is returnedin NumericAttributePtr.

SQL_DESC_DISPLAY_SIZE SMALLINT The maximum number of bytes needed to displaythe data in character form is returned inNumericAttributePtr.

SQL_DESC_LABEL CHAR(128) The label for this column, if one exists. Otherwise, azero-length string.


SQL_DESC_LENGTH INTEGER The number of bytes of data associated with thecolumn is returned in NumericAttributePtr.

If the column identified in ColumnNumber ischaracter based, for example, SQL_CHAR,SQL_VARCHAR, or SQL_LONG_VARCHAR, theactual length or maximum length is returned.

If the column type is SQL_DECIMAL orSQL_NUMERIC, SQL_DESC_LENGTH is (precision *256) + scale. This is returned so that the same valuecan be passed as input on SQLBindCol(). Theprecision and scale can also be obtained as separatevalues for these data types by usingSQL_DESC_PRECISION and SQL_DESC_SCALE.

SQL_DESC_NAME CHAR(128) The name of the column ColumnNumber is returnedin CharacterAttributePtr. If the column is anexpression, then the result returned is productspecific.

SQL_DESC_NULLABLE SMALLINT If the column identified by ColumnNumber cancontain nulls, then SQL_NULLABLE is returned inNumericAttributePtr.

If the column is constrained not to accept nulls, thenSQL_NO_NULLS is returned in NumericAttributePtr.

SQL_DESC_PRECISION SMALLINT The precision attribute of the column is returned.

SQL_DESC_SCALE SMALLINT The scale attribute of the column is returned.

SQLColAttribute


Table 28. Field Identifier descriptor types (continued)


SQL_DESC_SEARCHABLE INTEGER This is SQL_UNSEARCHABLE if the column cannotbe used in a WHERE clause.

This is SQL_LIKE_ONLY if the column can be usedin a WHERE clause only with the LIKE predicate.

This is SQL_ALL_EXCEPT_LIKE if the column canbe used in a WHERE clause with all comparisonoperators except LIKE.

This is SQL_SEARCHABLE if the column can beused in a WHERE clause with any comparisonoperator.


SQL_DESC_TYPE_NAME CHAR(128) The character representation of the SQL data type ofthe column identified in ColumnNumber. This isreturned in CharacterAttributePtr. The possible valuesfor the SQL data type are listed inTable 3 on page18. In addition, user-defined type (UDT) informationis also returned. The format for the UDT is <schemaname qualifier><job's current separator><UDTname>.

SQL_DESC_TYPE SMALLINT The SQL data type of the column identified inColumnNumber is returned in NumericAttributePtr.The possible values for pfSqlType are listed in Table 3on page 18.

SQL_DESC_UNNAMED SMALLINT This is SQL_NAMED if the NAME field is an actualname, or SQL_UNNAMED if the NAME field is animplementation-generated name.

SQL_DESC_UPDATABLE INTEGER Column is described by the values for the definedconstants:

SQL_ATTR_READONLYSQL_ATTR_WRITESQL_ATTR_READWRITE_UNKNOWN

SQL_COLUMN_UPDATABLE describes theupdatability of the column in the result set. Whethera column can be updated can be based on the datatype, user privileges, and the definition of the resultset itself. If it is unclear whether a column can beupdated, SQL_ATTR_READWRITE_UNKNOWNshould be returned.


SQLColAttribute


Usage

Instead of returning a specific set of arguments like SQLDescribeCol(), SQLColAttribute() can be used tospecify which attribute you want to receive for a specific column. If the required information is a string,it is returned in CharacterAttributePtr. If the required information is a number, it is returned inNumericAttributePtr.

Although SQLColAttribute() allows for future extensions, it requires more calls to receive the sameinformation than SQLDescribeCol() for each column.

If a FieldIdentifier descriptor type does not apply to the database server, an empty string is returned inCharacterAttributePtr or zero is returned in NumericAttributePtr, depending on the expected result of thedescriptor.

Columns are identified by a number (numbered sequentially from left to right starting with 1) and can bedescribed in any order.

Calling SQLColAttribute() with FieldIdentifier set to SQL_DESC_COUNT is an alternative to callingSQLNumResultCols() to determine whether any columns can be returned.

Call SQLNumResultCols() before calling SQLColAttribute() to determine whether a result set exists.

Return codesv SQL_SUCCESSv SQL_SUCCESS_WITH_INFOv SQL_ERRORv SQL_INVALID_HANDLEv SQL_NO_DATA_FOUND

Diagnostics

Table 29. SQLColAttribute SQLSTATEs


01004 Data truncated The requested information is returned as anull-terminated string and its length exceeded the lengthof the application buffer as specified in cbInfoValueMax.The argument pcbInfoValue contains the actual (nottruncated) length of the requested information.

07009 Column number that is notvalid

The value specified for the argument ColumnNumber isless than 1.


The value specified for the argument FieldIdentifier is notequal to a value specified in Table 27 on page 63.

The argument CharacterAttributePtr, StringLengthPtr, orNumericAttributePtr is a null pointer.

HY010 Function sequence error The function is called before calling SQLPrepare() orSQLExecDirect() for the StatementHandle.



HYC00 Driver not capable The SQL data type returned by the database server forcolumn ColumnNumber is not recognized by Db2 for iCLI.

SQLColAttribute


Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLDescribeCol - Describe column attributes” on page 85v “SQLExecDirect - Execute a statement directly” on page 102v “SQLExecute - Execute a statement” on page 104v “SQLPrepare - Prepare a statement” on page 200

SQLColAttribute


SQLColAttributes - Obtain column attributesSQLColAttributes() has been deprecated and replaced by SQLColAttribute().

Although this release version of DB2 CLI continues to support SQLColAttributes(), it is recommendedthat you begin using SQLColAttribute() in your DB2 CLI programs so that they conform to the lateststandards.”

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLColAttributesW(). Refer to “Unicode in Db2 for i CLI” on page307 for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLColAttributes (SQLHSTMT StatementHandle,

SQLSMALLINT ColumnNumber,SQLSMALLINT FieldIdentifier,SQLCHAR *CharacterAttributePtr,SQLINTEGER BufferLength,SQLINTEGER *StringLengthPtr,SQLINTEGER *NumericAttributePtr);

Note: Refer to “SQLColAttribute - Return a column attribute” on page 63 for a description of theapplicable sections.

SQLColAttributes


|||||||

SQLColumnPrivileges - Get privileges associated with the columns ofa tableSQLColumnPrivileges() returns a list of columns and associated privileges for the specified table. Theinformation is returned in an SQL result set, which can be retrieved with the same functions that are usedto process a result set generated from a query.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLColumnPrivilegesW(). Refer to “Unicode in Db2 for i CLI” on page307 for more information about Unicode support forDb2 for i CLI.

SyntaxSQLRETURN SQLColumnPrivileges (

SQLHSTMT StatementHandle,SQLCHAR *CatalogName,SQLSMALLINT NameLength1,SQLCHAR *SchemaName,SQLSMALLINT NameLength2,SQLCHAR *TableNameSQLSMALLINT NameLength3,SQLCHAR *ColumnName,SQLSMALLINT NameLength4);

Function arguments

Table 30. SQLColumnPrivileges arguments



SQLCHAR * CatalogName Input Catalog qualifier of a 3 part table name. Thismust be a NULL pointer or a zero lengthstring.

SQLSMALLINT NameLength1 Input Length of CatalogName. This must be set to 0.

SQLCHAR * SchemaName Input Schema qualifier of table name.

SQLSMALLINT NameLength2 Input Length of SchemaName.

SQLCHAR * TableName Input Table Name.

SQLSMALLINT NameLength3 Input Length of TableName.

SQLCHAR * ColumnName Input Buffer that can contain a pattern-value toqualify the result set by column name.

SQLSMALLINT NameLength4 Input Length of ColumnName.

Usage

The results are returned as a standard result set containing the columns listed in Table 31 on page 71. Theresult set is ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME, COLUMN_NAME, andPRIVILEGE. If multiple privileges are associated with any given column, each privilege is returned as aseparate row. A typical application might want to call this function after a call to SQLColumns() todetermine column privilege information. The application should use the character strings returned in theTABLE_SCHEM, TABLE_NAME, COLUMN_NAME columns of the SQLColumns() result set as inputarguments to this function

Because calls to SQLColumnPrivileges() in many cases map to a complex and thus expensive queryagainst the system catalog, they should be used sparingly, and the results saved rather than repeating thecalls.

SQLColumnPrivileges


The VARCHAR columns of the catalog-functions result set have been declared with a maximum lengthattribute of 128 to be consistent with SQL92 limits. Because Db2 for i names are always 128 characters orless in length, the application can choose to always set aside 128 characters (plus the null-terminator) forthe output buffer, or alternatively, call SQLGetInfo() with SQL_MAX_CATALOG_NAME_LEN,SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN, andSQL_MAX_COLUMN_NAME_LEN. The SQL_MAX_CATALOG_NAME_LEN value determines the actuallength of the TABLE_CAT supported by the connected Database Management System (DBMS). TheSQL_MAX_SCHEMA_NAME_LEN value determines the actual length of the TABLE_SCHEM supportedby the connected DBMS. The SQL_MAX_TABLE_NAME_LEN value determines the actual length of theTABLE_NAME supported by the connected DBMS. The SQL_MAX_COLUMN_NAME_LEN valuedetermines the actual length of the COLUMN_NAME supported by the connected DBMS.

Note that the ColumnName argument accepts a search pattern.

Table 31. Columns returned by SQLColumnPrivileges

Column number/name Data type Description

1 TABLE_CAT VARCHAR(128) This is always NULL.

2 TABLE_SCHEM VARCHAR(128) The name of the schema containingTABLE_NAME.

3 TABLE_NAME VARCHAR(128) not NULL Name of the table or view.

4 COLUMN_NAME VARCHAR(128) not NULL Name of the column of the specifiedtable or view.

5 GRANTOR VARCHAR(128) Authorization ID of the user whogranted the privilege.

6 GRANTEE VARCHAR(128) Authorization ID of the user to whomthe privilege is granted.

7 PRIVILEGE VARCHAR(128) The column privilege. This can be:

v INSERT

v REFERENCES

v SELECT

v UPDATE

8 IS_GRANTABLE VARCHAR(3) This indicates whether the grantee ispermitted to grant the privilege toother users.

Either YES or NO.

Note: The column names used by Db2 for i CLI follow the X/Open CLI CAE specification style. Thecolumn types, contents and order are identical to those defined for the SQLColumnPrivileges() result setin ODBC.

If there is more than one privilege associated with a column, then each privilege is returned as a separaterow in the result set.


SQLColumnPrivileges


Diagnostics

Table 32. SQLColumnPrivileges SQLSTATEs


HY001 Memory allocation failure The driver is unable to allocatememory required to support theprocessing or completion of thefunction.


The value of one of the name lengtharguments is less than 0, but notequal to SQL_NTS.

HY010 Function sequence error There is an open cursor for thisstatement handle, or there is noconnection for this statement handle.

HY021 Internal descriptor that is not valid The internal descriptor cannot beaddressed or allocated, or it containsa value that is not valid.

Restrictions

None.

Example/* From the CLI sample TBINFO.C *//* ... */

/* call SQLColumnPrivileges */printf("\n Call SQLColumnPrivileges for:\n");printf(" tbSchema = %s\n", tbSchema);printf(" tbName = %s\n", tbName);sqlrc = SQLColumnPrivileges( hstmt, NULL, 0,

tbSchema, SQL_NTS,tbName, SQL_NTS,colNamePattern, SQL_NTS);

Referencesv “SQLColumns - Get column information for a table” on page 73v “SQLTables - Get table information” on page 266

SQLColumnPrivileges


SQLColumns - Get column information for a tableSQLColumns() returns a list of columns in the specified tables. The information is returned in an queryresult set, which can be retrieved with the same functions that are used to fetch a result set generated bya SELECT statement.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLColumnsW(). Refer to “Unicode in Db2 for i CLI” on page 307 formore information about Unicode support for Db2 for i CLI.

SyntaxSQLRETURN SQLColumns (SQLHSTMT hstmt,

SQLCHAR *szCatalogName,SQLSMALLINT cbCatalogName,SQLCHAR *szSchemaName,SQLSMALLINT cbSchemaName,SQLCHAR *szTableName,SQLSMALLINT cbTableName,SQLCHAR *szColumnName,SQLSMALLINT cbColumnName);

Function arguments

Table 33. SQLColumns arguments



SQLCHAR * szCatalogName Input Buffer that might contain a pattern-value toqualify the result set. Catalog is the first partof a three-part table name.

This must be a NULL pointer or a zerolength string.

SQLSMALLINT cbCatalogName Input Length of szCatalogName. This must be set to0.

SQLCHAR * szSchemaName Input Buffer that might contain a pattern-value toqualify the result set by schema name.

SQLSMALLINT cbSchemaName Input Length of szSchemaName

SQLCHAR * szTableName Input Buffer that might contain a pattern-value toqualify the result set by table name.

SQLSMALLINT cbTableName Input Length of szTableName

SQLCHAR * szColumnName Input Buffer that can contain a pattern-value toqualify the result set by column name.

SQLSMALLINT cbColumnName Input Length of szColumnName

Usage

This function retrieves information about the columns of a table or a list of tables.

SQLColumns() returns a standard result set. Table 34 on page 74 lists the columns in the result set.

The szCatalogName, szSchemaName, szTableName, and szColumnName arguments accept search patterns. Anescape character can be specified in conjunction with a wildcard character to allow that actual characterto be used in the search pattern. The escape character is specified on the SQL_ATTR_ESCAPE_CHARenvironment attribute.

SQLColumns


This function does not return information about the columns in a result set, which is retrieved bySQLDescribeCol() or SQLColAttribute(). If an application wants to obtain column information for a resultset, it should always call SQLDescribeCol() or SQLColAttribute() for efficiency. SQLColumns() maps to acomplex query against the system catalogs, and can require a large amount of system resources.

Table 34. Columns returned by SQLColumns


1 TABLE_CAT VARCHAR(128) The current server.


3 TABLE_NAME VARCHAR(128) Name of the table, view or alias.

4 COLUMN_NAME VARCHAR(128) Column identifier. The name of the column ofthe specified view, table, or table's column thealias is built for.

5 DATA_TYPE SMALLINT not NULL DATA_TYPE identifies the SQL data type of thecolumn.

6 TYPE_NAME VARCHAR(128) not NULL TYPE_NAME is a character string representingthe name of the data type corresponding toDATA_TYPE. If the data type is FOR BIT DATA,then the corresponding string FOR BIT DATA isappended to the data type, for example, CHAR() FOR BIT DATA.

7 COLUMN_SIZE INTEGER If DATA_TYPE is an approximate numeric datatype, this column contains the number of bits ofmantissa precision of the column. For exactnumeric data types, this column contains thetotal number of decimal digit allowed in thecolumn. For time and timestamp data types, thiscolumn contains the number of digits ofprecision of the fractional seconds component;otherwise, this column is NULL.Note: The ODBC definition of precision istypically the number of digits to store the datatype.

8 BUFFER_LENGTH INTEGER The maximum number of bytes to store datafrom this column if SQL_DEFAULT werespecified on the SQLBindCol() , SQLGetData()andSQLBindParam() calls.

9 DECIMAL_DIGITS SMALLINT The scale of the column. NULL is returned fordata types where scale is not applicable.

SQLColumns


Table 34. Columns returned by SQLColumns (continued)


10 NUM_PREC_RADIX SMALLINT The value is 10, 2, or NULL. If DATA_TYPE isan approximate numeric data type, this columncontains the value 2; then theLENGTH_PRECISION column contains thenumber of bits allowed in the column.

If DATA_TYPE is an exact numeric data type,this column contains the value 10 and theLENGTH_PRECISION and NUM_SCALEcolumns contain the number of decimal digitsallowed for the column.

For numeric data types, the DatabaseManagement System (DBMS) can return aNUM_PREC_RADIX of either 10 or 2.

NULL is returned for data types where radix isnot applicable.

11 NULLABLE SMALLINT not NULL SQL_NO_NULLS if the column does not acceptNULL values.

SQL_NULLABLE if the column accepts NULLvalues.

12 REMARKS NVARCHAR(2000) Contains descriptive information about thecolumn.

13 COLUMN_DEF NVARCHAR(2000) The column's default value. If the default valueis a numeric literal, then this column contains thecharacter representation of the numeric literalwith no enclosing single quotation marks. If thedefault value is a character string, then thiscolumn is that string enclosed in single quotationmarks. If the default value a pseudo-literal, suchas for DATE, TIME, and TIMESTAMP columns,then this column contains the keyword of thepseudo-literal (for example, CURRENT DATE)with no enclosing quotation marks.

If NULL is specified as the default value, thenthis column returns the word NULL, notenclosed in quotation marks. If the default valuecannot be represented without truncation, thenthis column contains TRUNCATED with noenclosing single quotation marks. If no defaultvalue is specified, then this column is NULL.

14 SQL_DATA_TYPE SMALLINT not NULL DATA_TYPE identifies the SQL data type of thecolumn.

15 SQL_DATETIME_SUB SMALLINT The subtype code for date and time data types:

v SQL_DATE

v SQL_TIME

v SQL_TIMESTAMP

For all other data types, this column returnsNULL.

SQLColumns


||||

|||||||||||||

|||||||

Table 34. Columns returned by SQLColumns (continued)


16 CHAR_OCTET_LENGTH INTEGER This contains the maximum length in octets for acharacter data type column. For single bytecharacter sets, this is the same asLENGTH_PRECISION. For all other data types,it is NULL.

17 ORDINAL_POSITION INTEGER not NULL The ordinal position of the column in the table.The first column in the table is number 1.

18 IS_NULLABLE VARCHAR(3) Contains the string 'NO' if the column is knownto be not nullable; and 'YES' otherwise.


Diagnostics

Table 35. SQLColumns SQLSTATEs


HY001 Memory allocation failure The driver is unable to allocatememory required to support theprocessing or completion of thefunction.


The value of one of the name lengtharguments is less than 0, but notequal SQL_NTS.

HY010 Function sequence error There is an open cursor for thisstatement handle, or there is noconnection for this statement handle.

HY021 Internal descriptor that is not valid The internal descriptor cannot beaddressed or allocated, or it containsa value that is not valid.

SQLColumns


||||

SQLConnect - Connect to a data sourceSQLConnect() establishes a connection to the target database. The application can optionally supply atarget SQL database, an authorization name, and an authentication string.

SQLAllocConnect() must be called before calling this function.

This function must be called before calling SQLAllocStmt().

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLConnectW(). Refer to “Unicode in Db2 for i CLI” on page 307 formore information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLConnect (SQLHDBC hdbc,

SQLCHAR *szDSN,SQLSMALLINT cbDSN,SQLCHAR *szUID,SQLSMALLINT cbUID,SQLCHAR *szAuthStr,SQLSMALLINT cbAuthStr);

Function arguments

Table 36. SQLConnect arguments


SQLHDBC hdbc Input Connection handle.

SQLCHAR * szDSN Input Data source: name or alias name of thedatabase.

SQLSMALLINT cbDSN Input Length of contents of szDSN argument.

SQLCHAR * szUID Input Authorization name (user identifier).

SQLSMALLINT cbUID Input Length of contents of szUID argument.

SQLCHAR * szAuthStr Input Authentication string (password).

SQLSMALLINT cbAuthStr Input Length of contents of szAuthStr argument.

Usage

You can define various connection characteristics (options) in the application usingSQLSetConnectOption().

The input length arguments to SQLConnect() (cbDSN, cbUID, cbAuthStr) can be set to the actual length oftheir associated data - this does not include any null-terminating character - or to SQL_NTS to indicatethat the associated data is null-terminated.

Leading and trailing blanks in the szDSN and szUID argument values are stripped before processingunless they are enclosed in quotation marks.

Input arguments szUID and szAuthStr are treated as case sensitive.

When running in server mode, both szUID and szAuthStr must be passed in order for the connection torun on behalf of a user ID other than the current user. If either parameter is NULL or both are NULL, theconnection is started using the user ID that is in effect for the current job running the CLI program.

SQLConnect


|||

The data source must already be defined on the system for the connect function to work. On the IBM iplatform, you can use the Work with Relational Database Directory Entries (WRKRDBDIRE) command todetermine which data sources have been defined, and to optionally define additional data sources.

If the application does not supply a target database (szDSN), the CLI uses the local database as thedefault.

Non-server mode connections to the *LOCAL relational database must specify for the connecting szUIDeither NULL or the current user. In this case, the password is not validated. When a non-server modeconnection is used, the application should not obtain the connecting szUID as input from the user, sinceSQLConnect will not validate the password associated with the connection.


Diagnostics

Table 37. SQLConnect SQLSTATEs


08001 Unable to connect to datasource

The driver is unable to establish a connection with thedata source (server).

08002 Connection in use The specified hdbc has been used to establish aconnection with a data source and the connection is stillopen.

08004 Data source rejectedestablishment of connection

The data source (server) rejected the establishment of theconnection.

28000 Authorization specificationthat is not valid

The value specified for the argument szUID or the valuespecified for the argument szAuthStr violated restrictionsdefined by the data source.




The value specified for argument cbDSN is less than 0,but not equal to SQL_NTS and the argument szDSN isnot a null pointer.

The value specified for argument cbUID is less than 0,but not equal to SQL_NTS and the argument szUID isnot a null pointer.

The value specified for argument cbAuthStr is less than 0,but not equal to SQL_NTS and the argument szAuthStr isnot a null pointer.

A nonmatching double quotation mark (") is found ineither the szDSN, szUID, or szAuthStr argument.



HY501 * Data source name that is notvalid

A data source name that is not valid is specified inargument szDSN.

SQLConnect


||||

Restrictions

The implicit connection (or default database) option for IBM DBMSs is not supported. SQLConnect() mustbe called before any SQL statements can be processed. Db2 for i does not support multiple simultaneousconnections to the same data source in a single job.

When you are using Db2 for i CLI on a newer release, SQLConnect() can encounter an SQL0144 message.This indicates that the data source (the server) has obsolete SQL packages that must be deleted. To deletethese packages, run the following command on the data source:

DLTSQLPKG SQLPKG(QGPL/QSQCLI*)

The next SQLConnect() creates a new SQL package.

Example

Refer to the example in “SQLAllocEnv - Allocate environment handle” on page 30.

Referencesv “SQLAllocConnect - Allocate connection handle” on page 27v “SQLAllocStmt - Allocate a statement handle” on page 34

SQLConnect


SQLCopyDesc - Copy description statementSQLCopyDesc() copies the fields of the data structure associated with the source handle to the datastructure associated with the target handle.

Any existing data in the data structure associated with the target handle is overwritten, except that theALLOC_TYPE field is not changed.

SyntaxSQLRETURN SQLCopyDesc (SQLHDESC sDesc)

(SQLHDESC tDesc);

Function arguments

Table 38. SQLCopyDesc arguments


SQLHDESC sDesc Input Source descriptor handle

SQLHDESC tDesc Input Target descriptor handle

Usage

Handles for the automatically-generated row and parameter descriptors of a statement can be obtainedby calling GetStmtAttr().


SQLCopyDesc


SQLDataSources - Get list of data sourcesSQLDataSources() returns a list of target databases available, one at a time. A database must be catalogedto be available.

For more information about cataloging, refer to the usage notes for SQLConnect() or see the online helpfor the Work with Relational Database (RDB) Directory Entries (WRKRDBDIRE) command.

SQLDataSources() is typically called before a connection is made, to determine the databases that areavailable to connect to.

If you are running Db2 for i CLI in SQL server mode, some restrictions apply when you useSQLDataSources().

For more information about running in server mode refer to the “Restrictions for running Db2 for i CLIin server mode” on page 306.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLDataSourcesW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLDataSources (SQLHENV EnvironmentHandle,

SQLSMALLINT Direction,SQLCHAR *ServerName,SQLSMALLINT BufferLength1,SQLSMALLINT *NameLength1Ptr,SQLCHAR *Description,SQLSMALLINT BufferLength2,SQLSMALLINT *NameLength2Ptr);

Function arguments

Table 39. SQLDataSources arguments


SQLHENV EnvironmentHandle Input Environment handle.

SQLSMALLINT Direction Input This is used by application to request the first datasource name in the list or the next one in the list.Direction can take on only the following values:

v SQL_FETCH_FIRST

v SQL_FETCH_NEXT

SQLCHAR * ServerName Output Pointer to buffer to hold the data source nameretrieved.

SQLSMALLINT BufferLength1 Input Maximum length in characters of the buffer pointedto by ServerName. This should be less than or equalto SQL_MAX_DSN_LENGTH + 1.

SQLSMALLINT * NameLength1Ptr Output Pointer to location where the maximum number ofcharacters available to return in the ServerName isstored.

SQLCHAR * Description Output Pointer to buffer where the description of the datasource is returned. Db2 for i CLI returns theComment field associated with the databasecatalogued to the Database Management System(DBMS).

SQLDataSources


Table 39. SQLDataSources arguments (continued)


SQLSMALLINT BufferLength2 Input Maximum length in characters of the Descriptionbuffer.

SQLSMALLINT * NameLength2Ptr Output Pointer to location where the function returns theactual number of characters available to return forthe description of the data source.

Usage

The application can call this function any time by setting Direction to either SQL_FETCH_FIRST orSQL_FETCH_NEXT.

If SQL_FETCH_FIRST is specified, the first database in the list is always returned.

If SQL_FETCH_NEXT is specified:v Directly following the SQL_FETCH_FIRST call, the second database in the list is returnedv Before any other SQLDataSources() call, the first database in the list is returnedv When there are no more databases in the list, SQL_NO_DATA_FOUND is returned. If the function is

called again, the first database is returned.v Any other time, the next database in the list is returned.


Error conditions

Table 40. SQLDataSources SQLSTATEs


01004 Data truncated The data source name returned in the argument ServerName islonger than the value specified in the argument BufferLength1. Theargument NameLength1Ptr contains the length of the full datasource name. (Function returns SQL_SUCCESS_WITH_INFO.)

The data source name returned in the argument Description islonger than the value specified in the argument BufferLength2. Theargument NameLength2Ptr contains the length of the full datasource description. (Function returnsSQL_SUCCESS_WITH_INFO.)


HY000 General error An error occurred for which there is no specific SQLSTATE andfor which no specific SQLSTATE is defined. The error messagereturned by SQLError() in the argument ErrorMsg describes theerror and its cause.


SQLDataSources


Table 40. SQLDataSources SQLSTATEs (continued)


HY009 Argument value that is not valid The argument ServerName, NameLength1Ptr, Description, orNameLength2Ptr is a null pointer.

Value for the direction that is not valid.



HY103 Direction option out of range The value specified for the argument Direction is not equal toSQL_FETCH_FIRST or SQL_FETCH_NEXT.

Authorization

None.

Example

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./* From CLI sample datasour.c *//* ... */

#include <stdio.h>#include <stdlib.h>#include <sqlcli1.h>#include "samputil.h" /* Header file for CLI sample code */

/* ... */

/********************************************************************* main** - initialize** - terminate*******************************************************************/int main() {

SQLHANDLE henv ;SQLRETURN rc ;SQLCHAR source[SQL_MAX_DSN_LENGTH + 1], description[255] ;SQLSMALLINT buffl, desl ;

/* ... */

/* allocate an environment handle */rc = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv ) ;if ( rc != SQL_SUCCESS ) return( terminate( henv, rc ) ) ;

/* list the available data sources (servers) */printf( "The following data sources are available:\n" ) ;printf( "ALIAS NAME Comment(Description)\n" ) ;printf( "----------------------------------------------------\n" ) ;

while ( ( rc = SQLDataSources( henv,SQL_FETCH_NEXT,source,SQL_MAX_DSN_LENGTH + 1,&buffl,description,255,&desl

)

SQLDataSources


) != SQL_NO_DATA_FOUND) printf( "%-30s %s\n", source, description ) ;

rc = SQLFreeHandle( SQL_HANDLE_ENV, henv ) ;if ( rc != SQL_SUCCESS ) return( terminate( henv, rc ) ) ;

return( SQL_SUCCESS ) ;

}

SQLDataSources


SQLDescribeCol - Describe column attributesSQLDescribeCol() returns the result descriptor information (column name, type, precision) for theindicated column in the result set generated by a SELECT statement.

If the application needs only one attribute of the descriptor information, the SQLColAttribute() functioncan be used in place of SQLDescribeCol().

Either SQLPrepare() or SQLExecDirect() must be called before calling this function.

This function (or SQLColAttribute()) is typically called before SQLBindCol().

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLDescribeColW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLDescribeCol (SQLHSTMT hstmt,

SQLSMALLINT icol,SQLCHAR *szColName,SQLSMALLINT cbColNameMax,SQLSMALLINT *pcbColName,SQLSMALLINT *pfSqlType,SQLINTEGER *pcbColDef,SQLSMALLINT *pibScale,SQLSMALLINT *pfNullable);

Function arguments

Table 41. SQLDescribeCol arguments



SQLSMALLINT icol Input Column number to be described.

SQLCHAR * szColName Output Pointer to column name buffer.

SQLSMALLINT cbColNameMax Input Size of szColName buffer.

SQLSMALLINT * pcbColName Output Bytes available to return for szColNameargument. Truncation of column name(szColName) to cbColNameMax - 1 bytesoccurs if pcbColName is greater than or equalto cbColNameMax. If pfSqlType denotes agraphic SQL data type, this variable indicatesthe maximum number of double-bytecharacters the column can hold.

SQLSMALLINT * pfSqlType Output SQL data type of column.

SQLINTEGER * pcbColDef Output Precision of column as defined in thedatabase.

If fSqlType denotes a graphic SQL data type,then this variable indicates the maximumnumber of double-byte characters the columncan hold.

SQLSMALLINT * pibScale Output Scale of column as defined in the database(only applies to SQL_DECIMAL,SQL_NUMERIC, SQL_TIMESTAMP).

SQLDescribeCol


Table 41. SQLDescribeCol arguments (continued)


SQLSMALLINT * pfNullable Output This indicates whether NULLS are allowedfor this column

v SQL_NO_NULLS.

v SQL_NULLABLE.

Usage

Columns are identified by a number and are numbered sequentially from left to right starting with 1, andcan be described in any order.

A valid pointer and buffer space must be made available for the szColName argument. If a null pointer isspecified for any of the remaining pointer arguments, Db2 for i CLI assumes that the information is notneeded by the application and nothing is returned.


Diagnostics

If SQLDescribeCol() returns either SQL_ERROR, or SQL_SUCCESS_WITH_INFO, one of the followingSQLSTATEs can be obtained by calling the SQLError() function.

Table 42. SQLDescribeCol SQLSTATEs


01004 Data truncated The column name returned in the argument szColName islonger than the value specified in the argumentcbColNameMax. The argument pcbColName contains thelength of the full column name. (Function returnsSQL_SUCCESS_WITH_INFO.)

07005 * Not a SELECT statement The statement associated with the hstmt did not return aresult set. There were no columns to describe. (CallSQLNumResultCols() first to determine if there are anyrows in the result set.)

07009 Column number that is notvalid

The value specified for the argument icol is less than 1.

The value specified for the argument icol is greater thanthe number of columns in the result set.






The length specified in argument cbColNameMax is lessthan 1.

The argument szColName or pcbColName is a null pointer.

SQLDescribeCol


Table 42. SQLDescribeCol SQLSTATEs (continued)


HY010 Function sequence error The function is called before calling SQLPrepare() orSQLExecDirect() for the hstmt.



HYC00 Driver not capable The SQL data type of column icol is not recognized byDb2 for i CLI.

Example

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./********************************************************************* file = typical.c.../********************************************************************* display_results**** - for each column** - get column name** - bind column** - display column headings** - fetch each row** - if value truncated, build error message** - if column null, set value to "NULL"** - display row** - print truncation message** - free local storage*******************************************************************/display_results(SQLHSTMT hstmt,

SQLSMALLINT nresultcols){SQLCHAR colname[32];SQLSMALLINT coltype;SQLSMALLINT colnamelen;SQLSMALLINT nullable;SQLINTEGER collen[MAXCOLS];SQLSMALLINT scale;SQLINTEGER outlen[MAXCOLS];SQLCHAR * data[MAXCOLS];SQLCHAR errmsg[256];SQLRETURN rc;SQLINTEGER i;SQLINTEGER displaysize;

for (i = 0; i < nresultcols; i++){

SQLDescribeCol (hstmt, i+1, colname, sizeof (colname),&colnamelen, &coltype, &collen[i], &scale, &nullable);

/* get display length for column */SQLColAttribute (StatementHandle, i+1, SQL_COLUMN_DISPLAY_SIZE, NULL, 0,

NULL, &displaysize);

/* set column length to max of display length, and column namelength. Plus one byte for null terminator */

collen[i] = max(displaysize, strlen((char *) colname) ) + 1;

/* allocate memory to bind column */data[i] = (SQLCHAR *) malloc (collen[i]);

SQLDescribeCol


/* bind columns to program vars, converting all types to CHAR */SQLBindCol (hstmt, i+1, SQL_CHAR, data[i], collen[i],

&outlen[i]);}printf("\n");

/* display result rows */while ((rc = SQLFetch (hstmt)) != SQL_NO_DATA_FOUND){

errmsg[0] = ’\0’;for (i = 0; i < nresultcols; i++){

/* Build a truncation message for any columns truncated */if (outlen[i] >= collen[i]){ sprintf ((char *) errmsg + strlen ((char *) errmsg),

"%d chars truncated, col %d\n",outlen[i]-collen[i]+1, i+1);

}if (outlen[i] == SQL_NULL_DATA)else

} /* for all columns in this row */

printf ("\n%s", errmsg); /* print any truncation messages */} /* while rows to fetch */

/* free data buffers */for (i = 0; i < nresultcols; i++){

free (data[i]);}

}/* end display_results

Referencesv “SQLColAttribute - Return a column attribute” on page 63v “SQLColAttributes - Obtain column attributes” on page 69v “SQLExecDirect - Execute a statement directly” on page 102v “SQLNumResultCols - Get number of result columns” on page 194v “SQLPrepare - Prepare a statement” on page 200

SQLDescribeCol


SQLDescribeParam - Return description of a parameter markerSQLDescribeParam() returns the description of a parameter marker associated with a prepared SQLstatement. This information is also available in the fields of the implementation parameter descriptor.

SyntaxSQLRETURN SQLDescribeParam (SQLHSTMT StatementHandle,

SQLSMALLINT ParameterNumber,SQLSMALLINT *DataTypePtr,SQLINTEGER *ParameterSizePtr,SQLSMALLINT *DecimalDigitsPtr,SQLSMALLINT *NullablePtr);

Function arguments

Table 43. SQLDescribeParam arguments



SQLSMALLINT ParameterNumber Input Parameter marker number ordered sequentially inincreasing parameter order, starting at 1.

SQLSMALLINT * DataTypePtr Output Pointer to a buffer in which to return the SQL datatype of the parameter.

SQLINTEGER * ParameterSizePtr Output Pointer to a buffer in which to return the size of thecolumn or expression of the correspondingparameter marker as defined by the data source.

SQLSMALLINT * DecimalDigitsPtr Output Pointer to a buffer in which to return the number ofdecimal digits of the column or expression of thecorresponding parameter as defined by the datasource.

SQLSMALLINT * NullablePtr Output Pointer to a buffer in which to return a value thatindicates whether the parameter allows NULLvalues. This value is read from theSQL_DESC_NULLABLE field of the implementationparameter descriptor.

v SQL_NO_NULLS – The parameter does not allowNULL values (this is the default value).

v SQL_NULLABLE – The parameter allows NULLvalues.

v SQL_NULLABLE_UNKNOWN – Cannotdetermine if the parameter allows NULL values.

Usage

Parameter markers are numbered in increasing parameter order, starting with 1, in the order they appearin the SQL statement.

SQLDescribeParam() does not return the type (input, output, or both input and output) of a parameter inan SQL statement. Except in calls to procedures, all parameters in SQL statements are input parameters.To determine the type of each parameter in a call to a procedure, an application callsSQLProcedureColumns().

Return codesv SQL_SUCCESSv SQL_SUCCESS_WITH_INFO

SQLDescribeParam


v SQL_ERRORv SQL_INVALID_HANDLE

Error conditions

Table 44. SQLDescribeParam SQLSTATEs


01000 Warning Informational message. (Function returnsSQL_SUCCESS_WITH_INFO.)

07009 Descriptor index that is not valid The value specified for the argumentParameterNumber less than 1.

The value specified for the argumentParameterNumber is greater than the number ofparameters in the associated SQL statement.

The parameter marker is part of a non-DMLstatement.

The parameter marker is part of a SELECTlist.

08S01 Communication link failure The communication link between Db2 for iCLI and the data source to which it isconnected fails before the function completesprocessing.

21S01 Insert value list does not matchcolumn list

The number of parameters in the INSERTstatement does not match the number ofcolumns in the table named in the statement.

HY000 General error

HY001 Memory allocation failure Db2 for i CLI is unable to allocate memoryrequired to support the processing orcompletion of the function.

HY008 Operation canceled.

HY009 Argument value that is not valid The argument DataTypePtr, ParameterSizePtr,DecimalDigitsPtr, or NullablePtr is a nullpointer.

HY010 Function sequence error The function is called before callingSQLPrepare() or SQLExecDirect() for theStatementHandle.


The function call cannot be processed becausethe underlying memory objects can not beaccessed, possibly because of low memoryconditions.

Restrictions

None.

Referencesv “SQLBindParam - Bind a buffer to a parameter marker” on page 47v “SQLCancel - Cancel statement” on page 61v “SQLExecute - Execute a statement” on page 104v “SQLPrepare - Prepare a statement” on page 200

SQLDescribeParam


SQLDisconnect - Disconnect from a data sourceSQLDisconnect() ends the connection associated with the database connection handle.

After calling this function, either call SQLConnect() to connect to another database, or callSQLFreeConnect().

SyntaxSQLRETURN SQLDisconnect (SQLHDBC hdbc);

Function arguments

Table 45. SQLDisconnect arguments



Usage

If an application calls SQLDisconnect before it has freed all the statement handles associated with theconnection, Db2 for i CLI frees them after it successfully disconnects from the database.

If SQL_SUCCESS_WITH_INFO is returned, it implies that even though the disconnect from the databaseis successful, additional error or implementation specific information is available. For example:v A problem is encountered on the clean up after the disconnect, or,v If there is no current connection because of an event that occurred independently of the application

(such as communication failure).

After a successful SQLDisconnect() call, the application can re-use hdbc to make another SQLConnect()request.

If the hdbc is participating in a DUOW two-phase commit connection, the disconnect might not occurimmediately. The actual disconnect occurs at the next commit issued for the distributed transaction.


Diagnostics

Table 46. SQLDisconnect SQLSTATEs


01002 Disconnect error An error occurred during the disconnect. However, thedisconnect succeeded. (Function returnsSQL_SUCCESS_WITH_INFO.)

08003 Connection not open The connection specified in the argument hdbc is notopen.

25000 Transaction state that is notvalid

There is a transaction in process on the connectionspecified by the argument hdbc. The transaction remainsactive, and the connection cannot be disconnected.


SQLDisconnect


Table 46. SQLDisconnect SQLSTATEs (continued)





Example


Referencesv “SQLAllocConnect - Allocate connection handle” on page 27v “SQLConnect - Connect to a data source” on page 77v “SQLTransact - Commit or roll back a transaction” on page 269

SQLDisconnect


SQLDriverConnect - Connect to a data sourceSQLDriverConnect() is an alternative to SQLConnect(). Both functions establish a connection to the targetdatabase, but SQLDriverConnect() uses a connection string to determine the data source name, user ID,and password. The functions are the same; both are supported for compatibility purposes.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLDriverConnectW(). Refer to “Unicode in Db2 for i CLI” on page307 for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLDriverConnect (SQLHDBC ConnectionHandle,

SQLPOINTER WindowHandle,SQLCHAR *InConnectionString,SQLSMALLINT StringLength1,SQLCHAR *OutConnectionString,SQLSMALLINT BufferLength,SQLSMALLINT *StringLength2Ptr,SQLSMALLINT DriverCompletion);

Function arguments

Table 47. SQLDriverConnect arguments


SQLHDBC ConnectionHandle Input Connection handle.

SQLPOINTER WindowHandle Input For DB2 for Linux, UNIX, and Windows, this is theparent handle. On Db2 for i, it is ignored.

SQLCHAR * InConnectionString Input A full, partial, or empty (null pointer) connectionstring.

SQLSMALLINT StringLength1 Input Length of InConnectionString.

SQLCHAR * OutConnectionString Output Pointer to buffer for the completed connection string.

If the connection is established successfully, thisbuffer contains the completed connection string.

SQLSMALLINT BufferLength Input Maximum size of the buffer pointed to byOutConnectionString.

SQLSMALLINT * StringLength2Ptr Output Pointer to the number of bytes available to return inthe OutConnectionString buffer.

If the value of StringLength2Ptr is greater than orequal to BufferLength, the completed connectionstring in OutConnectionString is truncated toBufferLength - 1 bytes.

SQLSMALLINT DriverCompletion Input This indicates when Db2 for i CLI should promptthe user for more information.

Possible values:

v SQL_DRIVER_COMPLETE

v SQL_DRIVER_COMPLETE_REQUIRED

v SQL_DRIVER_NOPROMPT

SQLDriverConnect


Usage

The connection string is used to pass one or more values that are needed to complete a connection. Thecontents of the connection string and the value of DriverCompletion determine how the connection shouldbe established.

►► ▼

;

Connection string syntax = attribute ►◄

Connection string syntax

DSNUIDPWDDB2 CLI-defined-keyword

Each of the previous keywords has an attribute that is equal to:

DSN Data source name. The name or alias-name of the database. The data source name is required ifDriverCompletion is equal to SQL_DRIVER_NOPROMPT.

UID Authorization-name (user identifier).

PWD The password that corresponds to the authorization name. If there is no password for the userID, empty is specified (PWD=;).

The IBM i platform currently has no Db2 for i CLI-defined keywords.

Input user ID and password strings passed in argument InConnectionString are treated as case sensitive.

The value of DriverCompletion is verified to be valid, but all result in the same behavior. A connection isattempted with the information that is contained in the connection string. If there is not enoughinformation, SQL_ERROR is returned.

As soon as a connection is established, the complete connection string is returned. Applications that needto set up multiple connections to the same database for a given user ID should store this outputconnection string. This string can then be used as the input connection string value on futureSQLDriverConnect() calls.

Non-server mode connections to the *LOCAL relational database do not lead to validation of theconnecting userid and password. The *CURUSR value will be used for the connection processing.

Return codesv SQL_SUCCESSv SQL_SUCCESS_WITH_INFOv SQL_NO_DATA_FOUNDv SQL_INVALID_HANDLEv SQL_ERROR

Error conditions

All of the diagnostics that are generated by SQLConnect() can be returned here as well. The followingtable shows the additional diagnostics that can be returned.

SQLDriverConnect


Table 48. SQLDriverConnect SQLSTATEs


01004 Data truncated The buffer szConnstrOut is not large enough to hold the entireconnection string. The argument StringLength2Ptr contains theactual length of the connection string available for return.(Function returns SQL_SUCCESS_WITH_INFO)

01S00 Connection string attribute thatis not valid

A keyword or attribute value that is not valid is specified in theinput connection string, but the connection to the data source issuccessful anyway because one of the following situations occurs:

v The unrecognized keyword is ignored.

v The attribute value that is not valid is ignored, the defaultvalue is used instead.

(Function returns SQL_SUCCESS_WITH_INFO)

HY009 Argument value that is not valid The argument InConnectionString, OutConnectionString, orStringLength2PTR is a null pointer.

The argument DriverCompletion is not equal to 1.


The value specified for StringLength1 is less than 0, but not equalto SQL_NTS.

The value specified for BufferLength is less than 0.

HY110 Driver completion that is notvalid

The value specified for the argument DriverCompletion is not equalto one of the valid values.

Restrictions

None.

Example

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./* From CLI sample drivrcon.c *//* ... *//********************************************************************** drv_connect - Prompt for connect options and connect **********************************************************************/

intdrv_connect(SQLHENV henv,

SQLHDBC * hdbc,SQLCHAR con_type)

{SQLRETURN rc;SQLCHAR server[SQL_MAX_DSN_LENGTH + 1];SQLCHAR uid[MAX_UID_LENGTH + 1];SQLCHAR pwd[MAX_PWD_LENGTH + 1];SQLCHAR con_str[255];SQLCHAR buffer[255];SQLSMALLINT outlen;

printf("Enter Server Name:\n");gets((char *) server);printf("Enter User Name:\n");gets((char *) uid);printf("Enter Password Name:\n");gets((char *) pwd);

SQLDriverConnect


/* Allocate a connection handle */SQLAllocHandle( SQL_HANDLE_DBC,

henv,hdbc

);CHECK_HANDLE( SQL_HANDLE_DBC, *hdbc, rc);

sprintf((char *)con_str, "DSN=%s;UID=%s;PWD=%s;",server, uid, pwd);

rc = SQLDriverConnect(*hdbc,(SQLPOINTER) NULL,con_str,SQL_NTS,buffer, 255, &outlen,SQL_DRIVER_NOPROMPT);

if (rc != SQL_SUCCESS) {printf("Error while connecting to database, RC= %ld\n", rc);CHECK_HANDLE( SQL_NULL_HENV, *hdbc, rc);return (SQL_ERROR);


}}

References

“SQLConnect - Connect to a data source” on page 77

SQLDriverConnect


SQLEndTran - Commit or roll back a transactionSQLEndTran() commits or rolls back the current transaction in the connection.

All changes to the database that have been made on the connection since connect time or the previouscall to SQLEndTran(), whichever is the most recent, are committed or rolled back.

If a transaction is active on a connection, the application must call SQLEndTran() before it can disconnectfrom the database.

SyntaxSQLRETURN SQLEndTran (SQLSMALLINT hType,

SQLHENV handle,SQLSMALLINT fType);

Function arguments

Table 49. SQLEndTran arguments


SQLSMALLINT hType Input Type of handle. It must containSQL_HANDLE_ENV or SQL_HANDLE_DBC.

SQLHENV handle Input Handle to use when performing the COMMIT orROLLBACK.

SQLSMALLINT fType Input Wanted action for the transaction. The value for thisargument must be one of:

v SQL_COMMIT

v SQL_ROLLBACK

v SQL_COMMIT_HOLD

v SQL_ROLLBACK_HOLD

v SQL_SAVEPOINT_NAME_ROLLBACK

v SQL_SAVEPOINT_NAME_RELEASE

Usage

Completing a transaction with SQL_COMMIT or SQL_ROLLBACK has the following effects:v Statement handles are still valid after a call to SQLEndTran().v Cursor names, bound parameters, and column bindings survive transactions.v Open cursors are closed, and any result sets that are pending retrieval are discarded.

Completing the transaction with SQL_COMMIT_HOLD or SQL_ROLLBACK_HOLD still commits or rollsback the database changes, but does not cause cursors to be closed.

If no transaction is currently active on the connection, calling SQLEndTran() has no effect on the databaseserver and returns SQL_SUCCESS.

SQLEndTran() might fail while executing the COMMIT or ROLLBACK due to a loss of connection. In thiscase the application might be unable to determine whether the COMMIT or ROLLBACK has beenprocessed, and a database administrator's help might be required. Refer to the Database ManagementSystem (DBMS) product information for more information about transaction logs and other transactionmanagement tasks.

When using either SQL_SAVEPOINT_NAME_ROLLBACK or SQL_SAVEPOINT_NAME_RELEASE, youmust already have set the savepoint name using SQLSetConnectAttr.

SQLEndTran



Diagnostics

Table 50. SQLEndTran SQLSTATEs


08003 Connection not open The hdbc is not in a connected state.

08007 Connection failure duringtransaction

The connection associated with the hdbc fails during theprocessing of the function during the processing of thefunction and it cannot be determined whether the requestedCOMMIT or ROLLBACK occurs before the failure.


HY001 Memory allocation failure The driver is unable to allocate memory required to supportthe processing or completion of the function.

HY010 Function sequence error SQL_SAVEPOINT_NAME_ROLLBACK orSQL_SAVEPOINT_NAME_RELEASE is used, but thesavepoint name is not established by callingSQLSetConnectAttr() for attributeSQL_ATTR_SAVEPOINT_NAME.

HY012 Transaction operation statethat is not valid

The value specified for the argument fType is neitherSQL_COMMIT nor SQL_ROLLBACK.


The driver is unable to access memory required to supportthe processing or completion of the function.

SQLEndTran


SQLError - Retrieve error informationSQLError() returns the diagnostic information associated with the most recently called Db2 for i CLIfunction for a particular statement, connection, or environment handle.

The information consists of a standardized SQLSTATE, an error code, and a text message. Refer to“Diagnostics in a Db2 for i CLI application” on page 16 for more information.

Call SQLError() after receiving a return code of SQL_ERROR or SQL_SUCCESS_WITH_INFO fromanother function call.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLErrorW(). Refer to “Unicode in Db2 for i CLI” on page 307 formore information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLError (SQLHENV henv,

SQLHDBC hdbc,SQLHSTMT hstmt,SQLCHAR *szSqlState,SQLINTEGER *pfNativeError,SQLCHAR *szErrorMsg,SQLSMALLINT cbErrorMsgMax,SQLSMALLINT *pcbErrorMsg);

Function arguments

Table 51. SQLError arguments


SQLHENV henv Input Environment handle. To obtain diagnosticinformation associated with an environment,pass a valid environment handle. Set hdbc toSQL_NULL_HDBC. Set hstmt toSQL_NULL_HSTMT.

SQLHDBC hdbc Input Database connection handle. To obtaindiagnostic information associated with aconnection, pass a valid database connectionhandle, and set hstmt to SQL_NULL_HSTMT.The henv argument is ignored.

SQLHSTMT hstmt Input Statement handle. To obtain diagnosticinformation associated with a statement, passa valid statement handle. The henv and hdbcarguments are ignored.

SQLCHAR * szSqlState Output SQLSTATE as a string of 5 charactersterminated by a null character. The first 2characters indicate error class; the next 3indicate subclass. The values corresponddirectly to SQLSTATE values defined in theX/Open SQL CAE specification and theODBC specification, augmented with IBMspecific and product specific SQLSTATEvalues.

SQLError


Table 51. SQLError arguments (continued)


SQLINTEGER * pfNativeError Output Native error code. In Db2 for i CLI, thepfNativeError argument contains theSQLCODE value returned by the DatabaseManagement System (DBMS). If the error isgenerated by Db2 for i CLI and not theDBMS, this field is set to -99999.

SQLCHAR * szErrorMsg Output Pointer to buffer to contain theimplementation defined message text. In Db2for i CLI, only the DBMS generated messagesis returned; Db2 for i CLI itself does notreturn any message text describing theproblem.

SQLSMALLINT cbErrorMsgMax Input Maximum (that is, the allocated) length ofthe buffer szErrorMsg. The recommendedlength to allocate isSQL_MAX_MESSAGE_LENGTH + 1.

SQLSMALLINT * pcbErrorMsg Output Pointer to total number of bytes available toreturn to the szErrorMsg buffer.

Usage

The SQLSTATEs are those defined by the X/OPEN SQL CAE and the X/Open SQL CLI snapshot,augmented with IBM specific and product specific SQLSTATE values.v To obtain diagnostic information associated with an environment, pass a valid environment handle. Set

hdbc to SQL_NULL_HDBC. Set hstmt to SQL_NULL_HSTMT.v To obtain diagnostic information associated with a connection, pass a valid database connection handle,

and set hstmt to SQL_NULL_HSTMT. The henv argument is ignored.v To obtain diagnostic information associated with a statement, pass a valid statement handle. The henv

and hdbc arguments are ignored.

If diagnostic information generated by one Db2 for i CLI function is not retrieved before a function otherthan SQLError() is called with the same handle, the information for the previous function call is lost. Thisis true whether diagnostic information is generated for the second Db2 for i CLI function call.

To avoid truncation of the first level error message, declare a buffer length ofSQL_MAX_MESSAGE_LENGTH + 1. To avoid truncation of the second level error message, set the sizeof the buffer to a value greater than SQL_MAX_MESSAGE_LENGTH.

Return codesv SQL_ERRORv SQL_INVALID_HANDLEv SQL_NO_DATA_FOUNDv SQL_SUCCESS

Diagnostics

SQLSTATEs are not defined because SQLError() does not generate diagnostic information for itself.SQL_ERROR is returned if argument szSqlState, pfNativeError, szErrorMsg, or pcbErrorMsg is a nullpointer.

Example

SQLError


Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./*************************************************************************** file = typical.c************************************************************************/int print_error (SQLHENV henv,

SQLHDBC hdbc,SQLHSTMT hstmt)

{SQLCHAR buffer[SQL_MAX_MESSAGE_LENGTH + 1];SQLCHAR sqlstate[SQL_SQLSTATE_SIZE + 1];SQLINTEGER sqlcode;SQLSMALLINT length;

while ( SQLError(henv, hdbc, hstmt, sqlstate, &sqlcode, buffer,SQL_MAX_MESSAGE_LENGTH + 1, &length) == SQL_SUCCESS )

{printf("\n **** ERROR *****\n");printf(" SQLSTATE: %s\n", sqlstate);printf("Native Error Code: %ld\n", sqlcode);printf("%s \n", buffer);

};return (0);

}

SQLError


SQLExecDirect - Execute a statement directlySQLExecDirect() directly runs the specified SQL statement. The statement can only be processed once.Also, the connected database server must be able to prepare the statement.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLExecDirectW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLExecDirect (SQLHSTMT hstmt,

SQLCHAR *szSqlStr,SQLINTEGER cbSqlStr);

Function arguments

Table 52. SQLExecDirect arguments


SQLHSTMT hstmt Input Statement handle. There must not be anopen cursor associated with hstmt. See“SQLFreeStmt - Free (or reset) a statementhandle” on page 124 for more information.

SQLCHAR * szSqlStr Input SQL statement string. The connecteddatabase server must be able to prepare thestatement.

SQLINTEGER cbSqlStr Input Length of contents of szSqlStr argument. Thelength must be set to either the exact lengthof the statement, or if the statement isnull-terminated, set to SQL_NTS.

Usage

The SQL statement cannot be a COMMIT or ROLLBACK. Instead, SQLTransact() must be called to issueCOMMIT or ROLLBACK. For more information about supported SQL statements refer to Table 1 on page3.

The SQL statement string might contain parameter markers. A parameter marker is represented by a "?"character, and indicates a position in the statement where the value of an application variable is to besubstituted, when SQLExecDirect() is called. SQLBindParam() binds (or associates) an application variableto each parameter marker, to indicate if any data conversion should be performed at the time the data istransferred. All parameters must be bound before calling SQLExecDirect().

If the SQL statement is a SELECT, SQLExecDirect() generates a cursor name, and open the cursor. If theapplication has used SQLSetCursorName() to associate a cursor name with the statement handle, Db2 for iCLI associates the application generated cursor name with the internally generated one.

To retrieve a row from the result set generated by a SELECT statement, call SQLFetch() afterSQLExecDirect() returns successfully.

If the SQL statement is a Positioned DELETE or a Positioned UPDATE, the cursor referenced by thestatement must be positioned on a row. Additionally the SQL statement must be defined on a separatestatement handle under the same connection handle.

There must not be an open cursor on the statement handle.

SQLExecDirect



SQL_NO_DATA_FOUND is returned if the SQL statement is a Searched UPDATE or Searched DELETEand no rows satisfy the search condition.

Diagnostics

Table 53. SQLExecDirect SQLSTATEs



HY009 Argument value The argument szSqlStr is a null pointer.

The argument cbSqlStr is less than 1, but not equal toSQL_NTS.

HY010 Function sequence error Either no connection or there is an open cursor for thisstatement handle.



HY021 Internal descriptor The internal descriptor cannot be addressed or allocated,or it contains a value that is not valid.

Note: There are many other SQLSTATE values that can be generated by the Database Management System (DBMS),on processing of the statement.

Example


Referencesv “SQLExecute - Execute a statement” on page 104v “SQLFetch - Fetch next row” on page 108v “SQLSetParam - Set parameter” on page 246

SQLExecDirect


SQLExecute - Execute a statementSQLExecute() runs a statement that was successfully prepared using SQLPrepare() once or multiple times.The statement is processed with the current values of any application variables that were bound toparameter markers by SQLBindParam().

SyntaxSQLRETURN SQLExecute (SQLHSTMT hstmt);

Function arguments

Table 54. SQLExecute arguments


SQLHSTMT hstmt Input Statement handle. There must not be anopen cursor associated with hstmt, see“SQLFreeStmt - Free (or reset) a statementhandle” on page 124 for more information.

Usage

The SQL statement string might contain parameter markers. A parameter marker is represented by a "?"character, and indicates a position in the statement where the value of an application variable is to besubstituted, when SQLExecute() is called. SQLBindParam() is used to bind (or associate) an applicationvariable to each parameter marker, and to indicate if any data conversion should be performed at thetime the data is transferred. All parameters must be bound before calling SQLExecute().

As soon as the application has processed the results from the SQLExecute() call, it can process thestatement again with new (or the same) values in the application variables.

A statement processed by SQLExecDirect() cannot be reprocessed by calling SQLExecute(); SQLPrepare()must be called first.

If the prepared SQL statement is a SELECT, SQLExecute() generates a cursor name, and opens the cursor.If the application has used SQLSetCursorName() to associate a cursor name with the statement handle,Db2 for i CLI associates the application generated cursor name with the internally generated cursorname.

To process a SELECT statement more than once, the application must close the cursor by calling callSQLFreeStmt() with the SQL_CLOSE option. There must not be an open cursor on the statement handlewhen calling SQLExecute().

To retrieve a row from the result set generated by a SELECT statement, call SQLFetch() afterSQLExecute() returns successfully.

If the SQL statement is a positioned DELETE or a positioned UPDATE statement, the cursor referencedby the statement must be positioned on a row at the time SQLExecute() is called, and must be defined ona separate statement handle under the same connection handle.


SQLExecute


v SQL_NEED_DATA

SQL_NO_DATA_FOUND is returned if the SQL statement is a Searched UPDATE or Searched DELETEand no rows satisfy the search condition.

Diagnostics

The SQLSTATEs for SQLExecute() include all those for SQLExecDirect() (see Table 53 on page 103) exceptfor HY009, and with the addition of the SQLSTATEs in the following table.

Table 55. SQLExecute SQLSTATEs


HY009 Statement option is notvalid

Attributes associated with the statement being executedare not valid.

HY010 Function sequence error The specified hstmt is not in prepared state. SQLExecute()is called without first calling SQLPrepare.



Note: There are many other SQLSTATE values that can be generated by the Database Management System (DBMS),on processing of the statement.

Example

Refer to the example in “SQLPrepare - Prepare a statement” on page 200

Referencesv “SQLExecDirect - Execute a statement directly” on page 102v “SQLBindCol - Bind a column to an application variable” on page 36v “SQLPrepare - Prepare a statement” on page 200v “SQLFetch - Fetch next row” on page 108v “SQLSetParam - Set parameter” on page 246

SQLExecute


SQLExtendedFetch - Fetch array of rowsSQLExtendedFetch() extends the function of SQLFetch() by returning a block of data that containsmultiple rows (called a rowset) in the form of an array, for each bound column. The size of the rowset isdetermined by the SQL_ROWSET_SIZE attribute on an SQLSetStmtAttr() call.

To fetch one row of data at a time, an application should call SQLFetch().

SyntaxSQLRETURN SQLExtendedFetch (SQLHSTMT StatementHandle,

SQLSMALLINT FetchOrientation,SQLINTEGER FetchOffset,SQLINTEGER *RowCountPtr,SQLSMALLINT *RowStatusArray);

Function arguments

Table 56. SQLExtendedFetch arguments



SQLSMALLINT FetchOrientation Input Fetch orientation. See Table 61 on page 114 forpossible values.

SQLINTEGER FetchOffset Input Row offset for relative positioning.

SQLINTEGER * RowCountPtr Output Number of the rows actually fetched. If an erroroccurs during processing, RowCountPtr points to theordinal position of the row (in the rowset) thatprecedes the row where the error occurred. If anerror occurs retrieving the first row RowCountPtrpoints to the value 0.

SQLSMALLINT * RowStatusArray Output An array of status values. The number of elementsmust equal the number of rows in the rowset (asdefined by the SQL_ROWSET_SIZE attribute). Astatus value for each row fetched is returned:

v SQL_ROW_SUCCESS

If the number of rows fetched is less than thenumber of elements in the status array (that is, lessthan the rowset size), the remaining status elementsare set to SQL_ROW_NOROW.

Db2 for i CLI cannot detect whether a row has beenupdated or deleted since the start of the fetch.Therefore, the following ODBC defined status valuesare not reported:

v SQL_ROW_DELETED

v SQL_ROW_UPDATED

Usage

SQLExtendedFetch() is used to perform an array fetch of a set of rows. An application specifies the size ofthe array by calling SQLSetStmtAttr() with the SQL_ROWSET_SIZE attribute.

Before SQLExtendedFetch() is called the first time, the cursor is positioned before the first row. AfterSQLExtendedFetch() is called, the cursor is positioned on the row in the result set corresponding to thelast row element in the rowset just retrieved.

SQLExtendedFetch


For any columns in the result set that have been bound by the SQLBindCol() function, Db2 for i CLIconverts the data for the bound columns as necessary and stores it in the locations bound to thesecolumns. The result set must be bound in a row-wise fashion. This means that the values for all thecolumns of the first row are contiguous, followed by the values of the second row, and so on. Also, ifindicator variables are used, they are all returned in one contiguous storage location.

When using this procedure to retrieve multiple rows, all columns must be bound, and the storage mustbe contiguous. When using this function to retrieve rows from an SQL procedure result set, only theSQL_FETCH_NEXT orientation is supported. The user is responsible for allocating enough storage for thenumber of rows that are specified in SQL_ROWSET_SIZE.

The cursor must be a scrollable cursor for SQLExtendedFetch() to use any orientation other thanSQL_FETCH_NEXT. See “SQLSetStmtAttr - Set a statement attribute” on page 247 for information aboutsetting the SQL_ATTR_CURSOR_SCROLLABLE attribute.


Error conditions

Table 57. SQLExtendedFetch SQLSTATEs


HY009 Argument value that is not validThe argument value RowCountPtr or RowStatusArray is a nullpointer.

The value specified for the argument FetchOrientation is notrecognized.

HY010 Function sequence error SQLExtendedFetch() is called for an StatementHandle afterSQLFetch() is called and before SQLFreeStmt() has been calledwith the SQL_CLOSE option.

The function is called before calling SQLPrepare() orSQLExecDirect() for the StatementHandle.

The function is called while in a data-at-processing(SQLParamData(), SQLPutData()) operation.



Restrictions

None.

Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLExecute - Execute a statement” on page 104v “SQLExecDirect - Execute a statement directly” on page 102v “SQLFetch - Fetch next row” on page 108

SQLExtendedFetch


SQLFetch - Fetch next rowSQLFetch() advances the cursor to the next row of the result set, and retrieves any bound columns.

SQLFetch() can be used to receive the data directly into variables that you specify with SQLBindCol(), orthe columns can be received individually after the fetch by calling SQLGetData(). Data conversion is alsoperformed when SQLFetch() is called, if conversion is indicated when the column is bound.

SyntaxSQLRETURN SQLFetch (SQLHSTMT hstmt);

Function arguments

Table 58. SQLFetch arguments

Data type argument Use Description


Usage

SQLFetch() can only be called if the most recently processed statement on hstmt is a SELECT.

The number of application variables bound with SQLBindCol() must not exceed the number of columnsin the result set; otherwise SQLFetch() fails.

If SQLBindCol() has not been called to bind any columns, then SQLFetch() does not return data to theapplication, but just advances the cursor. In this case SQLGetData() can then be called to obtain all of thecolumns individually. Data in unbound columns is discarded when SQLFetch() advances the cursor to thenext row.

If any bound variables are not large enough to hold the data returned by SQLFetch(), the data istruncated. If character data is truncated, and the SQLSetEnvAttr() attributeSQL_ATTR_TRUNCATION_RTNC is set to SQL_TRUE, then the CLI return codeSQL_SUCCESS_WITH_INFO is returned, along with an SQLSTATE that indicates truncation. Note thatthe default is SQL_FALSE for SQL_ATTR_TRUNCATION_RTNC. Also, in the case of character datatruncation, the SQLBindCol() deferred output argument pcbValue contains the actual length of the columndata retrieved from the data source. The application should compare the output length to the inputlength (pcbValue and cbValueMax arguments from SQLBindCol()) to determine which character columnshave been truncated.

Truncation of numeric data types is not reported if the truncation involves digits to the right of thedecimal point. If truncation occurs to the left of the decimal point, an error is returned (refer to thediagnostics section).

Truncation of graphic data types is treated the same as character data types. Except the rgbValue buffer isfilled to the nearest multiple of two bytes that is still less than or equal to the cbValueMax specified inSQLBindCol(). Graphic data transferred between Db2 for i CLI and the application is nevernull-terminated.

When all the rows have been retrieved from the result set, or the remaining rows are not needed,SQLFreeStmt() should be called to close the cursor and discard the remaining data and associatedresources.

Return codesv SQL_SUCCESSv SQL_SUCCESS_WITH_INFO

SQLFetch


v SQL_ERRORv SQL_INVALID_HANDLEv SQL_NO_DATA_FOUND

SQL_NO_DATA_FOUND is returned if there are no rows in the result set, or previous SQLFetch() callshave fetched all the rows from the result set.

Diagnostics

Table 59. SQLFetch SQLSTATEs


01004 Data truncated The data returned for one or more columns is truncated.String values are right truncated.(SQL_SUCCESS_WITH_INFO is returned if no erroroccurred.)


HY010 Function sequence error The specified hstmt is not in an processed state. Thefunction is called without first calling SQLExecute orSQLExecDirect.





Example

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./*************************************************************************** file = fetch.c**** Example of executing an SQL statement.** SQLBindCol & SQLFetch is used to retrieve data from the result set** directly into application storage.**** Functions used:**** SQLAllocConnect SQLFreeConnect** SQLAllocEnv SQLFreeEnv** SQLAllocStmt SQLFreeStmt** SQLConnect SQLDisconnect**** SQLBindCol SQLFetch** SQLTransact SQLExecDirect** SQLError****************************************************************************/

#include <stdio.h>#include <string.h>#include "sqlcli.h"

#define MAX_STMT_LEN 255

int initialize(SQLHENV *henv,SQLHDBC *hdbc);

SQLFetch


int terminate(SQLHENV henv,SQLHDBC hdbc);

int print_error (SQLHENV henv,SQLHDBC hdbc,SQLHSTMT hstmt);

int check_error (SQLHENV henv,SQLHDBC hdbc,SQLHSTMT hstmt,SQLRETURN frc);

/********************************************************************* main** - initialize** - terminate*******************************************************************/int main(){

SQLHENV henv;SQLHDBC hdbc;SQLCHAR sqlstmt[MAX_STMT_LEN + 1]="";SQLRETURN rc;

rc = initialize(&henv, &hdbc);if (rc == SQL_ERROR) return(terminate(henv, hdbc));

{SQLHSTMT hstmt;SQLCHAR sqlstmt[]="SELECT deptname, location from org where division = ’Eastern’";SQLCHAR deptname[15],

location[14];SQLINTEGER rlength;

rc = SQLAllocStmt(hdbc, &hstmt);if (rc != SQL_SUCCESS )

check_error (henv, hdbc, SQL_NULL_HSTMT, rc);

rc = SQLExecDirect(hstmt, sqlstmt, SQL_NTS);if (rc != SQL_SUCCESS )

check_error (henv, hdbc, hstmt, rc);

rc = SQLBindCol(hstmt, 1, SQL_CHAR, (SQLPOINTER) deptname, 15,&rlength);

if (rc != SQL_SUCCESS )check_error (henv, hdbc, hstmt, rc);

rc = SQLBindCol(hstmt, 2, SQL_CHAR, (SQLPOINTER) location, 14,&rlength);

if (rc != SQL_SUCCESS )check_error (henv, hdbc, hstmt, rc);

printf("Departments in Eastern division:\n");printf("DEPTNAME Location\n");printf("-------------- -------------\n");

while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS){

printf("%-14.14s %-13.13s \n", deptname, location);}if (rc != SQL_NO_DATA_FOUND )


rc = SQLFreeStmt(hstmt, SQL_DROP);if (rc != SQL_SUCCESS )

check_error (henv, hdbc, SQL_NULL_HSTMT, rc);}

SQLFetch


rc = SQLTransact(henv, hdbc, SQL_COMMIT);if (rc != SQL_SUCCESS )


terminate(henv, hdbc);return (0);

}/* end main */

/********************************************************************* initialize** - allocate environment handle** - allocate connection handle** - prompt for server, user id, & password** - connect to server*******************************************************************/


{SQLCHAR server[SQL_MAX_DSN_LENGTH],

uid[30],pwd[30];

SQLRETURN rc;

rc = SQLAllocEnv (henv); /* allocate an environment handle */if (rc != SQL_SUCCESS )


rc = SQLAllocConnect (*henv, hdbc); /* allocate a connection handle */if (rc != SQL_SUCCESS )







}

return(SQL_SUCCESS);}/* end initialize */

/********************************************************************* terminate** - disconnect** - free connection handle** - free environment handle*******************************************************************/int terminate(SQLHENV henv,

SQLHDBC hdbc){SQLRETURN rc;

rc = SQLDisconnect (hdbc); /* disconnect from database */if (rc != SQL_SUCCESS )

SQLFetch


print_error (henv, hdbc, SQL_NULL_HSTMT);rc = SQLFreeConnect (hdbc); /* free connection handle */if (rc != SQL_SUCCESS )

print_error (henv, hdbc, SQL_NULL_HSTMT);rc = SQLFreeEnv (henv); /* free environment handle */if (rc != SQL_SUCCESS )

print_error (henv, hdbc, SQL_NULL_HSTMT);

return(rc);}/* end terminate */

/********************************************************************* - print_error - call SQLError(), display SQLSTATE and message*******************************************************************/

int print_error (SQLHENV henv,SQLHDBC hdbc,SQLHSTMT hstmt)




};

return ( SQL_ERROR);} /* end print_error */

/********************************************************************* - check_error - call print_error(), checks severity of return code*******************************************************************/int check_error (SQLHENV henv,


{SQLRETURN rc;





printf("Rollback Successful, Exiting application\n");terminate(henv, hdbc);exit(frc);break;


case SQL_NO_DATA_FOUND :printf("\n ** No Data Found ** \n");

SQLFetch


break;default :

printf("\n ** Invalid Return Code ** \n");printf(" ** Attempting to rollback transaction **\n");SQLTransact(henv, hdbc, SQL_ROLLBACK);terminate(henv, hdbc);exit(frc);break;


} /* end check_error */

Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLExecute - Execute a statement” on page 104v “SQLExecDirect - Execute a statement directly” on page 102v “SQLGetCol - Retrieve one column of a row of the result set” on page 126v “SQLFetchScroll - Fetch from a scrollable cursor” on page 114

SQLFetch


SQLFetchScroll - Fetch from a scrollable cursorSQLFetchScroll() positions the cursor based on the requested orientation and then retrieves any boundcolumns.

SQLFetchScroll() can be used to receive the data directly into variables that you specify withSQLBindCol(), or the columns can be received individually after the fetch by calling SQLGetData(). Dataconversion is also performed when SQLFetchScroll() is called, if conversion is indicated when thecolumn is bound.

SyntaxSQLRETURN SQLFetchScroll (SQLHSTMT hstmt,

SQLSMALLINT fOrient,SQLINTEGER fOffset);

Function arguments

Table 60. SQLFetchScroll arguments



SQLSMALLINT fOrient Input Fetch orientation. See Table 61 for possiblevalues.

SQLINTEGER fOffset Input Row offset for relative positioning.

Usage

SQLFetchScroll() can only be called if the most recently processed statement on hstmt is a SELECT.

SQLFetchScroll() acts like SQLFetch(), except the fOrient parameter positions the cursor before any datais retrieved. The cursor must be a scrollable cursor for SQLFetchScroll() to use any orientation otherthan SQL_FETCH_NEXT.

When using this function to retrieve rows from an SQL procedure result set, only the SQL_FETCH_NEXTorientation is supported.

SQLFetchScroll() supports array fetch, an alternative to the array fetch support provided bySQLExtendedFetch(). See the SQLExtendedFetch() topic for details on array fetch.

The information returned in the RowCountPtr and RowStatusArray parameters of SQLExtendedFetch() arehandled by SQLFetchScroll() as follows:v RowCountPtr: SQLFetchScroll() returns the number of rows fetched in the buffer pointed to by the

SQL_ATTR_ROWS_FETCHED_PTR statement attribute.v RowStatusArray: SQLFetchScroll() returns the array of statuses for each row in the buffer pointed to by

the SQL_ATTR_ROW_STATUS_PTR statement attribute.

Table 61. Statement attributes

fOrient Description

SQL_FETCH_ABSOLUTE Move to the result set row specified by the fOffsetargument.

SQL_FETCH_FIRST Move to the first row of the result set.

SQL_FETCH_LAST Move to the last row of the result set.

SQL_FETCH_NEXT Move to the row following the current cursor position.

SQL_FETCH_PRIOR Move to the row preceding the current cursor position.

SQLFetchScroll


Table 61. Statement attributes (continued)

fOrient Description

SQL_FETCH_RELATIVE If fOffset is:

v Positive, advance the cursor that number of rows.

v Negative, back up the cursor that number of rows.

v Zero, do not move the cursor.


Diagnostics

Table 62. SQLFetchScroll SQLSTATEs


01004 Data truncated The data returned for one or more columns is truncated.String values are right truncated.(SQL_SUCCESS_WITH_INFO is returned if no erroroccurred.)



Orientation that is not valid.

HY010 Function sequence error The specified hstmt is not in an processed state. Thefunction is called without first calling SQLExecute orSQLExecDirect.





Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLExecute - Execute a statement” on page 104v “SQLExecDirect - Execute a statement directly” on page 102v “SQLExtendedFetch - Fetch array of rows” on page 106v “SQLGetCol - Retrieve one column of a row of the result set” on page 126v “SQLFetch - Fetch next row” on page 108v “SQLSetStmtAttr - Set a statement attribute” on page 247

SQLFetchScroll


SQLForeignKeys - Get the list of foreign key columnsSQLForeignKeys() returns information about foreign keys for the specified table. The information isreturned in an SQL result set, which can be processed with the same functions that are used to retrieve aresult that is generated by a query.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLForeignKeysW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLForeignKeys (SQLHSTMT StatementHandle,

SQLCHAR *PKCatalogName,SQLSMALLINT NameLength1,SQLCHAR *PKSchemaName,SQLSMALLINT NameLength2,SQLCHAR *PKTableName,SQLSMALLINT NameLength3,SQLCHAR *FKCatalogName,SQLSMALLINT NameLength4,SQLCHAR *FKSchemaName,SQLSMALLINT NameLength5,SQLCHAR *FKTableName,SQLSMALLINT NameLength6);

Function arguments

Table 63. SQLForeignKeys arguments



SQLCHAR * PKCatalogName Input Catalog qualifier of the primary key table. This mustbe a NULL pointer or a zero length string.

SQLSMALLINT NameLength1 Input Length of PKCatalogName. This must be set to 0.

SQLCHAR * PKSchemaName Input Schema qualifier of the primary key table.

SQLSMALLINT NameLength2 Input Length of PKSchemaName.

SQLCHAR * PKTableName Input Name of the table name containing the primary key.

SQLSMALLINT NameLength3 Input Length of PKTableName.

SQLCHAR * FKCatalogName Input Catalog qualifier of the table containing the foreignkey. This must be a NULL pointer or a zero lengthstring.

SQLSMALLINT NameLength4 Input Length of FKCatalogName. This must be set to 0.

SQLCHAR * FKSchemaName Input Schema qualifier of the table containing the foreignkey.

SQLSMALLINT NameLength5 Input Length of FKSchemaName.

SQLCHAR * FKTableName Input Name of the table containing the foreign key.

SQLSMALLINT NameLength6 Input Length of FKTableName.

Usage

If PKTableName contains a table name, and FKTableName is an empty string, SQLForeignKeys() returns aresult set that contains the primary key of the specified table and all of the foreign keys (in other tables)that refer to it.

SQLForeignKeys


If FKTableName contains a table name, and PKTableName is an empty string, SQLForeignKeys() returns aresult set that contains all of the foreign keys in the specified table and the primary keys (in other tables)to which they refer.

If both PKTableName and FKTableName contain table names, SQLForeignKeys() returns the foreign keys inthe table specified in FKTableName that refer to the primary key of the table specified in PKTableName.This should be one key at the most.

If the schema qualifier argument that is associated with a table name is not specified, then for the schemaname the default is the one currently in effect for the current connection.

Table 64 lists the columns of the result set generated by the SQLForeignKeys() call. If the foreign keys thatare associated with a primary key are requested, the result set is ordered by FKTABLE_CAT,FKTABLE_SCHEM, FKTABLE_NAME, and ORDINAL_POSITION. If the primary keys that are associatedwith a foreign key are requested, the result set is ordered by PKTABLE_CAT, PKTABLE_SCHEM,PKTABLE_NAME, and ORDINAL_POSITION.

Although new columns might be added and the names of the existing columns might be changed infuture releases, the position of the current columns does not change.

Table 64. Columns returned by SQLForeignKeys


1 PKTABLE_CAT VARCHAR(128) The current server.

2 PKTABLE_SCHEM VARCHAR(128) The name of the schema containing PKTABLE_NAME.

3 PKTABLE_NAME VARCHAR(128)not NULL

Name of the table containing the primary key.

4 PKCOLUMN_NAME VARCHAR(128)not NULL

Primary key column name.

5 FKTABLE_CAT VARCHAR(128) The current server.

6 FKTABLE_SCHEM VARCHAR(128) The name of the schema containing FKTABLE_NAME.

7 FKTABLE_NAME VARCHAR(128)not NULL

The name of the table containing the Foreign key.

8 FKCOLUMN_NAME VARCHAR(128)not NULL

Foreign key column name.

9 KEY_SEQ SMALLINT notNULL

The ordinal position of the column in the key, starting at 1.

10 UPDATE_RULE SMALLINT Action to be applied to the foreign key when the SQL operation isUPDATE:

v SQL_RESTRICT

v SQL_NO_ACTION

The update rule for IBM DB2 DBMSs is always either RESTRICT orSQL_NO_ACTION. However, ODBC applications might encounterthe following UPDATE_RULE values when connected to non-IBMRDBMSs:

v SQL_CASCADE

v SQL_SET_NULL

SQLForeignKeys


Table 64. Columns returned by SQLForeignKeys (continued)


11 DELETE_RULE SMALLINT Action to be applied to the foreign key when the SQL operation isDELETE:

v SQL_CASCADE

v SQL_NO_ACTION

v SQL_RESTRICT

v SQL_SET_DEFAULT

v SQL_SET_NULL

12 FK_NAME VARCHAR(128) Foreign key identifier. NULL if not applicable to the data source.

13 PK_NAME VARCHAR(128) Primary key identifier. NULL if not applicable to the data source.

14 DEFERRABILITY SMALLINT One of:

v SQL_INITIALLY_DEFERRED

v SQL_INITIALLY_IMMEDIATE

v SQL_NOT_DEFERRABLE

Note: The column names used by Db2 for i CLI follow the X/Open CLI CAE specification style. The column types,contents and order are identical to those defined for the SQLForeignKeys() result set in ODBC.


Diagnostics

Table 65. SQLForeignKeys SQLSTATEs


24000 Cursor state that is not valid A cursor is already opened on the statement handle.



HY009 Argument value that is not valid The arguments PKTableName and FKTableName were both NULLpointers.

HY010 Function sequence error

HY014 No more handles Db2 for i CLI is unable to allocate a handle due to internalresources.




The value of one of the name length arguments is less than 0, butnot equal to SQL_NTS.

The length of the table or owner name is greater than themaximum length supported by the data source. Refer to“SQLGetInfo - Get general information” on page 155.

HYC00 Driver not capable Db2 for i CLI does not support catalog as a qualifier for tablename.

SQLForeignKeys


Table 65. SQLForeignKeys SQLSTATEs (continued)


HYT00 Timeout expired

Restrictions

None.

Example

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./* From CLI sample browser.c *//* ... */SQLRETURN list_foreign_keys( SQLHANDLE hstmt,

SQLCHAR * schema,SQLCHAR * tablename

) {

/* ... */rc = SQLForeignKeys(hstmt, NULL, 0,

schema, SQL_NTS, tablename, SQL_NTS,NULL, 0,NULL, SQL_NTS, NULL, SQL_NTS);

CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;

rc = SQLBindCol(hstmt, 2, SQL_C_CHAR, (SQLPOINTER) pktable_schem.s, 129,&pktable_schem.ind);


rc = SQLBindCol(hstmt, 3, SQL_C_CHAR, (SQLPOINTER) pktable_name.s, 129,&pktable_name.ind);


rc = SQLBindCol(hstmt, 4, SQL_C_CHAR, (SQLPOINTER) pkcolumn_name.s, 129,&pkcolumn_name.ind);


rc = SQLBindCol(hstmt, 6, SQL_C_CHAR, (SQLPOINTER) fktable_schem.s, 129,&fktable_schem.ind);


rc = SQLBindCol(hstmt, 7, SQL_C_CHAR, (SQLPOINTER) fktable_name.s, 129,&fktable_name.ind);


rc = SQLBindCol(hstmt, 8, SQL_C_CHAR, (SQLPOINTER) fkcolumn_name.s, 129,&fkcolumn_name.ind);


rc = SQLBindCol(hstmt, 10, SQL_C_SHORT, (SQLPOINTER) &update_rule,0, &update_ind);


rc = SQLBindCol(hstmt, 11, SQL_C_SHORT, (SQLPOINTER) &delete_rule,0, &delete_ind);


rc = SQLBindCol(hstmt, 12, SQL_C_CHAR, (SQLPOINTER) fkey_name.s, 129,&fkey_name.ind);


SQLForeignKeys


rc = SQLBindCol(hstmt, 13, SQL_C_CHAR, (SQLPOINTER) pkey_name.s, 129,&pkey_name.ind);


printf("Primary Key and Foreign Keys for %s.%s\n", schema, tablename);/* Fetch each row, and display */while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS) {

printf(" %s %s.%s.%s\n Update Rule ",pkcolumn_name.s, fktable_schem.s, fktable_name.s, fkcolumn_name.s);

if (update_rule == SQL_RESTRICT) {printf("RESTRICT "); /* always for IBM DBMSs */

} else {if (update_rule == SQL_CASCADE) {

printf("CASCADE "); /* non-IBM only */} else {

printf("SET NULL ");}

}printf(", Delete Rule: ");if (delete_rule== SQL_RESTRICT) {

printf("RESTRICT "); /* always for IBM DBMSs */} else {

if (delete_rule == SQL_CASCADE) {printf("CASCADE "); /* non-IBM only */

} else {if (delete_rule == SQL_NO_ACTION) {

printf("NO ACTION "); /* non-IBM only */} else {

printf("SET NULL ");}

}}printf("\n");if (pkey_name.ind > 0 ) {

printf(" Primary Key Name: %s\n", pkey_name.s);}if (fkey_name.ind > 0 ) {

printf(" Foreign Key Name: %s\n", fkey_name.s);}

}

Referencesv “SQLPrimaryKeys - Get primary key columns of a table” on page 204v “SQLStatistics - Get index and statistics information for a base table” on page 259

SQLForeignKeys


SQLFreeConnect - Free connection handleSQLFreeConnect() invalidates and frees the connection handle. All Db2 for i CLI resources associated withthe connection handle are freed.

SQLDisconnect() must be called before calling this function.

Either SQLFreeEnv() is called next to continue ending the application, or SQLAllocHandle() is called toallocate a new connection handle.

SyntaxSQLRETURN SQLFreeConnect (SQLHDBC hdbc);

Function arguments

Table 66. SQLFreeConnect arguments



Usage

If this function is called when a connection still exists, SQL_ERROR is returned, and the connectionhandle remains valid.


Diagnostics

Table 67. SQLFreeConnect SQLSTATEs




HY010 Function sequence error The function is called before SQLDisconnect() for thehdbc.



Example


Referencesv “SQLDisconnect - Disconnect from a data source” on page 91v “SQLFreeEnv - Free environment handle” on page 122

SQLFreeConnect


SQLFreeEnv - Free environment handleSQLFreeEnv() invalidates and frees the environment handle. All Db2 for i CLI resources associated withthe environment handle are freed.

SQLFreeConnect() must be called before calling this function.

This function is the last Db2 for i CLI step that an application needs before it ends.

SyntaxSQLRETURN SQLFreeEnv (SQLHENV henv);

Function arguments

Table 68. SQLFreeEnv arguments


SQLHENV henv Input Environment handle

Usage

If this function is called when there is still a valid connection handle, SQL_ERROR is returned, and theenvironment handle remains valid.


Diagnostics

Table 69. SQLFreeEnv SQLSTATEs




HY010 Function sequence error There is an hdbc which is in allocated or connected state.Call SQLDisconnect and SQLFreeConnect for the hdbcbefore calling SQLFreeEnv.



Example


References

“SQLFreeConnect - Free connection handle” on page 121

SQLFreeEnv


SQLFreeHandle - Free a handleSQLFreeHandle() invalidates and frees a handle.

SyntaxSQLRETURN SQLFreeHandle (SQLSMALLINT htype,

SQLINTEGER handle);

Function arguments

Table 70. SQLFreeHandle arguments


SQLSMALLINT hType Input Handle type that must beSQL_HANDLE_ENV, SQL_HANDLE_DBC,SQL_HANDLE_STMT, orSQL_HANDLE_DESC.

SQLINTEGER handle Input The handle to be freed.

Usage

SQLFreeHandle() combines the function of SQLFreeEnv(), SQLFreeConnect(), and SQLFreeStmt().


Diagnostics

Table 71. SQLFreeHandle SQLSTATEs




HY010 Function sequence error There is an hdbc which is in allocated or connected state.Call SQLDisconnect and SQLFreeConnect for the hdbcbefore calling SQLFreeHandle.



Referencesv “SQLFreeConnect - Free connection handle” on page 121v “SQLFreeEnv - Free environment handle” on page 122v “SQLFreeStmt - Free (or reset) a statement handle” on page 124

SQLFreeHandle


SQLFreeStmt - Free (or reset) a statement handleSQLFreeStmt() ends processing on the statement that is referenced by the statement handle.

You can use this function to complete the following tasks:v Close a cursor.v Reset parameters.v Unbind columns from variables.v Drop the statement handle and free the Db2 for i CLI resources associated with the statement handle.

SQLFreeStmt() is called after executing an SQL statement and processing the results.

SyntaxSQLRETURN SQLFreeStmt (SQLHSTMT hstmt,

SQLSMALLINT fOption);

Function arguments

Table 72. SQLFreeStmt arguments



SQLSMALLINT fOption Input Option specifying the manner of freeing thestatement handle. The option must have oneof the following values:

v SQL_CLOSE

v SQL_DROP

v SQL_UNBIND

v SQL_RESET_PARAMS

Usage

SQLFreeStmt() can be called with the following options:v SQL_CLOSE

The cursor (if any) associated with the statement handle (hstmt) is closed and all pending results arediscarded. The application can reopen the cursor by calling SQLExecute() with the same or differentvalues in the application variables (if any) that are bound to hstmt. The cursor name is retained untilthe statement handle is dropped or the next successful SQLSetCursorName() call. If no cursor has beenassociated with the statement handle, this option has no effect (no warning or error is generated).

v SQL_DROPDb2 for i CLI resources associated with the input statement handle are freed, and the handle isinvalidated. The open cursor, if any, is closed and all pending results are discarded.

v SQL_UNBINDAll the columns bound by previous SQLBindCol() calls on this statement handle are released (theassociation between application variables or file references and result set columns is broken).

v SQL_RESET_PARAMSAll the parameters set by previous SQLBindParam() calls on this statement handle are released. Theassociation between application variables or file references and parameter markers in the SQLstatement of the statement handle is broken.

To reuse a statement handle to run a different statement and if the previous statement:v Was a SELECT, you must close the cursor.

SQLFreeStmt


v Used a different number or type of parameters, the parameters must be reset.v Used a different number or type of column bindings, the columns must be unbound.

Alternatively you can drop the statement handle and allocate a new one.

Return codesv SQL_SUCCESSv SQL_SUCCESS_WITH_INFOv SQL_ERRORv SQL_IN_HANDLE

SQL_SUCCESS_WITH_INFO is not returned if fOption is set to SQL_DROP, because there is no statementhandle to use when SQLError() is called.

Diagnostics

Table 73. SQLFreeStmt SQLSTATEs







The value specified for the argument fOption is notSQL_CLOSE, SQL_DROP, SQL_UNBIND, orSQL_RESET_PARAMS.



Example


Referencesv “SQLAllocStmt - Allocate a statement handle” on page 34v “SQLBindCol - Bind a column to an application variable” on page 36v “SQLFetch - Fetch next row” on page 108v “SQLFreeConnect - Free connection handle” on page 121v “SQLSetParam - Set parameter” on page 246

SQLFreeStmt


SQLGetCol - Retrieve one column of a row of the result setSQLGetCol() retrieves data for a single column in the current row of the result set. This is an alternativeto SQLBindCol(), which transfers data directly into application variables on a call to SQLFetch().SQLGetCol() is also used to retrieve large character-based data in pieces.

SQLFetch() must be called before SQLGetCol().

After calling SQLGetCol() for each column, SQLFetch() is called to retrieve the next row.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetColW(). Refer to “Unicode in Db2 for i CLI” on page 307 formore information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetCol (SQLHSTMT hstmt,


Function arguments

Table 74. SQLGetCol arguments



SQLSMALLINT icol Input Column number for which the data retrievalis requested.

SQLSMALLINT fCType Input Application data type of the columnidentified by icol. The following types aresupported:

v SQL_BIGINT

v SQL_BINARY

v SQL_BLOB

v SQL_CHAR

v SQL_CLOB

v SQL_DATETIME

v SQL_DBCLOB

v SQL_DECFLOAT

v SQL_DECIMAL

v SQL_DOUBLE

v SQL_FLOAT

v SQL_GRAPHIC

v SQL_INTEGER

v SQL_NUMERIC

v SQL_REAL

v SQL_SMALLINT

v SQL_TYPE_DATE

v SQL_TYPE_TIME


v SQL_VARBINARY

v SQL_VARGRAPHIC

SQLGetCol


Table 74. SQLGetCol arguments (continued)


SQLPOINTER rgbValue Output Pointer to buffer where the retrieved columndata is to be stored.

SQLINTEGER cbValueMax Input Maximum size of the buffer pointed to byrgbValue. If fcType is either SQL_DECIMAL orSQL_NUMERIC, cbValueMax must be aprecision and scale. The method to specifyboth values is to use (precision * 256) +scale. This is also the value returned as theLENGTH of these data types when usingSQLColAttribute().

SQLINTEGER * pcbValue Output Pointer to the value that indicates thenumber of bytes Db2 for i CLI has availableto return in the rgbValue buffer. If the data isbeing retrieved in pieces, this contains thenumber of bytes still remaining, excludingany bytes of the column's data that has beenobtained from previous calls to SQLGetCol().

The value is SQL_NULL_DATA if the datavalue of the column is null. If this pointer isNULL and SQLFetch() has obtained acolumn containing null data, then thisfunction fails because it has no means ofreporting this.

If SQLFetch() has fetched a columncontaining graphic data, then the pointer topcbValue must not be NULL or this functionfails because it has no means of informingthe application about the length of the dataretrieved in the rgbValue buffer.

Usage

SQLGetCol() can be used with SQLBindCol() for the same row, as long as the value of icol does not specifya column that has been bound. The general steps are:1. SQLFetch() - advances cursor to first row, retrieves first row, transfers data for bound columns.2. SQLGetCol() - transfers data for specified (unbound) column.3. Repeat step 2 for each column needed.4. SQLFetch() - advances cursor to next row, retrieves next row, transfers data for bound columns.5. Repeat steps 2, 3 and 4 for each row in the result set, or until the result set is no longer needed.

SQLGetCol() retrieves long columns if the C data type (fCType) is SQL_CHAR or if fCType isSQL_DEFAULT and the column type is CHAR or VARCHAR.

On each SQLGetCol() call, if the data available for return is greater than or equal to cbValueMax,truncation occurs. A function return code of SQL_SUCCESS_WITH_INFO that is coupled with anSQLSTATE that denotes data truncation indicates truncation. The application can call SQLGetCol() again,with the same icol value, to obtain later data from the same unbound column starting at the point oftruncation. To obtain the entire column, the application repeats such calls until the function returnsSQL_SUCCESS. The next call to SQLGetCol() returns SQL_NO_DATA_FOUND.

SQLGetCol


To discard the column data part way through the retrieval, the application can call SQLGetCol() with icolset to the next column position of interest. To discard unretrieved data for the entire row, the applicationshould call SQLFetch() to advance the cursor to the next row; or, if it is not interested in any more datafrom the result set, call SQLFreeStmt() to close the cursor.

The fCType input argument determines the type of data conversion (if any) needed before the columndata is placed into the storage area pointed to by rgbValue.

The contents returned in rgbValue is always null-terminated unless SQLSetEnvAttr() is used to changethe SQL_ATTR_OUTPUT_NTS attribute or if the application is retrieving the data in multiple chunks. Ifthe application is retrieving the data in multiple chunks, the null-terminating byte is only added to thelast portion of data.

Truncation of numeric data types is not reported if the truncation involves digits to the right of thedecimal point. If truncation occurs to the left of the decimal point, an error is returned (refer to thediagnostics section).

For decimal floating point data types, a precision of 32, 64, or 128 can be specified by using the defaultsymbolic C data type constants. For example, to specify a decimal floating point data type with aprecision of 128 bytes, ValueType can be set to SQL_C_DECIMAL128.


SQL_NO_DATA_FOUND is returned when the preceding SQLGetCol() call has retrieved all of the datafor this column.

SQL_SUCCESS is returned if a zero-length string is retrieved by SQLGetCol(). If this is the case, pcbValuecontains 0, and rgbValue contains a null terminator.

If the preceding call to SQLFetch() fails, SQLGetCol() should not be called because the result is undefined.

Diagnostics

Table 75. SQLGetCol SQLSTATEs


07006 Restricted data typeattribute violation

The data value cannot be converted to the C data typespecified by the argument fCType.



The value of the argument cbValueMax is less than 1 andthe argument fCType is SQL_CHAR.

The specified column number is not valid.

The argument rgbValue or pcbValue is a null pointer.

HY010 Function sequence error The specified hstmt is not in a cursor positioned state.The function is called without first calling SQLFetch().



SQLGetCol


Table 75. SQLGetCol SQLSTATEs (continued)




HYC00 Driver not capable The SQL data type for the specified data type isrecognized but not supported by the driver.

The requested conversion from the SQL data type to theapplication data fCType cannot be performed by thedriver or the data source.

Restrictions

ODBC requires that icol not specify a column of a lower number than the column last retrieved bySQLGetCol() for the same row on the same statement handle. ODBC also does not permit the use ofSQLGetCol() to retrieve data for a column that resides before the last bound column, (if any columns inthe row have been bound).

Db2 for i CLI has relaxed both of these rules by allowing the value of icol to be specified in any orderand before a bound column, provided that icol does not specify a bound column.

Example

Refer to the example in the “SQLFetch - Fetch next row” on page 108 for a comparison between usingbound columns and using SQLGetCol().

Refer to “Example: Interactive SQL and the equivalent Db2 for i CLI function calls” on page 314 for alisting of the check_error, initialize, and terminate functions used in the following example.

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./*************************************************************************** file = getcol.c**** Example of directly executing an SQL statement.** Getcol is used to retrieve information from the result set.** Compare to fetch.c**** Functions used:**** SQLAllocConnect SQLFreeConnect** SQLAllocEnv SQLFreeEnv** SQLAllocStmt SQLFreeStmt** SQLConnect SQLDisconnect**** SQLBindCol SQLFetch** SQLTransact SQLError** SQLExecDirect SQLGetCursor**************************************************************************/

#include <stdio.h>#include <string.h>#include "sqlcli.h"



SQLGetCol







rc = initialize(&henv, &hdbc);if (rc != SQL_SUCCESS) return(terminate(henv, hdbc));

{SQLHSTMT hstmt;SQLCHAR sqlstmt[]="SELECT deptname, location from org where division = ’Eastern’";SQLCHAR deptname[15],

location[14];SQLINTEGER rlength;



rc = SQLExecDirect(hstmt, sqlstmt, SQL_NTS);if (rc != SQL_SUCCESS )


printf("Departments in Eastern division:\n");printf("DEPTNAME Location\n");printf("-------------- -------------\n");


rc = SQLGetCol(hstmt, 1, SQL_CHAR, (SQLPOINTER) deptname, 15, &rlength);rc = SQLGetCol(hstmt, 2, SQL_CHAR, (SQLPOINTER) location, 14, &rlength);printf("%-14.14s %-13.13s \n", deptname, location);

}if (rc != SQL_NO_DATA_FOUND )

check_error (henv, hdbc, hstmt, rc);}

rc = SQLTransact(henv, hdbc, SQL_COMMIT);if (rc != SQL_SUCCESS )


terminate(henv, hdbc);return (SQL_SUCCESS);

}/* end main */

SQLGetCol


Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLFetch - Fetch next row” on page 108

SQLGetCol


SQLGetConnectAttr - Get the value of a connection attributeSQLGetConnectAttr() returns the current settings for the specified connection option.

These options are set using the SQLSetConnectAttr() function.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetConnectAttrW(). Refer to “Unicode in Db2 for i CLI” on page307 for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetConnectAttr( SQLHDBC hdbc,

SQLINTEGER fAttr,SQLPOINTER pvParam),;SQLINTEGER bLen,SQLINTEGER *sLen);

Function arguments

Table 76. SQLGetConnectAttr arguments



SQLINTEGER fAttr Input Attribute to retrieve. See“SQLSetConnectAttr - Set a connectionattribute” on page 220 for a description ofthe connect options.

SQLPOINTER pvParam Output Value associated with fAttr Depending onthe value of fAttr. This can be a 32-bitinteger value, or a pointer to a nullterminated character string.

SQLINTEGER bLen Input Maximum number of bytes to store inpvParm, if the value is a character string;otherwise, unused.

SQLINTEGER * sLen Output Length of the output data, if the attribute isa character string; otherwise, unused.

Usage

Statement options settings cannot be retrieved through SQLGetConnectAttr().

Diagnostics

Table 77. SQLGetConnectAttr SQLSTATEs


08003 Connection not open An fAttr value that requires an open connection isspecified .


HY009 Attribute type out of range An fAttr value that is not valid is specified.

The argument pvParam is a null pointer.

HYC00 Driver not capable The fAttr argument is recognized, but is not supported.

SQLGetConnectAttr


SQLGetConnectOption - Return current setting of a connect optionSQLGetConnectOption() has been deprecated and replaced with SQLGetConnectAttr(). Although thisversion of Db2 for i CLI continues to support SQLGetConnectOption(), it is recommended that you beginusing SQLGetConnectAttr() in your Db2 for i CLI programs so that they conform to the latest standards.

SQLGetConnectOption() returns the current settings for the specified connection option.

These options are set using the SQLSetConnectOption() function.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetConnectOptionW(). Refer to “Unicode in Db2 for i CLI” on page307 for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetConnectOption( HDBC hdbc,

SQLSMALLINT fOption,SQLPOINTER pvParam);

Function arguments

Table 78. SQLGetConnectOption arguments

Data type argument Use Description

HDBC hdbc Input Connection handle.

SQLSMALLINT fOption Input Option to retrieve. Refer to Table 146 on page 220 formore information.

SQLPOINTER pvParam Output Value associated with fOption Depending on the value offOption, this can be a 32-bit integer value, or a pointer toa null terminated character string. The maximum lengthof any character string returned isSQL_MAX_OPTION_STRING_LENGTH bytes (excludingthe null-terminating byte).

Usage

SQLGetConnectOption() provides the same function as SQLGetConnectAttr(). Both functions are supportedfor compatibility reasons.

Statement options settings cannot be retrieved through SQLGetConnectOption().

Diagnostics

Table 79. SQLGetConnectOption SQLSTATEs


08003 Connection not open An fOption value that requires an open connection isspecified .


HY009 Option type out of range An fOption value that is not valid is specified.


HYC00 Driver not capable The fOption argument is recognized, but is notsupported.

SQLGetConnectOption


References

“SQLGetConnectAttr - Get the value of a connection attribute” on page 132

SQLGetConnectOption


SQLGetCursorName - Get cursor nameSQLGetCursorName() returns the cursor name associated with the input statement handle. If a cursor nameis explicitly set by calling SQLSetCursorName(), this name is returned; otherwise, an internally generatedname is returned.

Internally generated cursor names are always 18 bytes in length.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetCursorNameW(). Refer to “Unicode in Db2 for i CLI” on page307 for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetCursorName (SQLHSTMT hstmt,

SQLCHAR *szCursor,SQLSMALLINT cbCursorMax,SQLSMALLINT *pcbCursor);

Function arguments

Table 80. SQLGetCursorName arguments



SQLCHAR * szCursor Output Cursor name

SQLSMALLINT cbCursorMax Input Length of buffer szCursor

SQLSMALLINT * pcbCursor Output Amount of bytes available to return forszCursor

Usage

SQLGetCursorName() returns a cursor name if a name is set using SQLSetCursorName() or if a SELECTstatement is processed on the statement handle. If neither of these is true, then calling SQLGetCusorName()results in an error.

If a name is set explicitly using SQLSetCursorName(), this name is returned until the statement is dropped,or until another explicit name is set.

If an explicit name is not set, an implicit name is generated when a SELECT statement is processed, andthis name is returned. Implicit cursor names always begin with SQLCUR.

The generated cursor names of ODBC start with SQL_CUR and X/Open CLI generated cursor namesbegin with SQLCUR. Db2 for i CLI uses SQLCUR.


SQLGetCursorName


Diagnostics

Table 81. SQLGetCursorName SQLSTATEs


01004 Data truncated The cursor name returned in szCursor is longer than thevalue in cbCursorMax, and is truncated to cbCursorMax -1 bytes. The argument pcbCursor contains the length ofthe full cursor name available for return. The functionreturns SQL_SUCCESS_WITH_INFO.






The argument szCursor or pcbCursor is a null pointer.

The value specified for the argument cbCursorMax is lessthan 1.

HY010 Function sequence error The statement hstmt is not in execute state. CallSQLExecute(), SQLExecDirect() or SQLSetCursorName()before calling SQLGetCursorName().



HY015 No cursor name available. There is no open cursor on the hstmt and no cursor namehas been set with SQLSetCursorName(). The statementassociated with hstmt does not support the use of acursor.

Example


Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./*************************************************************************** file = getcurs.c**** Example of directly executing a SELECT and positioned UPDATE SQL statement.** Two statement handles are used, and SQLGetCursor is used to retrieve the** generated cursor name.**** Functions used:**** SQLAllocConnect SQLFreeConnect** SQLAllocEnv SQLFreeEnv** SQLAllocStmt SQLFreeStmt** SQLConnect SQLDisconnect**** SQLBindCol SQLFetch** SQLTransact SQLError** SQLExecDirect SQLGetCursorName**************************************************************************/#include <stdio.h>#include <string.h>#include <stdlib.h>#include "sqlcli.h"

SQLGetCursorName








SQLHENV henv;SQLHDBC hdbc;SQLRETURN rc,

rc2;

rc = initialize(&henv, &hdbc);if (rc != SQL_SUCCESS) return(terminate(henv, hdbc));

{SQLHSTMT hstmt1,hstmt2;

SQLCHAR sqlstmt[]="SELECT name, job from staff for update of job";SQLCHAR updstmt[MAX_STMT_LEN + 1];SQLCHAR name[10],

job[6],newjob[6],cursor[19];

SQLINTEGER rlength, attr;SQLSMALLINT clength;

rc = SQLAllocStmt(hdbc, &hstmt1);if (rc != SQL_SUCCESS )


/* make sure the statement is update-capable */attr = SQL_FALSE;rc = SQLSetStmtAttr(hstmt1,SQL_ATTR_FOR_FETCH_ONLY, &attr, 0);

/* allocate second statement handle for update statement */rc2 = SQLAllocStmt(hdbc, &hstmt2);if (rc2 != SQL_SUCCESS )


rc = SQLExecDirect(hstmt1, sqlstmt, SQL_NTS);if (rc != SQL_SUCCESS )

check_error (henv, hdbc, hstmt1, rc);

/* Get Cursor of the SELECT statement’s handle */rc = SQLGetCursorName(hstmt1, cursor, 19, &clength);if (rc != SQL_SUCCESS )


SQLGetCursorName


/* bind name to first column in the result set */rc = SQLBindCol(hstmt1, 1, SQL_CHAR, (SQLPOINTER) name, 10,

&rlength);if (rc != SQL_SUCCESS )


/* bind job to second column in the result set */rc = SQLBindCol(hstmt1, 2, SQL_CHAR, (SQLPOINTER) job, 6,



printf("Job Change for all clerks\n");

while ((rc = SQLFetch(hstmt1)) == SQL_SUCCESS){

printf("Name: %-9.9s Job: %-5.5s \n", name, job);printf("Enter new job or return to continue\n");gets(newjob);if (newjob[0] != ’\0’){

sprintf( updstmt,"UPDATE staff set job = ’%s’ where current of %s",newjob, cursor);

rc2 = SQLExecDirect(hstmt2, updstmt, SQL_NTS);if (rc2 != SQL_SUCCESS )

check_error (henv, hdbc, hstmt2, rc);}

}if (rc != SQL_NO_DATA_FOUND )

check_error (henv, hdbc, hstmt1, rc);SQLFreeStmt(hstmt1, SQL_CLOSE);

}

printf("Commiting Transaction\n");rc = SQLTransact(henv, hdbc, SQL_COMMIT);if (rc != SQL_NO_DATA_FOUND )



}/* end main */

Referencesv “SQLExecute - Execute a statement” on page 104v “SQLExecDirect - Execute a statement directly” on page 102v “SQLSetCursorName - Set cursor name” on page 235

SQLGetCursorName


SQLGetData - Get data from a columnSQLGetData() retrieves data for a single column in the current row of the result set. This is an alternativeto SQLBindCol(), which transfers data directly into application variables on a call to SQLFetch().SQLGetData() can also be used to retrieve large character-based data in pieces.

SQLFetch() must be called before SQLGetData().

After calling SQLGetData() for each column, SQLFetch() is called to retrieve the next row.

SQLGetData() is identical to SQLGetCol(). Both functions are supported for compatibility reasons.

SyntaxSQLRETURN SQLGetData (SQLHSTMT hstmt,


Note: Refer to “SQLGetCol - Retrieve one column of a row of the result set” on page 126 for adescription of the applicable sections.

SQLGetData


SQLGetDescField - Get descriptor fieldSQLGetDescField() obtains a value from a descriptor. SQLGetDescField() is a more extensible alternativeto the SQLGetDescRec() function.

This function is similar to that of SQLDescribeCol(), but SQLGetDescField() can retrieve data fromparameter descriptors as well as row descriptors.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetDescFieldW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetDescField (SQLHDESC hdesc,

SQLSMALLINT irec,SQLSMALLINT fDescType,SQLPOINTER rgbDesc,SQLINTEGER bLen,SQLINTEGER *sLen);

Function arguments

Table 82. SQLGetDescField arguments


SQLHDESC hdesc Input Descriptor handle.

SQLSMALLINT irec Input Indicates the descriptor record from whichthe application seeks information. Descriptorrecords are numbered from 1, with therecord number 1 being the first item in thedescriptor. If the fDescType argumentindicates a field of the descriptor headerrecord ( SQL_DESC_ALLOC_TYPE orSQL_DESC_COUNT), irec must be 0.

SQLSMALLINT fDescType Input Indicates the field of the descriptor whosevalue is to be returned. See Table 83.

SQLPOINTER rgbDesc Output Pointer to buffer.

SQLINTEGER bLen Input Length of descriptor buffer (rgbDesc).

SQLINTEGER * sLen Output Actual number of bytes in the descriptor toreturn. If this argument contains a valueequal to or higher than the length rgbDescbuffer, truncation occurs.

Table 83. fDescType descriptor types


SQL_DESC_ALLOC_TYPE SMALLINT Either SQL_DESC_ALLOC_USER ifthe application explicitly allocatedthe descriptor, orSQL_DESC_ALLOC_AUTO if theimplementation automaticallyallocated the descriptor.

SQL_DESC_COUNT SMALLINT The number of records in thedescriptor is returned in rgbDesc.

SQL_DESC_DATA_PTR SQLPOINTER Retrieve the data pointer field forirec.

SQLGetDescField


Table 83. fDescType descriptor types (continued)


SQL_DESC_DATETIME_INTERVAL_CODE SMALLINT Retrieve the interval code for recordswith a type of SQL_DATETIME. Theinterval code further defines theSQL_DATETIME data type. The codevalues are SQL_CODE_DATE,SQL_CODE_TIME, andSQL_CODE_TIMESTAMP.

SQL_DESC_INDICATOR_PTR SQLPOINTER Retrieve the indicator pointer fieldfor irec.

SQL_DESC_LENGTH_PTR SQLPOINTER Retrieve the length pointer field forirec.

SQL_DESC_LENGTH INTEGER Retrieve the LENGTH field of irec.

SQL_DESC_NAME CHAR(128) Retrieve the NAME field of irec.

SQL_DESC_NULLABLE SMALLINT If irec can contain nulls, thenSQL_NULLABLE is returned inrgbDesc. Otherwise,SQL_NO_NULLS is returned inrgbDesc.

SQL_DESC_PRECISION SMALLINT Retrieve the PRECISION field of irec.

SQL_DESC_SCALE SMALLINT Retrieve the SCALE field of irec.

SQL_DESC_TYPE SMALLINT Retrieve the TYPE field of irec.

SQL_DESC_UNNAMED SMALLINT This is SQL_NAMED if the NAMEfield is an actual name, orSQL_UNNAMED if the NAME fieldis an implementation-generatedname.

SQL_DESC_CCSID INTEGER Retrieve the CCSID value of irec

Usage

The number of records in the descriptor corresponds to the number of columns in the result set, if thedescriptor is row descriptor, or the number of parameters, for a parameter descriptor.

Calling SQLGetDescField() with fDescType set to SQL_DESC_COUNT is an alternative to callingSQLNumResultCols() to determine whether any columns can be returned.


SQLGetDescField


|||

Diagnostics

Table 84. SQLGetDescField SQLSTATEs



The value specified for the argument fDescType or irec isnot valid.

The argument rgbDesc or sLen is a null pointer.


The driver is unable to access the memory required tosupport the processing or completion of the function.




SQLGetDescField


SQLGetDescRec - Get descriptor recordSQLGetDescRec() obtains an entire record from a descriptor. SQLGetDescRec() is a more concise alternativeto the SQLGetDescField() function.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetDescRecW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetDescRec (SQLHDESC hdesc,

SQLSMALLINT irec,SQLCHAR *rgbDesc,SQLSMALLINT cbDescMax,SQLSMALLINT *pcbDesc,SQLSMALLINT *type,SQLSMALLINT *subtype,SQLINTEGER *length,SQLSMALLINT *prec,SQLSMALLINT *scale,SQLSMALLINT *nullable);

Function arguments

Table 85. SQLGetDescRec arguments



SQLSMALLINT irec Input Indicates the descriptor record from whichthe application seeks information. Descriptorrecords are numbered from 1, with therecord number 1 being the first item in thedescriptor. If the fDescType argumentindicates a field of the descriptor headerrecord ( SQL_DESC_ALLOC_TYPE orSQL_DESC_COUNT), irec must be 0.

SQLCHAR * rgbDesc Output NAME field for the record.

SQLSMALLINT cbDescMax Input Maximum number of bytes to store inrgbDesc.

SQLSMALLINT * pcbDesc Output Total length of the output data.

SQLSMALLINT * type Output TYPE field for the record.

SQLSMALLINT * subtype Output DATETIME_INTERVAL_CODE, for recordswhose TYPE is SQL_DATETIME.

SQLINTEGER * length Output LENGTH field for the record.

SQLSMALLINT * prec Output PRECISION field for the record.

SQLSMALLINT * scale Output SCALE field for the record.

SQLSMALLINT * nullable Output NULLABLE field for the record.

Usage

Calling SQLGetDescRec() retrieves all the data from a descriptor record in one call. It might still benecessary to call SQLGetDescField() with SQL_DESC_COUNT to determine the number of records in thedescriptor.

SQLGetDescRec



Diagnostics

Table 86. SQLGetDescRec SQLSTATEs



The value specified for the argument irec is not valid.

The argument rgbDesc, pcbDesc, type, subtype, length, prec,scale or nullable is a null pointer.






SQLGetDescRec


SQLGetDiagField - Return diagnostic information (extensible)SQLGetDiagField() returns the diagnostic information associated with the most recently called Db2 for iCLI function for a particular statement, connection, or environment handle.

The information consists of a standardized SQLSTATE, an error code, and a text message. Refer to“Diagnostics in a Db2 for i CLI application” on page 16 for more information.

Call SQLGetDiagField() after receiving a return code of SQL_ERROR or SQL_SUCCESS_WITH_INFOfrom another function call.

Note: Some database servers might provide product-specific diagnostic information after returningSQL_NO_DATA_FOUND from the processing of a statement.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetDiagFieldW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetDiagField (SQLSMALLINT htype,

SQLINTEGER handle,SQLSMALLINT recNum,SQLSMALLINT diagId,SQLPOINTER diagInfo,SQLSMALLINT bLen,SQLSMALLINT *sLen);

Function arguments

Table 87. SQLGetDiagField arguments


SQLSMALLINT hType Input Handle type.

SQLINTEGER handle Input Handle for which the diagnostic informationis wanted.

SQLSMALLINT recNum Input If there are multiple errors, this indicateswhich one should be retrieved. If headerinformation is requested, this must be 0. Thefirst error record is number 1.

SQLSMALLINT diagId Input See Table 88.

SQLPOINTER diagInfo Output Buffer for diagnostic information.

SQLSMALLINT bLen Input Length of diagInfo, if requested data is acharacter string; otherwise, unused.

SQLSMALLINT * sLen Output Length of complete diagnostic information, Ifthe requested data is a character string;otherwise, unused.

Table 88. diagId types


SQL_DIAG_MESSAGE_TEXT CHAR(254) The implementation-defined messagetext relating to the diagnostic record.

SQL_DIAG_NATIVE INTEGER The implementation-defined error coderelating to the diagnostic record.Portable applications should not basetheir behavior on this value.

SQLGetDiagField


Table 88. diagId types (continued)


SQL_DIAG_NUMBER INTEGER The number of diagnostic recordsavailable for the specified handle.

SQL_DIAG_RETURNCODE SMALLINT Return code of the underlying function.Can be SQL_SUCCESS,SQL_SUCCESS_WITH_INFO,SQL_NO_DATA_FOUND, orSQL_ERROR.

SQL_DIAG_ROW_COUNT INTEGER The number of rows for the specifiedhandle, if the handle is a statementhandle.

SQL_DIAG_SERVER_NAME CHAR(128) The server name that the diagnosticrecord relates to, as it is supplied onthe SQLConnect() statement thatestablishes the connection.

SQL_DIAG_SQLSTATE CHAR(5) The 5-character SQLSTATE coderelating to the diagnostic record. TheSQLSTATE code provides a portablediagnostic indication.

Usage

The SQLSTATEs are those defined by the X/OPEN SQL CAE and the X/Open SQL CLI snapshot,augmented with SQLSTATE values.

If diagnostic information generated by one Db2 for i CLI function is not retrieved before a function otherthan SQLGetDiagField() is called with the same handle, the information for the previous function call islost. This is true whether diagnostic information is generated for the second Db2 for i CLI function call.

Multiple diagnostic messages might be available after a given Db2 for i CLI function call. These messagescan be retrieved one at a time by repeatedly calling SQLGetDiagField(). When there are no moremessages to retrieve, SQL_NO_DATA_FOUND is returned.

Diagnostic information stored under a given handle is cleared when a call is made to SQLGetDiagField()with that handle, or when another Db2 for i CLI function call is made with that handle. However,information associated with a given handle type is not cleared by a call to SQLGetDiagField() with anassociated but different handle type. For example, a call to SQLGetDiagField() with a connection handleinput does not clear errors associated with any statement handles under that connection.

SQL_SUCCESS is returned even if the buffer for the error message (szDiagFieldMsg) is too short. This isbecause the application is not able to retrieve the same error message by calling SQLGetDiagField() again.The actual length of the message text is returned in the pcbDiagFieldMsg.


Return codesv SQL_SUCCESSv SQL_ERRORv SQL_INVALID_HANDLEv SQL_NO_DATA_FOUND

SQLGetDiagField


SQL_NO_DATA_FOUND is returned if no diagnostic information is available for the input handle, or ifall of the messages have been retrieved through calls to SQLGetDiagField().

SQL_ERROR is returned if the argument diagInfo or sLen is a null pointer.

Diagnostics

SQLSTATEs are not defined, because SQLGetDiagField() does not generate diagnostic information foritself.

Restrictions

Although ODBC also returns X/Open SQL CAE SQLSTATEs, only Db2 for i CLI returns the additionalIBM defined SQLSTATEs. The ODBC Driver Manager also returns SQLSTATE values in addition to thestandard ones. For more information about ODBC specific SQLSTATEs refer to Microsoft ODBCProgrammer's Reference.

Because of this, you should only build dependencies on the standard SQLSTATEs. This means anybranching logic in the application should only rely on the standard SQLSTATEs. The augmentedSQLSTATEs are most useful for debugging purposes.

SQLGetDiagField


SQLGetDiagRec - Return diagnostic information (concise)SQLGetDiagRec() returns the diagnostic information associated with the most recently called Db2 for i CLIfunction for a particular statement, connection, or environment handle.

The information consists of a standardized SQLSTATE, the error code, and a text message. See“Diagnostics in a Db2 for i CLI application” on page 16 for more information.

Call SQLGetDiagRec() after receiving a return code of SQL_ERROR or SQL_SUCCESS_WITH_INFO fromanother function call.

Note: Some database servers might provide product-specific diagnostic information after returningSQL_NO_DATA_FOUND from the processing of a statement.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetDiagRecW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetDiagRec (SQLSMALLINT hType,

SQLINTEGER handle,SQLSMALLINT recNum,SQLCHAR *szSqlState,SQLINTEGER *pfNativeError,SQLCHAR *szErrorMsg,SQLSMALLINT cbErrorMsgMax,SQLSMALLINT *pcbErrorMsg);

Function arguments

Table 89. SQLGetDiagRec arguments


SQLSMALLINT hType Input Handle type.

SQLINTEGER handle Input Handle for which the diagnostic informationis wanted.

SQLSMALLINT recNum Input If there are multiple errors, this indicateswhich one should be retrieved. If headerinformation is requested, this must be 0. Thefirst error record is number 1.

SQLCHAR * szSqlState Output SQLSTATE as a string of 5 charactersterminated by a null character. The first 2characters indicate error class; the next 3indicate subclass. The values corresponddirectly to SQLSTATE values defined in theX/Open SQL CAE specification and theODBC specification, augmented with IBMspecific and product specific SQLSTATEvalues.

SQLINTEGER * pfNativeError Output Error code. In Db2 for i CLI, the pfNativeErrorargument contains the SQLCODE valuereturned by the Database ManagementSystem (DBMS). If the error is generated byDb2 for i CLI and not the DBMS, then thisfield is set to -99999.

SQLGetDiagRec


Table 89. SQLGetDiagRec arguments (continued)


SQLCHAR * szErrorMsg Output Pointer to buffer to contain theimplementation defined message text. In Db2for i CLI, only the DBMS generated messagesare returned; Db2 for i CLI itself does notreturn any message text describing theproblem.

SQLSMALLINT cbErrorMsgMax Input Maximum (that is, the allocated) length ofthe buffer szErrorMsg. The recommendedlength to allocate isSQL_MAX_MESSAGE_LENGTH + 1.

SQLSMALLINT * pcbErrorMsg Output Pointer to total number of bytes available toreturn to the szErrorMsg buffer. This does notinclude the null termination character.

Usage

The SQLSTATEs are those defined by the X/OPEN SQL CAE and the X/Open SQL CLI snapshot,augmented with IBM specific and product specific SQLSTATE values.

If diagnostic information generated by one Db2 for i CLI function is not retrieved before a function otherthan SQLGetDiagRec() is called with the same handle, the information for the previous function call islost. This is true whether diagnostic information is generated for the second Db2 for i CLI function call.

Multiple diagnostic messages might be available after a given Db2 for i CLI function call. These messagescan be retrieved one at a time by repeatedly calling SQLGetDiagRec(). When there are no more messagesto retrieve, SQL_NO_DATA_FOUND is returned, the SQLSTATE is set to "00000", pfNativeError is set to 0,and pcbErrorMsg and szErrorMsg are undefined.

Diagnostic information stored under a given handle is cleared when a call is made to SQLGetDiagRec()with that handle, or when another Db2 for i CLI function call is made with that handle. However,information associated with a given handle type is not cleared by a call to SQLGetDiagRec() with anassociated but different handle type. For example, a call to SQLGetDiagRec() with a connection handleinput does not clear errors associated with any statement handles under that connection.

SQL_SUCCESS is returned even if the buffer for the error message (szErrorMsg) is too short, because theapplication is not able to retrieve the same error message by calling SQLGetDiagRec() again. The actuallength of the message text is returned in the pcbErrorMsg.


Return codesv SQL_SUCCESSv SQL_ERRORv SQL_INVALID_HANDLEv SQL_NO_DATA_FOUND

SQL_NO_DATA_FOUND is returned if no diagnostic information is available for the input handle, or ifall of the messages have been retrieved through calls to SQLGetDiagRec().

SQLGetDiagRec


SQL_ERROR is returned if the argument szSqlState, pfNativeError, szErrorMsg , or pcbErrorMsg is anull pointer.

Diagnostics

SQLSTATEs are not defined because SQLGetDiagRec() does not generate diagnostic information for itself.

Restrictions

Although ODBC also returns X/Open SQL CAE SQLSTATEs, only Db2 for i CLI returns the additionalIBM defined SQLSTATEs. The ODBC Driver Manager also returns SQLSTATE values in addition to thestandard ones. For more information about ODBC specific SQLSTATEs refer to Microsoft ODBCProgrammer's Reference.

Because of this, you should only build dependencies on the standard SQLSTATEs. This means anybranching logic in the application should only rely on the standard SQLSTATEs. The augmentedSQLSTATEs are most useful for debugging purposes.

References

“SQLGetDiagField - Return diagnostic information (extensible)” on page 145

SQLGetDiagRec


SQLGetEnvAttr - Return current setting of an environment attributeSQLGetEnvAttr() returns the current settings for the specified environment attribute.

These options are set using the SQLSetEnvAttr() function.

SyntaxSQLRETURN SQLGetEnvAttr (SQLHENV henv,

SQLINTEGER Attribute,SQLPOINTER Value,SQLINTEGER BufferLength,SQLINTEGER *StringLength);

Function arguments

Table 90. SQLGetEnvAttr arguments


SQLHENV henv Input Environment handle.

SQLINTEGER Attribute Input Attribute to retrieve. Refer to Table 158 onpage 241 for more information.

SQLPOINTER Value Output Current value associated with Attribute. Thetype of the value returned depends onAttribute.

SQLINTEGER BufferLength Input Maximum size of buffer pointed to by Value,if the attribute value is a character string;otherwise, unused.

SQLINTEGER * StringLength Output Length in bytes of the output data if theattribute value is a character string;otherwise, unused.

If Attribute does not denote a string, then Db2 for i CLI ignores BufferLength and does not setStringLength.

Usage

SQLGetEnvAttr() can be called at any time between the allocation and freeing of the environment handle.It obtains the current value of the environment attribute.

Diagnostics

Table 91. SQLGetEnvAttr SQLSTATEs



HY009 Attribute out of range An Attribute value that is not valid is specified.

The argument Value or StringLength is a null pointer.

SQLGetEnvAttr


SQLGetFunctions - Get functionsSQLGetFunctions() queries whether a specific function is supported. This allows applications to adapt tovarying levels of support when using different drivers.

SQLConnect() must be called, and a connection to the data source (database server) must exist beforecalling this function.

SyntaxSQLRETURN SQLGetFunctions (SQLHDBC hdbc,

SQLSMALLINT fFunction,SQLSMALLINT *pfSupported);

Function arguments

Table 92. SQLGetFunctions arguments


SQLHDBC hdbc Input Database connection handle.

SQLSMALLINT fFunction Input Function being queried.

SQLSMALLINT * pfSupported Output Pointer to location where this functionreturns SQL_TRUE or SQL_FALSEdepending on whether the function beingqueried is supported.

Usage

The following list shows the valid value for the fFunction argument and whether the correspondingfunction is supported.SQL_API_ALLOCCONNECT = TRUESQL_API_ALLOCENV = TRUESQL_API_ALLOCHANDLE = TRUESQL_API_ALLOCSTMT = TRUESQL_API_BINDCOL = TRUESQL_API_BINDFILETOCOL = TRUESQL_API_BINDFILETOPARAM = TRUESQL_API_BINDPARAM = TRUESQL_API_BINDPARAMETER = TRUESQL_API_CANCEL = TRUESQL_API_CLOSECURSOR = TRUESQL_API_COLATTRIBUTE = TRUESQL_API_COLATTRIBUTEW = TRUESQL_API_COLATTRIBUTES = TRUESQL_API_COLATTRIBUTESW = TRUESQL_API_COLUMNS = TRUESQL_API_COLUMNSW = TRUESQL_API_CONNECT = TRUESQL_API_CONNECTW = TRUESQL_API_COPYDESC = TRUESQL_API_DATASOURCES = TRUESQL_API_DATASOURCESW = TRUESQL_API_DESCRIBECOL = TRUESQL_API_DESCRIBECOLW = TRUESQL_API_DESCRIBEPARAM = TRUESQL_API_DISCONNECT = TRUESQL_API_DRIVERCONNECT = TRUESQL_API_DRIVERCONNECTW = TRUESQL_API_ENDTRAN = TRUESQL_API_ERROR = TRUESQL_API_ERRORW = TRUESQL_API_EXECDIRECT = TRUE

SQLGetFunctions


SQL_API_EXECDIRECTW = TRUESQL_API_EXECUTE = TRUESQL_API_EXTENDEDFETCH = TRUESQL_API_FETCH = TRUESQL_API_FOREIGNKEYS = TRUESQL_API_FOREIGNKEYSW = TRUESQL_API_FREECONNECT = TRUESQL_API_FREEENV = TRUESQL_API_FREEHANDLE = TRUESQL_API_FREESTMT = TRUESQL_API_GETCOL = TRUESQL_API_GETCONNECTATTR = TRUESQL_API_GETCONNECTATTRW = TRUESQL_API_GETCONNECTOPTION = TRUESQL_API_GETCONNECTOPTIONW = TRUESQL_API_GETCURSORNAME = TRUESQL_API_GETCURSORNAMEW = TRUESQL_API_GETDATA = TRUESQL_API_GETDESCFIELD = TRUESQL_API_GETDESCFIELDW = TRUESQL_API_GETDESCREC = TRUESQL_API_GETDESCRECW = TRUESQL_API_GETDIAGFIELD = TRUESQL_API_GETDIAGFIELDW = TRUESQL_API_GETDIAGREC = TRUESQL_API_GETDIAGRECW = TRUESQL_API_GETENVATTR = TRUESQL_API_GETFUNCTIONS = TRUESQL_API_GETINFO = TRUESQL_API_GETINFOW = TRUESQL_API_GETLENGTH = TRUESQL_API_GETPOSITION = TRUESQL_API_GETPOSITIONW = TRUESQL_API_GETSTMTATTR = TRUESQL_API_GETSTMTATTRW = TRUESQL_API_GETSTMTOPTION = TRUESQL_API_GETSTMTOPTIONW = TRUESQL_API_GETSUBSTRING = TRUESQL_API_GETSUBSTRINGW = TRUESQL_API_GETTYPEINFO = TRUESQL_API_GETTYPEINFOW = TRUESQL_API_LANGUAGES = TRUESQL_API_MORERESULTS = TRUESQL_API_NATIVESQL = TRUESQL_API_NATIVESQLW = TRUESQL_API_NUMPARAMS = TRUESQL_API_NUMRESULTCOLS = TRUESQL_API_PARAMDATA = TRUESQL_API_PARAMOPTIONS = TRUESQL_API_PREPARE = TRUESQL_API_PREPAREW = TRUESQL_API_PRIMARYKEYS = TRUESQL_API_PRIMARYKEYSW = TRUESQL_API_PROCEDURECOLUMNS = TRUESQL_API_PROCEDURECOLUMNSW = TRUESQL_API_PROCEDURES = TRUESQL_API_PROCEDURESW = TRUESQL_API_PUTDATA = TRUESQL_API_RELEASEENV = TRUESQL_API_ROWCOUNT = TRUESQL_API_SETCONNECTATTR = TRUESQL_API_SETCONNECTATTRW = TRUESQL_API_SETCONNECTOPTION = TRUESQL_API_SETCONNECTOPTIONW = TRUESQL_API_SETCURSORNAME = TRUESQL_API_SETCURSORNAMEW = TRUESQL_API_SETDESCFIELD = TRUE

SQLGetFunctions


SQL_API_SETDESCFIELDW = TRUESQL_API_SETDESCREC = TRUESQL_API_SETENVATTR = TRUESQL_API_SETPARAM = TRUESQL_API_SETSTMTATTR = TRUESQL_API_SETSTMTATTRW = TRUESQL_API_SETSTMTOPTION = TRUESQL_API_SETSTMTOPTIONW = TRUESQL_API_SPECIALCOLUMNS = TRUESQL_API_SPECIALCOLUMNSW = TRUESQL_API_STATISTICS = TRUESQL_API_STATISTICSW = TRUESQL_API_TABLES = TRUESQL_API_TABLESW = TRUESQL_API_TRANSACT = TRUE


Diagnostics

Table 93. SQLGetFunctions SQLSTATEs






HY009 Argument value that is notvalid.

The argument pfSupported is a null pointer.

HY010 Function sequence error.Connection handles mustnot be allocated yet.

SQLGetFunctions is called before SQLConnect.



SQLGetFunctions


SQLGetInfo - Get general informationSQLGetInfo() returns general information (including supported data conversions) about the DatabaseManagement System (DBMS) that the application is currently connected to.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetInfoW(). Refer to “Unicode in Db2 for i CLI” on page 307 formore information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetInfo (SQLHDBC hdbc,

SQLSMALLINT fInfoType,SQLPOINTER rgbInfoValue,SQLSMALLINT cbInfoValueMax,SQLSMALLINT *pcbInfoValue);

Function arguments

Table 94. SQLGetInfo arguments



SQLSMALLINT fInfoType Input Type of the required information.

SQLPOINTER rgbInfoValue Output (alsoinput)

Pointer to buffer where this function storesthe required information. Depending on thetype of information being retrieved, fourtypes of information can be returned:

v 16-bit integer value

v 32-bit integer value

v 32-bit binary value

v Null-terminated character string

SQLSMALLINT cbInfoValueMax Input The maximum length of the buffer pointedby rgbInfoValue pointer.

SQLSMALLINT * pcbInfoValue Output Pointer to location where this functionreturns the total number of bytes available toreturn the required information.

If the value in the location pointed to bypcbInfoValue is greater than the size of thergbInfoValue buffer as specified incbInfoValueMax, then the string outputinformation is truncated to cbInfoValueMax - 1bytes and the function returns withSQL_SUCCESS_WITH_INFO.

Usage

Table 95 on page 156 lists the possible values of fInfoType and a description of the information thatSQLGetInfo() returns for that value.

SQLGetInfo


Table 95. Information returned by SQLGetInfo

fInfoType Format Description and notes

SQL_ACTIVE_CONNECTIONS Short int The maximum number of active connectionssupported per application.

Zero is returned, indicating that the limit isdependent on system resources.

SQL_ACTIVE_STATEMENTS Short int The maximum number of active statements perconnection.

Zero is returned, indicating that the limit isdependent on system resources.

SQL_AGGREGATE_FUNCTIONS 32-bit mask A bit mask enumerating support for aggregationfunctions:

v SQL_AF_ALL

v SQL_AF_AVG

v SQL_AF_COUNT

v SQL_AF_DISTINCT

v SQL_AF_MAX

v SQL_AF_MIN

v SQL_AF_SUM

SQL_CATALOG_NAME String A character string of Y indicates that the datasource supports catalog names. N indicates thatcatalog names are not supported.

SQL_COLUMN_ALIAS String Whether the connection supports column aliases.The value Y is returned if the connection supportsthe concept of a column alias.

SQL_CONNECTION_JOB_NAME String When in server mode, this is a character stringthat contains the complete job name associatedwith the connection. When not in server mode, afunction sequence error is returned.

SQLGetInfo


Table 95. Information returned by SQLGetInfo (continued)


SQL_CONVERT_BIGINTSQL_CONVERT_BINARYSQL_CONVERT_BLOBSQL_CONVERT_CHARSQL_CONVERT_CLOBSQL_CONVERT_DATESQL_CONVERT_DBCLOBSQL_CONVERT_DECIMALSQL_CONVERT_DOUBLESQL_CONVERT_FLOATSQL_CONVERT_INTEGERSQL_CONVERT_LONGVARBINARYSQL_CONVERT_LONGVARCHARSQL_CONVERT_NUMERICSQL_CONVERT_REALSQL_CONVERT_SMALLINTSQL_CONVERT_TIMESQL_CONVERT_TIMESTAMPSQL_CONVERT_VARBINARYSQL_CONVERT_VARCHARSQL_CONVERT_WCHARSQL_CONVERT_WLONGVARCHARSQL_CONVERT_WVARCHAR

32-bit mask This indicates the conversions supported by thedata source with the CONVERT scalar functionfor data of the type named in the infoType. If thebit mask equals zero, the data source does notsupport any conversions for the data of thenamed type, including conversions to the samedata type.

For example, to find out if a data source supportsthe conversion of SQL_INTEGER data to theSQL_DECIMAL data type, an application callsSQLGetInfo() with finfoType ofSQL_CONVERT_INTEGER. The application thenANDs the returned bit mask withSQL_CVT_DECIMAL. If the resulting value isnonzero, then the conversion is supported. Thefollowing bit masks are used to determine whichconversions are supported:v SQL_CONVERT_BLOBv SQL_CONVERT_CLOBv SQL_CONVERT_DBCLOBv SQL_CONVERT_SMALLINTv SQL_CONVERT_TIMEv SQL_CONVERT_TIMESTAMPv SQL_CONVERT_VARBINARYv SQL_CONVERT_VARCHARv SQL_CONVERT_WCHARv SQL_CONVERT_WLONGVARCHARv SQL_CONVERT_WVARCHARv SQL_CVT_BIGINTv SQL_CVT_BINARYv SQL_CVT_CHARv SQL_CVT_DATEv SQL_CVT_DECIMALv SQL_CVT_DOUBLEv SQL_CVT_FLOATv SQL_CVT_INTEGERv SQL_CVT_LONGVARBINARYv SQL_CVT_LONGVARCHARv SQL_CVT_NUMERICv SQL_CVT_REAL

SQL_CONVERT_FUNCTIONS 32 bit mask This indicates the scalar conversion functionssupported by the driver and associated datasource:

v SQL_FN_CVT_CONVERT is used to determinewhich conversion functions are supported.

v SQL_FN_CVT_CAST is used to determinewhich cast functions are supported.

SQLGetInfo




SQL_CORRELATION_NAME Short int This indicates the degree of correlation namesupport by the system:

v SQL_CN_ANY – Correlation name is supportedand can be any valid user-defined name.

v SQL_CN_NONE – Correlation name is notsupported.

v SQL_CN_DIFFERENT – Correlation name issupported but it must be different from thename of the table that it represents.

SQL_CURSOR_COMMIT_BEHAVIOR 16-bit integer This indicates how a COMMIT operation affectscursors:

v SQL_CB_DELETE destroys cursors and dropsaccess plans for dynamic SQL statements.

v SQL_CB_CLOSE destroys cursors, but retainsaccess plans for dynamic SQL statements(including nonquery statements).

v SQL_CB_PRESERVE retains cursors and accessplans for dynamic statements (includingnonquery statements). Applications cancontinue to fetch data, or close the cursor andreprocess the query without preparing thestatement again.

Note: After the COMMIT operation, a FETCHmust be issued to reposition the cursor beforeactions such as positioned updates or deletes canbe taken.

SQL_CURSOR_ROLLBACK_BEHAVIOR 16-bit integer This indicates how a ROLLBACK operationaffects cursors:

v SQL_CB_DELETE destroys cursors and dropsaccess plans for dynamic SQL statements.

v SQL_CB_CLOSE destroys cursors, but retainsaccess plans for dynamic SQL statements(including nonquery statements)

v SQL_CB_PRESERVE retains cursors and accessplans for dynamic statements (includingnonquery statements). Applications cancontinue to fetch data, or close the cursor andrun the query again without preparing thestatement again.

Note: DB2 servers do not have theSQL_CB_PRESERVE property.

SQL_DATA_SOURCE_NAME String Name of the connected data source for theconnection handle.

SQL_DATA_SOURCE_READ_ONLY String A character string of Y indicates that the databaseis set to READ ONLY mode; an N indicates that itis not set to READ ONLY mode.

SQL_DATABASE_NAME String Name of the current database in use. This string isthe same as that returned by the SELECTCURRENT SERVER SQL statement.

SQLGetInfo




SQL_DBMS_NAME String Name of the Distributed Relational DatabaseArchitecture™ (DRDA) Service Name beingaccessed.

For example:

v AS for Db2 for i

v DB2/xxx for DB2 for Linux, UNIX, andWindows

v DB2 for DB2 for z/OS®

SQL_DBMS_VER String Version of the DBMS product accessed.

SQL_DEFAULT_TXN_ISOLATION 32-bit mask The default transaction-isolation level supported.

One of the following masks are returned:

v SQL_TXN_READ_UNCOMMITTED – Changesare immediately perceived by all transactions(dirty read, non-repeatable read, and phantomsare possible).

This is equivalent to UR level.

v SQL_TXN_READ_COMMITTED – Row read bytransaction 1 can be altered and committed bytransaction 2 (non-repeatable read andphantoms are possible).

This is equivalent to CS level.

v SQL_TXN_REPEATABLE_READ – Atransaction can add or remove rows matchingthe search condition or a pending transaction(repeatable read, but phantoms are possible).

This is equivalent to RS level.

v SQL_TXN_SERIALIZABLE – Data affected bypending transaction is not available to othertransactions (repeatable read, phantoms are notpossible).

This is equivalent to RR level.

v SQL_TXN_VERSIONING – Not applicable toIBM DBMSs.

v SQL_TXN_NOCOMMIT – Any changes areeffectively committed at the end of a successfuloperation; no explicit commit or rollbackoperation is allowed.

This is a DB2 isolation level.

In IBM terminology,

v SQL_TXN_READ_UNCOMMITTED isuncommitted read.

v SQL_TXN_READ_COMMITTED is cursorstability.

v SQL_TXN_REPEATABLE_READ is readstability.

v SQL_TXN_SERIALIZABLE is repeatable read.

SQL_DESCRIBE_PARAMETER String Y if parameters can be described; N if not.

SQLGetInfo




SQL_DRIVER_NAME String File name of the driver used to access the datasource.

SQL_DRIVER_ODBC_VER String The version number of ODBC that the driversupports. DB2 ODBC returns 2.1.

SQL_GROUP_BY 16-bit integer This indicates the degree of support for theGROUP BY clause by the data source:

v SQL_GB_NO_RELATION means there is norelationship between the columns in theGROUP BY and in the SELECT list.

v SQL_GB_NOT_SUPPORTED – GROUP BY isnot supported.

v SQL_GB_GROUP_BY_EQUALS_SELECT –GROUP BY must include all nonaggregatedcolumns in the select list.

v SQL_GB_GROUP_BY_CONTAINS_SELECT –GROUP BY clause must contain allnonaggregated columns in the SELECT list.

SQL_IDENTIFIER_CASE 16-bit integer This indicates case sensitivity of object names(such as table-name).

v SQL_IC_UPPER – Identifier names are stored inuppercase in the system catalog.

v SQL_IC_LOWER – Identifier names are storedin lowercase in the system catalog.

v SQL_IC_SENSITIVE – Identifier names are casesensitive, and are stored in mixed case in thesystem catalog.

v SQL_IC_MIXED – Identifier names are not casesensitive, and are stored in mixed case in thesystem catalog.

Note: Identifier names in IBM DBMSs are notcase sensitive.

SQL_IDENTIFIER_QUOTE_CHAR String Character used as the delimiter of a quoted string.

SQL_KEYWORDS String A character string containing a comma-separatedlist of all data source-specific keywords. This is alist of all reserved keywords. Interoperableapplications should not use these keywords inobject names. This list does not contain keywordsspecific to ODBC or keywords used by both thedata source and ODBC.

SQL_LIKE_ESCAPE_CLAUSE String A character string that indicates whether anescape character is supported for themetacharacters percent and underscore in a LIKEpredicate.

SQL_MAX_CATALOG_NAME_LEN 16-bit integer The maximum length of a catalog qualifier name;first part of a three-part table name (in bytes).

SQL_MAX_COLUMN_NAME_LEN Short int The maximum length of a column name.

SQL_MAX_COLUMNS_IN_GROUP_BY Short int The maximum number of columns in a GROUPBY clause.

SQL_MAX_COLUMNS_IN_INDEX Short int The maximum number of columns in an SQLindex.

SQLGetInfo




SQL_MAX_COLUMNS_IN_ORDER_BY Short int Maximum number of columns in an ORDER BYclause.

SQL_MAX_COLUMNS_IN_SELECT Short int The maximum number of columns in a SELECTstatement.

SQL_MAX_COLUMNS_IN_TABLE Short int The maximum number of columns in an SQLtable.

SQL_MAX_CURSOR_NAME_LEN Short int The maximum length of a cursor name.

SQL_MAX_OWNER_NAME_LEN Short int The maximum length of an owner name.

SQL_MAX_ROW_SIZE 32–bit unsignedinteger

The maximum length in bytes that the data sourcesupports in a single row of a base table. It is zeroif there is no limit.

SQL_MAX_SCHEMA_NAME_LEN Int The maximum length of a schema name.

SQL_MAX_STATEMENT_LEN 32–bit unsignedinteger

This indicates the maximum length of an SQLstatement string in bytes, including the number ofwhite spaces in the statement.

SQL_MAX_TABLE_NAME Short int The maximum length of a table name.

SQL_MAX_TABLES_IN_SELECT Short int The maximum number of tables in a SELECTstatement.

SQL_MULTIPLE_ACTIVE_TXN String The character string Y indicates that activetransactions on multiple connections are allowed.N indicates that only one connection at a time canhave an active transaction.

SQL_NON_NULLABLE_COLUMNS 16-bit integer This indicates whether non-nullable columns aresupported:

v SQL_NNC_NON_NULL – columns can bedefined as NOT NULL.

v SQL_NNC_NULL – columns cannot be definedas NOT NULL.

SQLGetInfo




SQL_NUMERIC_FUNCTIONS 32-bit mask The scalar numeric functions supported.

The following bit masks are used to determinewhich numeric functions are supported:v SQL_FN_NUM_ABSv SQL_FN_NUM_ACOSv SQL_FN_NUM_ASINv SQL_FN_NUM_ATANv SQL_FN_NUM_ATAN2v SQL_FN_NUM_CEILINGv SQL_FN_NUM_COSv SQL_FN_NUM_COTv SQL_FN_NUM_DEGREESv SQL_FN_NUM_EXPv SQL_FN_NUM_FLOORv SQL_FN_NUM_LOGv SQL_FN_NUM_LOG10v SQL_FN_NUM_MODv SQL_FN_NUM_PIv SQL_FN_NUM_POWERv SQL_FN_NUM_RADIANSv SQL_FN_NUM_RANDv SQL_FN_NUM_ROUNDv SQL_FN_NUM_SIGNv SQL_FN_NUM_SINv SQL_FN_NUM_SQRTv SQL_FN_NUM_TANv SQL_FN_NUM_TRUNCATE

SQL_ODBC_API_CONFORMANCE 16-bit integer The level of ODBC conformance:

v SQL_OAC_NONE

v SQL_OAC_LEVEL1

v SQL_OAC_LEVEL2

SQL_ODBC_SQL_CONFORMANCE 16-bit integer A value of:

v SQL_OSC_MINIMUM means minimum ODBCSQL grammar supported

v SQL_OSC_CORE means core ODBC SQLgrammar supported

v SQL_OSC_EXTENDED means extended ODBCSQL grammar supported

For the definition of the previous types of ODBCSQL grammar, see Microsoft ODBC 3.0 SoftwareDevelopment Kit and Programmer's Reference.

SQL_ORDER_BY_COLUMNS_IN_SELECT String Set to Y if columns in the ORDER BY clausesmust be in the select list; otherwise set to N.

SQL_OUTER_JOINS String The character string:

v Y indicates that outer joins are supported, andDB2 ODBC supports the ODBC outer joinrequest syntax.

v N indicated that outer joins are not supported.

SQL_OWNER_TERM orSQL_SCHEMA_TERM

String The database vendor terminology for a schema(owner).

SQLGetInfo




SQL_OWNER_USAGE orSQL_SCHEMA_USAGE

32-bit mask This indicates the type of SQL statements thathave schema (owners) associated with them whenthese statements are processed. Schema qualifiers(owners) are as follows:

v SQL_OU_DML_STATEMENTS is supported inall DML statements.

v SQL_OU_PROCEDURE_INVOCATION issupported in the procedure invocationstatement.

v SQL_OU_TABLE_DEFINITION is supported inall table definition statements.

v SQL_OU_INDEX_DEFINITION is supported inall index definition statements.

v SQL_OU_PRIVILEGE_DEFINITION issupported in all privilege definition statements(that is, grant and revoke statements).

SQL_POSITIONED_STATEMENTS 32-bit mask This indicates the degree of support forpositioned UPDATE and positioned DELETEstatements:

v SQL_PS_POSITIONED_DELETE

v SQL_PS_POSITIONED_UPDATE

v SQL_PS_SELECT_FOR_UPDATE

SQL_PS_SELECT_FOR_UPDATE indicateswhether the data source requires the FORUPDATE clause to be specified on a <queryexpression> for a column to be updated withthe cursor.

SQL_PROCEDURE_TERM String Data source name for a procedure.

SQL_PROCEDURES String Whether the current server supports SQLprocedures. The value Y is returned if theconnection supports SQL procedures.

SQL_QUALIFIER_LOCATION orSQL_CATALOG_LOCATION

16-bit integer A 16-bit integer value indicated the position of thequalifier in a qualified table name. Zero indicatesthat qualified names are not supported.

SQL_QUALIFIER_NAME_SEPARATOR orSQL_CATALOG_NAME_SEPARATOR

String The characters used as a separator between acatalog name and the qualified name element thatfollows it.

SQL_QUALIFIER_TERM orSQL_CATALOG_TERM

String The database vendor terminology for a qualifier.

This is the name that the vendor uses for thehigh-order part of a 3-part name.

Because DB2 ODBC does not support 3-partnames, a zero-length string is returned.

For non-ODBC applications, theSQL_CATALOG_TERM symbolic name should beused instead of SQL_QUALIFIER_NAME.

SQL_QUALIFIER_USAGE orSQL_CATALOG_USAGE

32-bit mask This is similar to SQL_OWNER_USAGE exceptthat this is used for catalog.

SQLGetInfo




SQL_QUOTED_IDENTIFIER_CASE 16-bit integer v SQL_IC_UPPER – Quoted identifiers in SQL arecase insensitive and stored in uppercase in thesystem catalog.

v SQL_IC_LOWER – Quoted identifiers in SQLare case insensitive and are stored in lowercasein the system catalog.

v SQL_IC_SENSITIVE – Quoted identifiers(delimited identifiers) in SQL are case sensitiveand are stored in mixed case in the systemcatalog.

v SQL_IC_MIXED – Quoted identifiers in SQL arecase insensitive and are stored in mixed case inthe system catalog.

This should be contrasted with theSQL_IDENTIFIER_CASE fInfoType, which is usedto determine how (unquoted) identifiers arestored in the system catalog.

SQL_SEARCH_PATTERN_ESCAPE String Used to specify what the driver supports as anescape character for catalog functions, such asSQLTables() and SQLColumns().

SQL_SQL92_PREDICATES 32-bit mask This indicates the predicates supported in aSELECT statement that SQL-92 defines.v SQL_SP_BETWEENv SQL_SP_COMPARISONv SQL_SP_EXISTSv SQL_SP_INv SQL_SP_ISNOTNULLv SQL_SP_ISNULLv SQL_SP_LIKEv SQL_SP_MATCH_FULLv SQL_SP_MATCH_PARTIALv SQL_SP_MATCH_UNIQUE_FULLv SQL_SP_MATCH_UNIQUE_PARTIALv SQL_SP_OVERLAPSv SQL_SP_QUANTIFIED_COMPARISONv SQL_SP_UNIQUE

SQL_SQL92_VALUE_EXPRESSIONS 32-bit mask This indicates the value expressions supportedthat SQL-92 defines.

v SQL_SVE_CASE

v SQL_SVE_CAST

v SQL_SVE_COALESCE

v SQL_SVE_NULLIF

SQLGetInfo




SQL_STRING_FUNCTIONS 32-bit bit mask This indicates which string functions aresupported.

The following bit masks are used to determinewhich string functions are supported:v SQL_FN_STR_ASCIIv SQL_FN_STR_CHARv SQL_FN_STR_CONCATv SQL_FN_STR_DIFFERENCEv SQL_FN_STR_INSERTv SQL_FN_STR_LCASEv SQL_FN_STR_LEFTv SQL_FN_STR_LENGTHv SQL_FN_STR_LOCATEv SQL_FN_STR_LOCATE_2v SQL_FN_STR_LTRIMv SQL_FN_STR_REPEATv SQL_FN_STR_REPLACEv SQL_FN_STR_RIGHTv SQL_FN_STR_RTRIMv SQL_FN_STR_SOUNDEXv SQL_FN_STR_SPACEv SQL_FN_STR_SUBSTRINGv SQL_FN_STR_UCASE

If an application can call the LOCATE scalarfunction with the string1, string2, and startarguments, the SQL_FN_STR_LOCATE bit maskis returned. If an application can only call theLOCATE scalar function with the string1 andstring2, the SQL_FN_STR_LOCATE_2 bit mask isreturned. If the LOCATE scalar function is fullysupported, both bit masks are returned.

SQL_TIMEDATE_FUNCTIONS 32-bit mask This indicates which time and date functions aresupported.

The following bit masks are used to determinewhich date functions are supported:v SQL_FN_TD_CURDATEv SQL_FN_TD_CURTIMEv SQL_FN_TD_DAYNAMEv SQL_FN_TD_DAYOFMONTHv SQL_FN_TD_DAYOFWEEKv SQL_FN_TD_DAYOFYEARv SQL_FN_TD_HOURv SQL_FN_TD_JULIAN_DAYv SQL_FN_TD_MINUTEv SQL_FN_TD_MONTHv SQL_FN_TD_MONTHNAMEv SQL_FN_TD_NOWv SQL_FN_TD_QUARTERv SQL_FN_TD_SECONDv SQL_FN_TD_SECONDS_SINCE_MIDNIGHTv SQL_FN_TD_TIMESTAMPADDv SQL_FN_TD_TIMESTAMPDIFFv SQL_FN_TD_WEEKv SQL_FN_TD_YEAR

SQLGetInfo




SQL_TXN_CAPABLE Short int This indicates whether transactions can containDDL or DML or both:

v SQL_TC_NONE – Transactions are notsupported.

v SQL_TC_DML – Transactions can only containDML statements (SELECT, INSERT, UPDATE,DELETE, and so on). DDL statements (CREATETABLE, DROP INDEX, and so on) encounteredin a transaction cause an error.

v SQL_TC_DDL_COMMIT – Transactions canonly contain DML statements. DDL statementsencountered in a transaction cause thetransaction to be committed.

v SQL_TC_DDL_IGNORE – Transactions can onlycontain DML statements. DDL statementsencountered in a transaction are ignored.

v SQL_TC_ALL – Transactions can contain DDLand DML statements in any order.

SQL_USER_NAME String User name used in a particular database.


Diagnostics

Table 96. SQLGetInfo SQLSTATEs


01004 Data truncated The requested information is returned as anull-terminated string and its length exceeded the lengthof the application buffer as specified in cbInfoValueMax.The argument pcbInfoValue contains the actual (nottruncated) length of the requested information.

08003 Connection not open The type of information requested in fInfoType requiresan open connection. Only SQL_ODBC_VER does notrequire an open connection.






The argument rgbInfoValue is a null pointer

An fInfoType that is not valid is specified.



SQLGetInfo


SQLGetLength - Retrieve length of a string valueSQLGetLength() is used to retrieve the length of a large object value referenced by a large object locator.The large object locator has been returned from the data source (as a result of a fetch or anSQLGetSubString() call) during the current transaction.

SyntaxSQLRETURN SQLGetLength (SQLHSTMT StatementHandle,

SQLSMALLINT LocatorCType,SQLINTEGER Locator,SQLINTEGER *StringLength,SQLINTEGER *IndicatorValue);

Function arguments

Table 97. SQLGetLength arguments


SQLHSTMT StatementHandle Input Statement handle. This can be any statement handlewhich has been allocated but which does notcurrently have a prepared statement assigned to it.

SQLSMALLINT LocatorCType Input The C type of the source LOB locator.




SQLINTEGER Locator Input Must be set to the LOB locator value.

SQLINTEGER * StringLength Output The length of the specified locator.1

If the pointer is set to NULL then the SQLSTATEHY009 is returned.

SQLINTEGER * IndicatorValue Output Always set to zero.

1. This is in bytes even for DBCLOB data.

Usage

SQLGetLength() can be used to determine the length of the data value represented by a LOB locator. It isused by applications to determine the overall length of the referenced LOB value so that the appropriatestrategy to obtain some or all of the LOB value can be chosen.

The Locator argument can contain any valid LOB locator which has not been explicitly freed using aFREE LOCATOR statement nor implicitly freed because the transaction during which it is created hasterminated.

The statement handle must not have been associated with any prepared statements or catalog functioncalls.

Db2 for i restricts the use of LOB locators when running with no isolation level.


SQLGetLength


Error conditions

Table 98. SQLGetLength SQLSTATEs


07006 Conversion that is not valid The combination of the argumentLocatorCType and Locator is notvalid.

0F001 LOB variable that is not valid The value specified for the argument Locator has not beenassociated with a LOB locator.


HY003 Program type out of range The argument LocatorCType is not one ofSQL_C_CLOB_LOCATOR, SQL_C_BLOB_LOCATOR, orSQL_C_DBCLOB_LOCATOR.

HY009 Argument value that is not valid The argument StringLength or IndicatorValue is a null pointer.

HY010 Function sequence error The specified argument StatementHandle is not in an allocated state.



HYC00 Driver not capable The application is currently connected to a data source that doesnot support large objects.

Restrictions

This function is not available when connected to a DB2 server that does not support Large Objects.

Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLFetch - Fetch next row” on page 108v “SQLGetPosition - Return starting position of string” on page 169v “SQLGetSubString - Retrieve portion of a string value” on page 176

SQLGetLength


SQLGetPosition - Return starting position of stringSQLGetPosition() is used to return the starting position of one string within a LOB value (the source).The source value must be a LOB locator; the search string can be a LOB locator or a literal string.

The source and search LOB locators can be any that have been returned from the database from a fetchor an SQLGetSubString() call during the current transaction.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetPositionW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetPosition (SQLHSTMT StatementHandle,

SQLSMALLINT LocatorCType,SQLINTEGER SourceLocator,SQLINTEGER SearchLocator,SQLCHAR *SearchLiteral,SQLINTEGER SearchLiteralLength,SQLINTEGER FromPosition,SQLINTEGER *LocatedAt,SQLINTEGER *IndicatorValue);

Function arguments

Table 99. SQLGetPosition arguments


SQLHSTMT StatementHandle Input Statement handle. This can be any statementhandle which has been allocated but which doesnot currently have a prepared statement assignedto it.

SQLSMALLINT LocatorCType Input The C type of the source LOB locator. This can be:




SQLINTEGER SourceLocator Input SourceLocator must be set to the source LOBlocator.

SQLINTEGER SearchLocator Input If the SearchLiteral pointer is NULL and ifSearchLiteralLength is set to 0, then SearchLocatormust be set to the LOB locator associated with thesearch string; otherwise, this argument is ignored.The lob locator type for the SearchLocator must bethe same as the locator type used by theSourceLocator. This locator type is set forargument LocatorCType.

SQLCHAR * SearchLiteral Input This argument points to the area of storage thatcontains the search string literal.

If SearchLiteralLength is 0, this pointer must beNULL. If the LocatorCType is set toSQL_C_DBCLOB_LOCATOR, and the call toSQLGetPositionW was made, then the string literalis assumed to be double byte data. If a call to thenon Wide API was made, then this string literal isassumed to be single byte data

SQLGetPosition


Table 99. SQLGetPosition arguments (continued)


SQLINTEGER SearchLiteralLength Input The length of the string in SearchLiteral(in bytes).1

If this argument value is 0, then the argumentSearchLocator is meaningful.

SQLINTEGER FromPosition Input For BLOBs and CLOBs, this is the position of thefirst byte within the source string at which thesearch is to start. to be returned by the function.For DBCLOBs, this is the first character. The startbyte or character is numbered 1.

SQLINTEGER * LocatedAt Output For BLOBs and CLOBs, this is the byte position atwhich the string is located or, if not located, thevalue zero. For DBCLOBs, this is the characterposition.

If the length of the source string is zero, the value1 is returned.

SQLINTEGER * IndicatorValue Output Always set to zero.

1. This is in double byte characters for a call to the SQLGetPositionW API, but in bytes for a call to theSQLGetPosition API for DBCLOB data.

Usage

SQLGetPosition() is used in conjunction with SQLGetSubString() in order to obtain any portion of astring in a random manner. In order to use SQLGetSubString(), the location of the substring within theoverall string must be known in advance. In situations where the start of that substring can be found bya search string, SQLGetPosition() can be used to obtain the starting position of that substring.

The Locator and SearchLocator (if used) arguments can contain any valid LOB locator which has not beenexplicitly freed using a FREE LOCATOR statement or implicitly freed because the transaction duringwhich it is created has terminated.

The Locator and SearchLocator must have the same LOB locator type.


If a remote connection has been made, the CCSID of the CLOB data (SourceLocator) must be compatiblewith the CCSID of the job executing the SQLGetSubString API, otherwise translation problems will occur.


Error conditions

Table 100. SQLGetPosition SQLSTATEs


07006 Conversion that is not valid The combination of the LocatorCType argument and either of theLOB locator values is not valid.

SQLGetPosition


Table 100. SQLGetPosition SQLSTATEs (continued)


0F001 LOB variable that is not valid The value specified for argument Locator or SearchLocator is notcurrently a LOB locator.

22522 CCSID not valid. The specified LocatorCType argument does not match the actualLOB type of the input locator.

42818 Length that is not valid The length of the pattern is too long.


HY009 Argument value that is not valid The argument LocatedAt or IndicatorValue is a null pointer.

The argument value for FromPosition is not greater than 0.

LocatorCType is not one of SQL_C_CLOB_LOCATOR,SQL_C_BLOB_LOCATOR, or SQL_C_DBCLOB_LOCATOR.

HY010 Function sequence error The specified StatementHandle argument is not in an allocated state.




The value of SearchLiteralLength is less than 1, and not SQL_NTS.


Restrictions


Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLExtendedFetch - Fetch array of rows” on page 106v “SQLFetch - Fetch next row” on page 108v “SQLGetLength - Retrieve length of a string value” on page 167v “SQLGetSubString - Retrieve portion of a string value” on page 176

SQLGetPosition


SQLGetStmtAttr - Get the value of a statement attributeSQLGetStmtAttr() returns the current settings of the specified statement attribute.

These options are set using the SQLSetStmtAttr() function. This function is similar toSQLGetStmtOption(). Both functions are supported for compatibility reasons.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetStmtAttrW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetStmtAttr( SQLHSTMT hstmt,

SQLINTEGER fAttr,SQLPOINTER pvParam,SQLINTEGER bLen,SQLINTEGER *sLen);

Function arguments

Table 101. SQLGetStmtAttr arguments



SQLINTEGER fAttr Input Attribute to retrieve. Refer to Table 102 for moreinformation.

SQLPOINTER pvParam Output Pointer to buffer for requested attribute.

SQLINTEGER bLen Input Maximum number of bytes to store in pvParam, ifthe attribute is a character string; otherwise,unused.

SQLINTEGER * sLen Output Length of output data if the attribute is acharacter string; otherwise, unused.

Usage

Table 102. Statement attributesfAttr Data type Contents

SQL_ATTR_APP_PARAM_DESC Integer The descriptor handle used by the application to provide parameter values for this statementhandle.

SQL_ATTR_APP_ROW_DESC Integer The descriptor handle for the application to retrieve row data using the statement handle.

SQL_ATTR_CURSOR_SCROLLABLE Integer A 32-bit integer value that specifies if cursors opened for this statement handle should bescrollable.

v SQL_FALSE – Cursors are not scrollable, and SQLFetchScroll() cannot be used against them.

v SQL_TRUE – Cursors are scrollable. SQLFetchScroll() can be used to retrieve data fromthese cursors.

SQL_ATTR_CURSOR_TYPE Integer A 32-bit integer value that specifies the behavior of cursors opened for this statement handle.

v SQL_CURSOR_FORWARD_ONLY – Cursors are not scrollable, and SQLFetchScroll() cannotbe used against them.

v SQL_DYNAMIC – Cursors are scrollable. SQLFetchScroll() can be used to retrieve data fromthese cursors.

SQL_ATTR_CURSOR_SENSITIVITY Integer The cursor sensitivity.

v SQL_UNSPECIFIED – Cursors on the statement handle might make visible none, some, or allsuch changes depending on the cursor type.

v SQL_INSENSITIVE – All valid cursors on the statement handle show the result set withoutreflecting any changes made to it by any other cursor.

v SQL_SENSITIVE – All valid cursors on the statement handle make visible all changes madeto a result by another cursor.

SQLGetStmtAttr


|||||||||

Table 102. Statement attributes (continued)fAttr Data type Contents

SQL_ATTR_CURSOR_HOLD Integer Returns the HOLDABILITY for the cursor for the statement.

v SQL_FALSE – Cursor position is not held across transaction boundaries.

v SQL_TRUE – Cursor position is held across transaction boundaries.

SQL_ATTR_FOR_FETCH_ONLY Integer This indicates if cursors opened for this statement handle should be read-only.

v SQL_FALSE - Cursors can be used for positioned updates and deletes. This is the default.

v SQL_TRUE - Cursors are read-only and cannot be used for positioned updates or deletes.

SQL_ATTR_IMP_PARAM_DESC Integer The descriptor handle used by the CLI implementation to provide parameter values for thisstatement handle.

SQL_ATTR_IMP_ROW_DESC Integer The descriptor handle used by the CLI implementation to retrieve row data using this statementhandle.

SQL_ATTR_ROWSET_SIZE Integer A 32–bit integer value that specifies the number of rows in the rowset. This is the number ofrows returned by each call to SQLExtendedFetch(). The default value is 1.

SQL_ATTR_PARAM_BIND_TYPE Integer The binding used for the parameters.

v SQL_BIND_BY_ROW - Binding is row-wise. This is the default. When using row-wisebinding for a multiple row statements, all of the data for each row must be contiguousstorage, followed by the data for the next row, and so on.

v SQL_BIND_BY_COLUMN - Binding is column-wise. When using column-wise binding for amultiple row statements, all of the data for each column is in contiguous storage. A differentaddress is provided by the user for each column in the statement, and it is the responsibilityof the user to ensure that each address has space for all the parameter data to be passed tothe database.

SQL_ATTR_ROW_BIND_TYPE Integer The binding used for rows.

v SQL_BIND_BY_ROW - Binding is row-wise. When using row-wise binding for a multiplerow fetch, all of the data for a row is returned in contiguous storage, followed by the data forthe next row, and so on.

v SQL_BIND_BY_COLUMN - Binding is column-wise. When using column-wise binding for amultiple row fetch, all of the data for each column is returned in contiguous storage. Thestorage for each column need not be contiguous. A different address is provided by the userfor each column in the result set, and it is the responsibility of the user to ensure that eachaddress has space for all the data to be retrieved.

SQL_ATTR_PARAMSET_SIZE Integer Returns the number of rows for each multiple row statement. These include INSERT, MERGE,and UPDATE statements.

Return codesv SQL_SUCCESSv SQL_SUCCESS_WITH_INFOv SQL_ERRORv SQL_INVALID_HANDLEv SQL_NO_DATA

Diagnostics

Table 103. SQLGetStmtAttr SQLSTATEs





An fAttr that is not valid value is specified.

HYC00 Driver not capable Db2 for i CLI recognizes the option but does not supportit.

SQLGetStmtAttr


||||||||||||||||||||||||||

SQLGetStmtOption - Return current setting of a statement optionSQLGetStmtOption() has been deprecated and replaced with SQLGetStmtAttr(). Although this version ofDb2 for i CLI continues to support SQLGetStmtOption(), it is recommended that you begin usingSQLGetStmtAttr() in your Db2 for i CLI programs so that they conform to the latest standards.

SQLGetStmtOption() returns the current settings of the specified statement option.

These options are set using the SQLSetStmtOption() function.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetStmtOptionW(). Refer to “Unicode in Db2 for i CLI” on page307 for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetStmtOption( SQLHSTMT hstmt,

SQLSMALLINT fOption,SQLPOINTER pvParam);

Function arguments

Table 104. SQLStmtOption arguments


SQLHSTMT hstmt Input Connection handle.

SQLSMALLINT fOption Input Option to retrieve. See Table 102 on page 172 for moreinformation.

SQLPOINTER pvParam Output Value of the option. Depending on the value of fOptionthis can be a 32-bit integer value, or a pointer to a nullterminated character string.

Usage

SQLGetStmtOption() provides the same function as SQLGetStmtAttr(), both functions are supported forcompatibility reasons.

See Table 102 on page 172 for a list of statement options.


Diagnostics

Table 105. SQLStmtOption SQLSTATEs





A fOption that is not valid value is specified.

SQLGetStmtOption


Table 105. SQLStmtOption SQLSTATEs (continued)


HYC00 Driver not capable Db2 for i CLI recognizes the option but does not supportit.

References

“SQLGetStmtAttr - Get the value of a statement attribute” on page 172

SQLGetStmtOption


SQLGetSubString - Retrieve portion of a string valueSQLGetSubString() is used to retrieve a portion of a large object value referenced by a large object locator.The large object locator has been returned from the data source (returned by a fetch or a previousSQLGetSubString() call) during the current transaction.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetSubStringW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetSubString (

SQLHSTMT StatementHandle,SQLSMALLINT LocatorCType,SQLINTEGER SourceLocator,SQLINTEGER FromPosition,SQLINTEGER ForLength,SQLSMALLINT TargetCType,SQLPOINTER DataPtr,SQLINTEGER BufferLength,SQLINTEGER *StringLength,SQLINTEGER *IndicatorValue);

Function arguments

Table 106. SQLGetSubString arguments


SQLHSTMT StatementHandle input Statement handle. This can be any statementhandle which has been allocated but whichdoes not currently have a prepared statementassigned to it.

SQLSMALLINT LocatorCType input The C type of the source LOB locator. This canbe:




SQLINTEGER SourceLocator input SourceLocator must be set to the source LOBlocator value.

SQLINTEGER FromPosition input For BLOBs and CLOBs, this is the position ofthe first byte to be returned by the function.For DBCLOBs, this is the first character. Thestart byte or character is numbered 1.

SQLINTEGER ForLength input This is the length of the string to be returnedby the function. For BLOBs and CLOBs, this isthe length in bytes. For DBCLOBs, this is thelength in characters.

If FromPosition is less than the length of thesource string but FromPosition + ForLength - 1extends beyond the end of the source string,the result is padded on the right with thenecessary number of characters (X'00' forBLOBs, single byte blank character for CLOBs,and double byte blank character forDBCLOBs).

SQLGetSubString


Table 106. SQLGetSubString arguments (continued)


SQLSMALLINT TargetCType input The C data type of the DataPtr. The targetmust be a C string variable (SQL_C_CHAR,SQL_C_WCHAR, SQL_C_BINARY, orSQL_C_DBCHAR).

SQLPOINTER DataPtr output Pointer to the buffer where the retrieved stringvalue or a LOB locator is to be stored.

SQLINTEGER BufferLength input Maximum size of the buffer pointed to byDataPtr in bytes.

SQLINTEGER * StringLength output The length of the returned information inDataPtr in bytesa if the target C buffer type isintended for a binary or character stringvariable and not a locator value.

If the pointer is set to NULL, nothing isreturned.

SQLINTEGER * IndicatorValue output Always set to zero.

Note: 1. This is in bytes even for DBCLOB data.

Usage

SQLGetSubString() is used to obtain any portion of the string that is represented by the LOB locator.There are two choices for the target:v The target can be an appropriate C string variable.v A new LOB value can be created on the server and the LOB locator for that value can be assigned to a

target application variable on the client.

SQLGetSubString() can be used as an alternative to SQLGetData() for getting data in pieces. In this case acolumn is first bound to a LOB locator, which is then used to fetch the LOB as a whole or in pieces.

The Locator argument can contain any valid LOB locator which has not been explicitly freed using aFREE LOCATOR statement nor implicitly freed because the transaction during which it is created hasterminated.


If a locator entry exists in the locator table but has no data, SQLGetSubString() will return anSQL_NO_DATA return code.

If a remote connection has been made, the CCSID of the CLOB data (SourceLocator) must be compatiblewith the CCSID of the job executing the SQLGetSubString API, otherwise translation problems will occur.

Return codesv SQL_SUCCESSv SQL_SUCCESS_WITH_INFOv SQL_ERRORv SQL_INVALID_HANDLEv SQL_NO_DATA

SQLGetSubString


Error conditions

Table 107. SQLGetSubString SQLSTATEs


01004 Data truncated The amount of data to be returned is longer than BufferLength.Actual length available for return is stored in StringLength.

07006 Conversion that is not valid The value specified for TargetCType is not SQL_C_CHAR,SQL_C_BINARY, SQL_C_DBCHAR, or a LOB locator.

The value specified for TargetCType is inappropriate for the source(for example SQL_C_DBCHAR for a BLOB column).

22011 Substring error occurred FromPosition is greater than the length of the source string.


HY003 Program type out of range LocatorCType is not one of SQL_C_CLOB_LOCATOR,SQL_C_BLOB_LOCATOR, or SQL_C_DBCLOB_LOCATOR.

HY009 Argument value that is not valid The value specified for FromPosition or ForLength is not a positiveinteger.

The argument DataPtr, StringLength, or IndicatorValue is a nullpointer

HY010 Function sequence error The specified StatementHandle is not in an allocated state.




The value of BufferLength is less than 0.


0F001 No locator currently assigned The value specified for Locator is not currently a LOB locator.

Restrictions


Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLFetch - Fetch next row” on page 108v “SQLGetData - Get data from a column” on page 139v “SQLGetLength - Retrieve length of a string value” on page 167v “SQLGetPosition - Return starting position of string” on page 169

SQLGetSubString


SQLGetTypeInfo - Get data type informationSQLGetTypeInfo() returns information about the data types that are supported by the DatabaseManagement Systems (DBMSs) associated with Db2 for i CLI. The information is returned in an SQLresult set. The columns can be received using the same functions that are used to process a query.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLGetTypeInfoW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLGetTypeInfo (SQLHSTMT StatementHandle,

SQLSMALLINT DataType);

Function arguments

Table 108. SQLGetTypeInfo arguments


SQLHSTMT StatementHandle Input Statement handle

SQLSMALLINT DataType Input The SQL data type being queried. The supportedtypes are:

v SQL_ALL_TYPES

v SQL_BIGINT

v SQL_BINARY

v SQL_BLOB

v SQL_CHAR

v SQL_CLOB

v SQL_DATE

v SQL_DBCLOB

v SQL_DECFLOAT

v SQL_DECIMAL

v SQL_DOUBLE

v SQL_FLOAT

v SQL_GRAPHIC

v SQL_INTEGER

v SQL_NUMERIC

v SQL_REAL

v SQL_SMALLINT

v SQL_TIME

v SQL_TIMESTAMP

v SQL_VARBINARY

v SQL_VARCHAR

v SQL_VARGRAPHIC

If SQL_ALL_TYPES is specified, information aboutall supported data types is returned in ascendingorder by TYPE_NAME. All unsupported data typesare absent from the result set.

SQLGetTypeInfo


Usage

Because SQLGetTypeInfo() generates a result set and is equivalent to executing a query, it generates acursor and begins a transaction. To prepare and process another statement on this statement handle, thecursor must be closed.

If SQLGetTypeInfo() is called with a DataType that is not valid, an empty result set is returned.

The columns of the result set that is generated by this function are described below.

Although new columns might be added and the names of the existing columns might be changed infuture releases, the position of the current columns does not change. The data types that are returned arethose that can be used in a CREATE TABLE, ALTER TABLE, DDL statement. Nonpersistent data typesare not part of the returned result set. User-defined data types are not returned either.

Table 109. Columns returned by SQLGetTypeInfo


1 TYPE_NAME VARCHAR(128) NOT NULL Character representation of the SQL data type name(for example, VARCHAR, DATE, INTEGER)

2 DATA_TYPE SMALLINT NOT NULL SQL data type define values (for example,SQL_VARCHAR, SQL_DATE, SQL_INTEGER)

3 COLUMN_SIZE INTEGER If the data type is a character or binary string, thenthis column contains the maximum length in bytes; ifit is a graphic (DBCS) string, this is the number ofdouble byte characters for the column.

For date, time, timestamp data types, this is the totalnumber of characters required to display the valuewhen converted to character.

For numeric data types, this is the total number ofdigits.

4 LITERAL_PREFIX VARCHAR(128) Character that DB2 recognizes as a prefix for a literalof this data type. This column is null for data typeswhere a literal prefix is not applicable.

5 LITERAL_SUFFIX VARCHAR(128) Character that DB2 recognizes as a suffix for a literal ofthis data type. This column is null for data typeswhere a literal prefix is not applicable.

6 CREATE_PARAMS VARCHAR(128) The text of this column contains a list of keywords,separated by commas, corresponding to eachparameter the application might specify in parenthesiswhen using the name in the TYPE_NAME column as adata type in SQL. The keywords in the list can be:LENGTH, PRECISION, SCALE. They appear in theorder that the SQL syntax requires that they be used.

A NULL indicator is returned if there are noparameters for the data type definition, (such asINTEGER).Note: The intent of CREATE_PARAMS is to enable anapplication to customize the interface for a DDLbuilder. An application should expect, using this, onlyto be able to determine the number of argumentsrequired to define the data type and to have localizedtext that can be used to label an edit control.

SQLGetTypeInfo


Table 109. Columns returned by SQLGetTypeInfo (continued)


7 NULLABLE SMALLINT NOT NULL This indicates whether the data type accepts a NULLvalue

v Set to SQL_NO_NULLS if NULL values aredisallowed.

v Set to SQL_NULLABLE if NULL values are allowed.

v Set to SQL_NULLABLE_UNKNOWN if it is notknown whether NULL values are allowed or not.

8 CASE_SENSITIVE SMALLINT NOT NULL This indicates whether the data type can be treated ascase sensitive for collation purposes; valid values areSQL_TRUE and SQL_FALSE.

9 SEARCHABLE SMALLINT NOT NULL This indicates how the data type is used in a WHEREclause. Valid values are:

v SQL_UNSEARCHABLE – if the data type cannot beused in a WHERE clause.

v SQL_LIKE_ONLY – if the data type can be used in aWHERE clause only with the LIKE predicate.

v SQL_ALL_EXCEPT_LIKE – if the data type can beused in a WHERE clause with all comparisonoperators except LIKE.

v SQL_SEARCHABLE – if the data type can be usedin a WHERE clause with any comparison operator.

10 UNSIGNED_ATTRIBUTE SMALLINT This indicates where the data type is unsigned. Thevalid values are: SQL_TRUE, SQL_FALSE or NULL. ANULL indicator is returned if this attribute is notapplicable to the data type.

11 FIXED_PREC_SCALE SMALLINT NOT NULL This contains the value SQL_TRUE if the data type isexact numeric and always has the same precision andscale; otherwise, it contains SQL_FALSE.

12 AUTO_UNIQUE_VAL SMALLINT This contains SQL_TRUE if a column of this data typeis automatically set to a unique value when a row isinserted; otherwise, contains SQL_FALSE.

13 LOCAL_TYPE_NAME VARCHAR(128) This column contains any localized name for the datatype that is different from the regular name of the datatype. If there is no localized name, this column isNULL.

This column is intended for display only. The characterset of the string is locale-dependent and is typically thedefault character set of the database.

14 MINIMUM_SCALE INTEGER The minimum scale of the SQL data type. If a datatype has a fixed scale, the MINIMUM_SCALE andMAXIMUM_SCALE columns both contain the samevalue. NULL is returned where scale is not applicable.

15 MAXIMUM_SCALE INTEGER The maximum scale of the SQL data type. NULL isreturned where scale is not applicable. If the maximumscale is not defined separately in the DBMS, but isdefined instead to be the same as the maximum lengthof the column, then this column contains the samevalue as the COLUMN_SIZE column.

SQLGetTypeInfo


Table 109. Columns returned by SQLGetTypeInfo (continued)


16 SQL_DATA_TYPE SMALLINT NOT NULL The value of the SQL data type as it appears in theSQL_DESC_TYPE field of the descriptor. This columnis the same as the DATA_TYPE column (except forinterval and datetime data types which Db2 for i CLIdoes not support).

17 SQL_DATETIME_SUB SMALLINT This field is always NULL (Db2 for i CLI does notsupport interval and datetime data types).

18 NUM_PREC_RADIX INTEGER If the data type is an approximate numeric type, thiscolumn contains the value 2 to indicate thatCOLUMN_SIZE specifies a number of bits. For exactnumeric types, this column contains the value 10 toindicate that COLUMN_SIZE specifies a number ofdecimal digits. Otherwise, this column is NULL.

19 INTERVAL_PRECISION SMALLINT This field is always NULL (Db2 for i CLI does notsupport interval data types).


Error conditions

Table 110. SQLGetTypeInfo SQLSTATEs


24000 Cursor state that is not valid A cursor is already opened on the statement handle.StatementHandle has not been closed.



HY004 SQL data type out of range A DataType that is not valid is specified.





Restrictions

The following ODBC specified SQL data types (and their corresponding DataType define values) are notsupported by any IBM RDBMS.

Data type DataType

TINY INT SQL_TINYINT

BIT SQL_BIT

SQLGetTypeInfo


Example

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./* From CLI sample typeinfo.c *//* ... */

rc = SQLGetTypeInfo(hstmt, SQL_ALL_TYPES);CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;

rc = SQLBindCol(hstmt, 1, SQL_C_CHAR, (SQLPOINTER) typename.s, 128, &typename.ind);CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;

rc = SQLBindCol(hstmt, 2, SQL_C_DEFAULT, (SQLPOINTER) & datatype,sizeof(datatype), &datatype_ind);


rc = SQLBindCol(hstmt, 3, SQL_C_DEFAULT, (SQLPOINTER) & precision,sizeof(precision), &precision_ind);


rc = SQLBindCol(hstmt, 7, SQL_C_DEFAULT, (SQLPOINTER) & nullable,sizeof(nullable), &nullable_ind);


rc = SQLBindCol(hstmt, 8, SQL_C_DEFAULT, (SQLPOINTER) & casesens,sizeof(casesens), &casesens_ind);


printf("Datatype Datatype Precision Nullable Case\n");printf("Typename (int) Sensitive\n");printf("------------------------- -------- ---------- -------- ---------\n");/* LONG VARCHAR FOR BIT DATA 99 2147483647 FALSE FALSE *//* Fetch each row, and display */while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS) {

printf("%-25s ", typename.s);printf("%8d ", datatype);printf("%10ld ", precision);printf("%-8s ", truefalse[nullable]);printf("%-9s\n", truefalse[casesens]);

} /* endwhile */

if ( rc != SQL_NO_DATA_FOUND )CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;

Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLGetInfo - Get general information” on page 155

SQLGetTypeInfo


SQLLanguages - Get SQL dialect or conformance informationSQLLanguages() returns SQL dialect or conformance information. The information is returned in an SQLresult set, which can be retrieved using the same functions that are used to fetch a result set generated bya SELECT statement.

SyntaxSQLRETURN SQLLanguages (SQLHSTMT hstmt);

Function arguments

Table 111. SQLLanguages arguments



Usage

The function returns dialect and conformance information, in the form of a result set on StatementHandle.This contains a row for every conformance claim the SQL product makes (including subsets defined forISO and vendor-specific versions). For a product that claims to comply with this specification, the resultset thus contains at least one row.

Rows defining ISO standard and vendor-specific languages can exist in the same table. Each row has atleast these columns and, if it makes an X/Open SQL conformance claim, the columns contains thesevalues.

Table 112. Columns returned by SQLLanguages


1 SOURCE VARCHAR(254), NOT NULL The organization that defined thisSQL version.

2 SOURCE_YEAR VARCHAR(254) The year the relevant sourcedocument is approved.

3 CONFORMANCE VARCHAR(254) The conformance level to the relevantdocument that the implementationclaims.

4 INTEGRITY VARCHAR(254) An indication of whether theimplementation supports the IntegrityEnhancement Feature (IEF).

5 IMPLEMENTATION VARCHAR(254) A character string, defined by thevendor, that uniquely identifies thevendor's SQL product.

6 BINDING_SYTLE VARCHAR(254) Either 'EMBEDDED', 'DIRECT', OR'CLI'.

7 PROGRAMMING_LANG VARCHAR(254) The host language for which thebinding style is supported.


SQLLanguages


Diagnostics

Table 113. SQLLanguages SQLSTATEs


24000 Cursor state that is not valid Cursor related information is requested, but no cursor isopen.





The value of one of the name length arguments is lessthan 0, but not equal SQL_NTS.

HYC00 Driver not capable Db2 for i CLI does not support catalog as a qualifier fortable name.

SQLLanguages


SQLMoreResults - Determine whether there are more result setsSQLMoreResults() determines whether there is more information available on the statement handle thathas been associated with a stored procedure that is returning result sets.

SyntaxSQLRETURN SQLMoreResults (SQLHSTMT StatementHandle);

Function arguments

Table 114. SQLMoreResults arguments


SQLHSTMT StatementHandle input Statement handle

Usage

This function is used to return multiple results that are set in a sequential manner upon the processing ofa stored procedure that contains SQL queries. The cursors have been left open so that the result setsremain accessible when the stored procedure has finished processing.

After completely processing the first result set, the application can call SQLMoreResults() to determine ifanother result set is available. If the current result set has unfetched rows, SQLMoreResults() discardsthem by closing the cursor and, if another result set is available, returns SQL_SUCCESS.

If all the result sets have been processed, SQLMoreResults() returns SQL_NO_DATA_FOUND.

If SQLFreeStmt() is called with the SQL_CLOSE or SQL_DROP option, all pending result sets on thisstatement handle are discarded.


Error conditions

Table 115. SQLMoreResults SQLSTATEs











SQLMoreResults


In addition SQLMoreResults() can return the SQLSTATEs associated with SQLExecute().

Restrictions

The ODBC specification of SQLMoreResults() also allow counts associated with the processing ofparameterized INSERT, UPDATE, and DELETE statements with arrays of input parameter values to bereturned. However, Db2 for i CLI does not support the return of such count information.

Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLBindParameter - Bind a parameter marker to a buffer” on page 52

SQLMoreResults


SQLNativeSql - Get native SQL textSQLNativeSql() is used to show how Db2 for i CLI interprets vendor escape clauses. If the original SQLstring that is passed by the application contains vendor escape clause sequences, Db2 for i CLI returnsthe transformed SQL string that is seen by the data source (with vendor escape clauses either convertedor discarded as appropriate).

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLNativeSqlW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLNativeSql (SQLHDBC ConnectionHandle,

SQLCHAR *InStatementText,SQLINTEGER TextLength1,SQLCHAR *OutStatementText,SQLINTEGER BufferLength,SQLINTEGER *TextLength2Ptr);

Function arguments

Table 116. SQLNativeSql arguments


SQLHDBC ConnectionHandle Input Connection handle.

SQLCHAR * InStatementText Input Input SQL string.

SQLINTEGER TextLength1 Input Length of InStatementText.

SQLCHAR * OutStatementText Output Pointer to buffer for the transformed outputstring.

SQLINTEGER BufferLength Input Size of buffer pointed by OutStatementText.

SQLINTEGER * TextLength2Ptr Output The total number of bytes available to returnin OutStatementText. If the number of bytesavailable to return is greater than or equal toBufferLength, the output SQL string inOutStatementText is truncated to BufferLength -1 bytes. The value SQL_NULL_DATA isreturned if no output string is generated.

Usage

This function is called when the application wants to examine or display the transformed SQL string thatis passed to the data source by Db2 for i CLI. Translation (mapping) only occurs if the input SQLstatement string contains vendor escape clause sequences.

There are no vendor escape sequences on the IBM i operating system; this function is provided forcompatibility purposes. Also, note that this function can be used to evaluate an SQL string for syntaxerrors.


SQLNativeSql


Error conditions

Table 117. SQLNativeSql SQLSTATEs


01004 Data truncated The buffer OutStatementText is not large enough to contain theentire SQL string, so truncation occurred. The argumentTextLength2Ptr contains the total length of the untruncated SQLstring. (Function returns with SQL_SUCCESS_WITH_INFO.)

08003 Connection is closed The ConnectionHandle does not reference an open databaseconnection.

37000 SQL syntax that is not valid The input SQL string in InStatementText contained a syntax error.


HY009 Argument value that is not valid The argument InStatementText, OutStatementText, or TextLength2Ptris a null pointer.


The argument TextLength1 is less than 0, but not equal toSQL_NTS.

The argument BufferLength is less than 0.

Restrictions

None.

Example

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./* From CLI sample native.c *//* ... */

SQLCHAR in_stmt[1024], out_stmt[1024] ;SQLSMALLINT pcPar ;SQLINTEGER indicator ;

/* ... *//* Prompt for a statement to prepare */printf("Enter an SQL statement: \n");gets((char *)in_stmt);

/* prepare the statement */rc = SQLPrepare(hstmt, in_stmt, SQL_NTS);CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;

SQLNumParams(hstmt, &pcPar);CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;

SQLNativeSql(hstmt, in_stmt, SQL_NTS, out_stmt, 1024, &indicator);CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;

if ( indicator == SQL_NULL_DATA ) printf( "Invalid statement\n" ) ;else {

printf( "Input Statement: \n %s \n", in_stmt ) ;printf( "Output Statement: \n %s \n", in_stmt ) ;printf( "Number of Parameter Markers = %d\n", pcPar ) ;

}

rc = SQLFreeHandle( SQL_HANDLE_STMT, hstmt ) ;CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;

SQLNativeSql


SQLNextResult - Process the next result setSQLNextResult() determines whether there is more information available on the statement handle thathas been associated with a stored procedure that is returning result sets.

SyntaxSQLRETURN SQLNextResult (SQLHSTMT StatementHandle,

SQLHSTMT NextResultHandle);

Function arguments

Table 118. SQLNextResult arguments



SQLHSTMT NextResultHandle Input Statement handle for next result set.

Usage

This function is used to associate the next result set from StatementHandle with NextResultHandle. Thisdiffers from SQLMoreResults() because it allows both statement handles to process their result setssimultaneously.

If all the result sets have been processed, SQLNextResult() returns SQL_NO_DATA_FOUND.

If SQLFreeStmt() is called with the SQL_CLOSE or SQL_DROP option, all pending result sets on thisstatement handle are discarded.


Error conditions

Table 119. SQLNextResult SQLSTATEs











SQLNextResult


References

“SQLMoreResults - Determine whether there are more result sets” on page 186

SQLNextResult


SQLNumParams - Get number of parameters in an SQL statementSQLNumParams() returns the number of parameter markers in an SQL statement.

SyntaxSQLRETURN SQLNumParams (SQLHSTMT StatementHandle,

SQLSMALLINT *ParameterCountPtr);

Function arguments

Table 120. SQLNumParams arguments



SQLSMALLINT * ParameterCountPtr Output Number of parameters in the statement.

Usage

This function can only be called after the statement that is associated with StatementHandle has beenprepared. If the statement does not contain any parameter markers, ParameterCountPtr is set to 0.

An application can call this function to determine how many SQLBindParameter() calls are necessary forthe SQL statement associated with the statement handle.


Error conditions

Table 121. SQLNumParams SQLSTATEs




HY008 Operation canceled

HY009 Argument value that is not valid ParameterCountPtr is null.

HY010 Function sequence error This function is called before SQLPrepare() is called for thespecified StatementHandle

The function is called while in a data-at-processing(SQLParamData(), SQLPutData()) operation.




SQLNumParams


Restrictions

None.

Example

Refer to the example in “SQLNativeSql - Get native SQL text” on page 188.

Referencesv “SQLBindParam - Bind a buffer to a parameter marker” on page 47v “SQLPrepare - Prepare a statement” on page 200

SQLNumParams


SQLNumResultCols - Get number of result columnsSQLNumResultCols() returns the number of columns in the result set associated with the input statementhandle.

SQLPrepare() or SQLExecDirect() must be called before calling this function.

After calling this function, you can call SQLDescribeCol(), SQLColAttribute(), SQLBindCol(), orSQLGetData().

SyntaxSQLRETURN SQLNumResultCols (SQLHSTMT hstmt,

SQLSMALLINT *pccol);

Function arguments

Table 122. SQLNumResultCols arguments



SQLSMALLINT * pccol Output Number of columns in the result set.

Usage

The function sets the output argument to zero if the last statement processed on the input statementhandle is not a SELECT.


Diagnostics

Table 123. SQLNumResultCols SQLSTATEs







pcbCol is a null pointer.

HY010 Function sequence error The function is called before calling SQLPrepare orSQLExecDirect for the hstmt.

S1013 * Memory managementproblem.


Referencesv “SQLBindCol - Bind a column to an application variable” on page 36v “SQLColAttributes - Obtain column attributes” on page 69v “SQLDescribeCol - Describe column attributes” on page 85

SQLNumResultCols


v “SQLExecDirect - Execute a statement directly” on page 102v “SQLGetCol - Retrieve one column of a row of the result set” on page 126v “SQLPrepare - Prepare a statement” on page 200

SQLNumResultCols


SQLParamData - Get next parameter for which a data value is neededSQLParamData() is used with SQLPutData() to send long data in pieces. It can also be used to sendfixed-length data.

SyntaxSQLRETURN SQLParamData (SQLHSTMT hstmt,

SQLPOINTER *prgbValue);

Function arguments

Table 124. SQLParamData arguments



SQLPOINTER * prgbValue Output Pointer to the value of the rgbValueargument specified on the SQLSetParamcall.

Usage

SQLParamData() returns SQL_NEED_DATA if there is at least one SQL_DATA_AT_EXEC parameter forwhich data still has not been assigned. This function returns an application defined value in prgbValuesupplied by the application during the previous SQLBindParam() call. SQLPutData() is called one or moretimes to send the parameter data. SQLParamData() is called to signal that all the data has been sent for thecurrent parameter and to advance to the next SQL_DATA_AT_EXEC parameter. SQL_SUCCESS isreturned when all the parameters have been assigned data values and the associated statement has beenprocessed successfully. If any errors occur during or before actual statement processing, SQL_ERROR isreturned.

If SQLParamData() returns SQL_NEED_DATA, then only SQLPutData() or SQLCancel() calls can be made.All other function calls using this statement handle fail. In addition, all function calls referencing theparent hdbc of hstmt fail if they involve changing any attribute or state of that connection. Thosefollowing function calls on the parent hdbc are also not permitted:v SQLAllocConnect()v SQLAllocHandle()v SQLAllocStmt()v SQLSetConnectOption()

Should they be called during an SQL_NEED_DATA sequence, these functions return SQL_ERROR withSQLSTATE of HY010 and the processing of the SQL_DATA_AT_EXEC parameters is not affected.

Return codesv SQL_SUCCESSv SQL_SUCCESS_WITH_INFOv SQL_ERRORv SQL_INVALID_HANDLEv SQL_NEED_DATA

Diagnostics

SQLParamData() can return any SQLSTATE returned by the SQLExecDirect() and SQLExecute() functions.In addition, the following diagnostics can also be generated:

SQLParamData


Table 125. SQLParamData SQLSTATEs




The argument prgbValue is a null pointer.

HY010 Function sequence error SQLParamData() is called out of sequence. This call isonly valid after an SQLExecDirect() or an SQLExecute(),or after an SQLPutData() call.



HYDE0 No data at processingvalues pending

Even though this function is called after anSQLExecDirect() or an SQLExecute() call, there are noSQL_DATA_AT_EXEC parameters (remaining) toprocess.

SQLParamData


SQLParamOptions - Specify an input array for a parameterSQLParamOptions() provides the ability to set multiple values for each parameter set bySQLBindParameter(). This allows the application to run INSERT, UPDATE, DELETE, and MERGEstatements providing multiple sets of arguments on a single call to SQLExecute() or SQLExecDirect().

SyntaxSQLRETURN SQLParamOptions (SQLHSTMT StatementHandle,

SQLINTEGER Crow,SQLINTEGER *FetchOffsetPtr);

Function arguments

Table 126. SQLParamOptions arguments



SQLINTEGER Crow Input Number of values for each parameter. If this isgreater than 1, then the rgbValue argument inSQLBindParameter() points to an array ofparameter values, and pcbValue points to anarray of lengths.

SQLINTEGER * FetchOffsetPtr Output(deferred)

Not currently used.

Usage

This function can be used with SQLBindParameter() to set up a multiple-row INSERT statement, or toprocess UPDATE, DELETE, and MERGE statements with multiple sets of parameter values. It is assumedthat the storage containing the data which represents the parameters is allocated and available to CLI.This data can be organized in a either a row-wise or a column-wise fashion. Row-wise binding is theterm used for the case where all the data for the first row is contiguous, followed by all the data for thenext row, and so on. Column-wise binding is used to describe the case where the data for each individualparameter marker is contiguous. For this case, each parameter marker's data can be provided in an arraythat does not need to be contiguous with data for the other parameter markers. The SQLBindParameter()function should be used to bind all of the input parameter types and lengths.

Here is an example of the set up necessary for a multiple-row statement with row-wise binding. In thiscase, the addresses provided on SQLBindParameter() are used to reference the first row of data. Allsubsequent rows of data are referenced by incrementing those addresses by the length of the entirerow.For instance, the application intends to insert 100 rows of data into a table, and each row contains a4-byte integer value, followed by a 10-byte character value. To do this, the application allocates 1400 bytesof storage, and fills each 14-byte piece of storage with the appropriate data for the row.

Also, the indicator pointer passed on the SQLBindParameter() must reference an 800-byte piece of storage(100 rows x 2 columns x 4 bytes for each indicator). The indicator array is used to pass in NULL valuesfor the corresponding parameter marker and row. This storage is also row-wise, so the first 8 bytes arethe 2 indicators for the first row, followed by the 2 indicators for the next row, and so on. TheSQLParamOptions() function is used by the application to specify how many rows of pararmeter valuesare provided.

The maximum number of database rows that can be specified in a multiple-row insert operation is 32,000.Therefore, SQLParamOptions allows only 32,767 rows to be specified at a time. Any additional rows needto be rebound and re-executed.

SQLParamOptions


SQLSetStmtAttr () provides an alternative means of setting the number of rows for a multiple-rowstatement using the SQL_ATTR_PARAMSET_SIZE option.


Error conditions

Table 127. SQLParamOptions SQLSTATEs


HY009 Argument value that is not valid The value in the argument Crow is less than 1.


Restrictions

None.

Referencesv “SQLBindParam - Bind a buffer to a parameter marker” on page 47v “SQLMoreResults - Determine whether there are more result sets” on page 186

SQLParamOptions


SQLPrepare - Prepare a statementSQLPrepare() associates an SQL statement with the input statement handle and sends the statement tothe DBMS to be prepared. The application can reference this prepared statement by passing the statementhandle to other functions.

If the statement handle has been used with a SELECT statement, SQLFreeStmt() must be called to closethe cursor, before calling SQLPrepare().

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLPrepareW() . Refer to “Unicode in Db2 for i CLI” on page 307 formore information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLPrepare (SQLHSTMT hstmt,

SQLCHAR *szSqlStr,SQLINTEGER cbSqlStr);

Function arguments

Table 128. SQLPrepare arguments


SQLHSTMT hstmt Input Statement handle. There must not be anopen cursor associated with hstmt.

SQLCHAR * szSqlStr Input SQL statement string.

SQLINTEGER cbSqlStr Input Length of contents of szSqlStr argument.

This must be set to either the exact length ofthe SQL statement in szSqlstr, or to SQL_NTSif the statement text is null-terminated.

Usage

As soon as a statement has been prepared using SQLPrepare(), the application can request informationabout the format of the result set (if it is a SELECT statement) by calling:v SQLNumResultCols()

v SQLDescribeCol()

v SQLColAttribute()

A prepared statement can be processed once, or multiple times by calling SQLExecute(). The SQLstatement remains associated with the statement handle until the handle is used with anotherSQLPrepare(), SQLExecDirect(), SQLColumns(), SQLSpecialColumns(), SQLStatistics(), or SQLTables().

The SQL statement string might contain parameter markers. A parameter marker is represented by a "?"character, and indicates a position in the statement where the value of an application variable is to besubstituted, when SQLExecute() is called. SQLBindParam() is used to bind (or associate) an applicationvariable to each parameter marker, and to indicate if any data conversion should be performed at thetime the data is transferred.

The SQL statement cannot be a COMMIT or ROLLBACK. SQLTransact() must be called to issueCOMMIT or ROLLBACK.

If the SQL statement is a positioned DELETE or a Positioned UPDATE, the cursor referenced by thestatement must be defined on a separate statement handle under the same connection handle.

SQLPrepare



Diagnostics

Table 129. SQLPrepare SQLSTATEs


24000 Cursor state that is not valid There is an open cursor on the specified hstmt.

37xxx Syntax error or accessviolation

szSqlStr contained one or more of the followingstatements:

v A COMMIT

v A ROLLBACK

v An SQL statement that the connected database servercannot prepare

v A statement containing a syntax error



szSqlStr is a null pointer.

The argument cbSqlStr is less than 1, but not equal toSQL_NTS.





Note: Not all Database Management Systems (DBMSs) report all of the above diagnostic messages atprepare time. Therefore an application must also be able to handle these conditions when callingSQLExecute().

Example


Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./*************************************************************************** file = prepare.c**** Example of preparing then repeatedly executing an SQL statement.**** Functions used:**** SQLAllocConnect SQLFreeConnect** SQLAllocEnv SQLFreeEnv** SQLAllocStmt SQLFreeStmt** SQLConnect SQLDisconnect**** SQLBindCol SQLFetch** SQLTransact SQLError

SQLPrepare


** SQLPrepare SQLSetParam** SQLExecute**************************************************************************/

#include <stdio.h>#include <string.h>#include <stdlib.h>#include "sqlcli.h"





int check_error (SQLHENV henv,SQLHDBC hdbc,SQLHSTMT hstmt,SQLRETURN rc);




{SQLHSTMT hstmt;SQLCHAR sqlstmt[]="SELECT deptname, location from org where division = ?";SQLCHAR deptname[15],

location[14],division[11];

SQLINTEGER rlength,plength;



/* prepare statement for multiple use */rc = SQLPrepare(hstmt, sqlstmt, SQL_NTS);if (rc != SQL_SUCCESS )


/* bind division to parameter marker in sqlstmt */rc = SQLSetParam(hstmt, 1, SQL_CHAR, SQL_CHAR, 10, 10, division,

&plength);if (rc != SQL_SUCCESS )


/* bind deptname to first column in the result set */rc = SQLBindCol(hstmt, 1, SQL_CHAR, (SQLPOINTER) deptname, 15,

SQLPrepare



check_error (henv, hdbc, hstmt, rc);rc = SQLBindCol(hstmt, 2, SQL_CHAR, (SQLPOINTER) location, 14,



printf("\nEnter Division Name or ’q’ to quit:\n");printf("(Eastern, Western, Midwest, Corporate)\n");gets(division);plength = SQL_NTS;

while(division[0] != ’q’){

rc = SQLExecute(hstmt);if (rc != SQL_SUCCESS )


printf("Departments in %s Division:\n", division);printf("DEPTNAME Location\n");printf("-------------- -------------\n");


printf("%-14.14s %-13.13s \n", deptname, location);}if (rc != SQL_NO_DATA_FOUND )

check_error (henv, hdbc, hstmt, rc);SQLFreeStmt(hstmt, SQL_CLOSE);printf("\nEnter Division Name or ’q’ to quit:\n");printf("(Eastern, Western, Midwest, Corporate)\n");gets(division);

}}

rc = SQLTransact(henv, hdbc, SQL_ROLLBACK);if (rc != SQL_SUCCESS )



}/* end main */

Referencesv “SQLColAttributes - Obtain column attributes” on page 69v “SQLDescribeCol - Describe column attributes” on page 85v “SQLExecDirect - Execute a statement directly” on page 102v “SQLExecute - Execute a statement” on page 104v “SQLNumResultCols - Get number of result columns” on page 194

SQLPrepare


SQLPrimaryKeys - Get primary key columns of a tableSQLPrimaryKeys() returns a list of column names that comprise the primary key for a table. Theinformation is returned in an SQL result set, which can be retrieved using the same functions that areused to process a result set that is generated by a query.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLPrimaryKeysW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLPrimaryKeys (SQLHSTMT StatementHandle,

SQLCHAR *CatalogName,SQLSMALLINT NameLength1,SQLCHAR *SchemaName,SQLSMALLINT NameLength2,SQLCHAR *TableName,SQLSMALLINT NameLength3);

Function arguments

Table 130. SQLPrimaryKeys arguments



SQLCHAR * CatalogName Input Catalog qualifier of a 3 part table name.

This must be a NULL pointer or a zero lengthstring.

SQLSMALLINT NameLength1 Input Length of CatalogName.

SQLCHAR * SchemaName Input Schema qualifier of table name.


SQLCHAR * TableName Input Table name.


Usage

SQLPrimaryKeys() returns the primary key columns from a single table. Search patterns cannot be used tospecify the schema qualifier or the table name.

The result set contains the columns that are listed in Table 131, ordered by TABLE_CAT, TABLE_SCHEM,TABLE_NAME, and ORDINAL_POSITION.

Because calls to SQLPrimaryKeys() in many cases map to a complex and, thus, expensive query againstthe system catalog, they should be used sparingly, and the results saved rather than repeating calls.


Table 131. Columns returned by SQLPrimaryKeys


1 TABLE_CAT VARCHAR (128) The current server.

2 TABLE_SCHEM VARCHAR (128) The name of the schema containing TABLE_NAME.

SQLPrimaryKeys


Table 131. Columns returned by SQLPrimaryKeys (continued)


3 TABLE_NAME VARCHAR (128) notNULL

Name of the specified table.

4 COLUMN_NAME VARCHAR (128) notNULL

Primary Key column name.

5 KEY_SEQ SMALLINT not NULL Column sequence number in the primary key, starting with 1.

6 PK_NAME VARCHAR(128) Primary key identifier. NULL if not applicable to the data source.

Note: The column names used by Db2 for i CLI follow the X/Open CLI CAE specification style. The column types,contents and order are identical to those defined for the SQLPrimaryKeys() result set in ODBC.

If the specified table does not contain a primary key, an empty result set is returned.


Error conditions

Table 132. SQLPrimaryKeys SQLSTATEs









The internal descriptor cannot be addressed or allocated, or itcontains a value that is not valid .



HYC00 Driver not capable Db2 for i CLI does not support catalog as a qualifier for tablename.


Restrictions

None.

Referencesv “SQLForeignKeys - Get the list of foreign key columns” on page 116v “SQLStatistics - Get index and statistics information for a base table” on page 259

SQLPrimaryKeys


SQLProcedureColumns - Get input/output parameter information for aprocedureSQLProcedureColumns() returns a list of input and output parameters associated with a procedure. Theinformation is returned in an SQL result set, which can be retrieved using the same functions that areused to process a result set that is generated by a query.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLProcedureColumnsW(). Refer to “Unicode in Db2 for i CLI” onpage 307 for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLProcedureColumns(SQLHSTMT StatementHandle,

SQLCHAR *CatalogName,SQLSMALLINT NameLength1,SQLCHAR *SchemaName,SQLSMALLINT NameLength2,SQLCHAR *ProcName,SQLSMALLINT NameLength3,SQLCHAR *ColumnName,SQLSMALLINT NameLength4);

Function arguments

Table 133. SQLProcedureColumns arguments



SQLCHAR * CatalogName Input Catalog qualifier of a 3 part procedure name.

This must be a NULL pointer or a zero lengthstring.


SQLCHAR * SchemaName Input Buffer that might contain a pattern-value toqualify the result set by schema name.

For DB2 for z/OS and OS/390® V 4.1, all thestored procedures are in one schema; the onlyacceptable value for the SchemaName argumentis a null pointer. For DB2, SchemaName cancontain a valid pattern value.


SQLCHAR * ProcName Input Buffer that might contain a pattern-value toqualify the result set by procedure name.

SQLSMALLINT NameLength3 Input Length of ProcName.

SQLCHAR * ColumnName Input Buffer that might contain a pattern-value toqualify the result set by parameter name. Thisargument is to be used to further qualify theresult set already restricted by specifying anon-empty value for ProcName orSchemaName.

SQLSMALLINT NameLength4 Input Length of ColumnName.

SQLProcedureColumns


Usage

Db2 for i CLI returns information about the input, input and output, and output parameters associatedwith the stored procedure, but cannot return information about the descriptor for any result setsreturned.

SQLProcedureColumns() returns the information in a result set, ordered by PROCEDURE_CAT,PROCEDURE_SCHEM, PROCEDURE_NAME, and COLUMN_TYPE. Table 134 lists the columns in theresult set. Applications should be aware that columns beyond the last column might be defined in futurereleases.

Because calls to SQLProcedureColumns() in many cases map to a complex and thus expensive queryagainst the system catalog, they should be used sparingly, and the results saved rather than repeatingcalls.

Special support was added to handle a keyword "*LIBL" in the SchemaName argument. Specifying thiskeyword will tell SQLStatistics to use the schema's on the library list to qualify the search criteria forretrieving index information for tables. The highest library on the library list hierarchy that matches thesearch criteria will be used. Also, system naming must be in effect for this support to be honored. Thefollowing behavior will occur when different connections are used:v When SQL Server Mode is used, the SQLProcedureColumns() API will use the library list of the initial

thread within the associated QSQSRVR job when processing the '*LIBL' request.v When SQL Server Mode is not used, the SQLProcedureColumns() API will use the library list of the

current thread when processing the '*LIBL' request.

Table 134. Columns returned by SQLProcedureColumns


1 PROCEDURE_CAT VARCHAR(128) The current server.

2 PROCEDURE_SCHEM VARCHAR(128) The name of the schema containingPROCEDURE_NAME.

3 PROCEDURE_NAME VARCHAR(128) Name of the procedure.

4 COLUMN_NAME VARCHAR(128) Name of the parameter.

5 COLUMN_TYPE SMALLINT not NULL This identifies the type information associated withthis row. The values can be:

v SQL_PARAM_TYPE_UNKNOWN – the parametertype is unknown.Note: This is not returned.

v SQL_PARAM_INPUT – this parameter is an inputparameter.

v SQL_PARAM_INPUT_OUTPUT – this parameter isan input / output parameter.

v SQL_PARAM_OUTPUT – this parameter is anoutput parameter.

v SQL_RETURN_VALUE – the procedure column isthe return value of the procedure.

Note: This is not returned.

v SQL_RESULT_COL – this parameter is actually acolumn in the result set.

Note: This is not returned.

6 DATA_TYPE INTEGER not NULL SQL data type.

7 TYPE_NAME VARCHAR(128) not NULL Character string representing the name of the datatype corresponding to DATA_TYPE.

SQLProcedureColumns


|||

Table 134. Columns returned by SQLProcedureColumns (continued)


8 COLUMN_SIZE INTEGER If the DATA_TYPE column value denotes a characteror binary string, then this column contains themaximum length in bytes; if it is a graphic (DBCS)string, this is the number of double byte charactersfor the parameter.

For date, time, timestamp data types, this is the totalnumber of bytes required to display the value whenconverted to character.

For numeric data types, this is either the total numberof digits, or the total number of bits allowed in thecolumn, depending on the value in theNUM_PREC_RADIX column in the result set.

9 BUFFER_LENGTH INTEGER The maximum number of bytes for the associated Cbuffer to store data from this parameter ifSQL_C_DEFAULT were specified on theSQLBindCol(), SQLGetData() and SQLBindParameter()calls. This length excludes any null-terminator. Forexact numeric data types, the length accounts for thedecimal and the sign.

10 DECIMAL_DIGITS SMALLINT The scale of the parameter. NULL is returned for datatypes where scale is not applicable.

11 NUM_PREC_RADIX SMALLINT Either 10 or 2 or NULL. If DATA_TYPE is anapproximate numeric data type, this column containsthe value 2, then the COLUMN_SIZE columncontains the number of bits allowed in the parameter.

If DATA_TYPE is an exact numeric data type, thiscolumn contains the value 10 and theCOLUMN_SIZE and DECIMAL_DIGITS columnscontain the number of decimal digits allowed for theparameter.

For numeric data types, the Database ManagementSystem (DBMS) can return a NUM_PREC_RADIX ofeither 10 or 2.

NULL is returned for data types where radix is notapplicable.

12 NULLABLE SMALLINT not NULL 'SQL_NO_NULLS' if the parameter does not acceptNULL values.

'SQL_NULLABLE' if the parameter accepts NULLvalues.

13 REMARKS NVARCHAR(2000) Contains descriptive information about the parameter.

SQLProcedureColumns


|||

Table 134. Columns returned by SQLProcedureColumns (continued)


14 COLUMN_DEF DBCLOB(64K) The default value of the column.

If NULL is specified as the default value, then thiscolumn is the word NULL, not enclosed in quotationmarks. If the default value cannot be representedwithout truncation, then this column containsTRUNCATED, with no enclosing single quotationmarks. If no default value is specified, then thiscolumn is NULL.

The value of COLUMN_DEF can be used ingenerating a new column definition, except when itcontains the value TRUNCATED.

15 SQL_DATA_TYPE SMALLINT not NULL The value of the SQL data type as it appears in theSQL_DESC_TYPE field of the descriptor. This columnis the same as the DATA_TYPE column except fordatetime data types (Db2 for i CLI does not supportinterval data types).

For datetime data types, the SQL_DATA_TYPE fieldin the result set is SQL_DATETIME, and theSQL_DATETIME_SUB field returns the subcode forthe specific datetime data type (SQL_CODE_DATE,SQL_CODE_TIME or SQL_CODE_TIMESTAMP).

16 SQL_DATETIME_SUB SMALLINT The subtype code for datetime data types. For allother data types this column returns a NULL(including interval data types which Db2 for i CLIdoes not support).

17 CHAR_OCTET_LENGTH INTEGER The maximum length in bytes of a character datatype column. For all other data types, this columnreturns a NULL.

18 ORDINAL_POSITION INTEGER not NULL This contains the ordinal position of the parametergiven by COLUMN_NAME in this result set. This isthe ordinal position of the argument to be providedon the CALL statement. The leftmost argument hasan ordinal position of 1.

19 IS_NULLABLE VARCHAR(3) v “NO” if the column does not include NULLs.

v “YES” if the column can include NULLs.

v zero-length string if nullability is unknown.

ISO rules are followed to determine nullability.

An ISO SQL-compliant DBMS cannot return anempty string.

The value returned for this column is different thanthe value returned for the NULLABLE column. (Seethe description of the NULLABLE column.)


SQLProcedureColumns


|||

|||||||

|||

|||

|

|

|

||

|||

Error conditions

Table 135. SQLProcedureColumns SQLSTATEs




42601 PARMLIST syntax error The PARMLIST value in the stored procedures catalog tablecontains a syntax error.








The value of one of the name length arguments is less than 0, butnot equal SQL_NTS.

HYC00 Driver not capable Db2 for i CLI does not support catalog as a qualifier for procedurename.

The connected data source does not support schema as a qualifierfor a procedure name.


Restrictions

SQLProcedureColumns() does not return information about the attributes of result sets that can bereturned from stored procedures.

If an application is connected to a DB2 server that does not provide support for a stored procedurecatalog, or does not provide support for stored procedures, SQLProcedureColumns() returns an emptyresult set.

Example

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./* From CLI sample proccols.c *//* ... */

printf("Enter Procedure Schema Name Search Pattern:\n");gets((char *)proc_schem.s);

printf("Enter Procedure Name Search Pattern:\n");gets((char *)proc_name.s);

rc = SQLProcedureColumns(hstmt, NULL, 0, proc_schem.s, SQL_NTS,proc_name.s, SQL_NTS, (SQLCHAR *)"%", SQL_NTS);


rc = SQLBindCol(hstmt, 2, SQL_C_CHAR, (SQLPOINTER) proc_schem.s, 129,&proc_schem.ind);


SQLProcedureColumns


rc = SQLBindCol(hstmt, 3, SQL_C_CHAR, (SQLPOINTER) proc_name.s, 129,&proc_name.ind);


rc = SQLBindCol(hstmt, 4, SQL_C_CHAR, (SQLPOINTER) column_name.s, 129,&column_name.ind);


rc = SQLBindCol(hstmt, 5, SQL_C_SHORT, (SQLPOINTER) &arg_type,0, &arg_type_ind);


rc = SQLBindCol(hstmt, 7, SQL_C_CHAR, (SQLPOINTER) type_name.s, 129,&type_name.ind);


rc = SQLBindCol(hstmt, 8, SQL_C_LONG, (SQLPOINTER) & length,0, &length_ind);


rc = SQLBindCol(hstmt, 10, SQL_C_SHORT, (SQLPOINTER) &scale,0, &scale_ind);


rc = SQLBindCol(hstmt, 13, SQL_C_CHAR, (SQLPOINTER) remarks.s, 255,&remarks.ind);


/* Fetch each row, and display */while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS) {

sprintf((char *)cur_name, "%s.%s", proc_schem.s, proc_name.s);if (strcmp((char *)cur_name, (char *)pre_name) != 0) {

printf("\n%s\n", cur_name);}strcpy((char *)pre_name, (char *)cur_name);printf(" %s", column_name.s);switch (arg_type){ case SQL_PARAM_INPUT : printf(", Input"); break;

case SQL_PARAM_OUTPUT : printf(", Output"); break;case SQL_PARAM_INPUT_OUTPUT : printf(", Input_Output"); break;

}printf(", %s", type_name.s);printf(" (%ld", length);if (scale_ind != SQL_NULL_DATA) {

printf(", %d)\n", scale);} else {

printf(")\n");}if (remarks.ind > 0 ) {

printf("(remarks), %s)\n", remarks.s);}

} /* endwhile */

References

“SQLProcedures - Get list of procedure names” on page 212

SQLProcedureColumns


SQLProcedures - Get list of procedure namesSQLProcedures() returns a list of procedure names that have been registered on the system and match thespecified search pattern.

The information is returned in an SQL result set, which can be retrieved using the same functions that areused to process a result set that is generated by a query.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLProceduresW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLProcedures (SQLHSTMT StatementHandle,

SQLCHAR *CatalogName,SQLSMALLINT NameLength1,SQLCHAR *SchemaName,SQLSMALLINT NameLength2,SQLCHAR *ProcName,SQLSMALLINT NameLength3);

Function arguments

Table 136. SQLProcedures arguments



SQLCHAR * CatalogName Input Catalog qualifier of a 3 part procedure name.

This must be a NULL pointer or a zero length string.


SQLCHAR * SchemaName Input Buffer that might contain a pattern-value to qualifythe result set by schema name.

For DB2 for z/OS and OS/390 V 4.1, all the storedprocedures are in one schema; the only acceptablevalue for the SchemaName argument is a null pointer.For DB2, SchemaName can contain a valid patternvalue.


SQLCHAR * ProcName Input Buffer that might contain a pattern-value to qualifythe result set by procedure name.

SQLSMALLINT NameLength3 Input Length of ProcName.

Usage

The result set returned by SQLProcedures() contains the columns listed in Table 137 on page 213 in theorder given. The rows are ordered by PROCEDURE_CAT, PROCEDURE_SCHEMA, andPROCEDURE_NAME.

Because calls to SQLProcedures() in many cases map to a complex and thus expensive query against thesystem catalog, use them sparingly, and save the results rather than repeating calls.


SQLProcedures


Table 137. Columns returned by SQLProcedures


1 PROCEDURE_CAT VARCHAR(128) The current server.

2 PROCEDURE_SCHEM VARCHAR(128) The name of the schema containing PROCEDURE_NAME.

3 PROCEDURE_NAME VARCHAR(128)NOT NULL

The name of the procedure.

4 NUM_INPUT_PARAMS INTEGER notNULL

Number of input parameters.

5 NUM_OUTPUT_PARAMS INTEGER notNULL

Number of output parameters.

6 NUM_RESULT_SETS INTEGER notNULL

Number of result sets returned by the procedure.

7 REMARKS VARCHAR(254) This contains the descriptive information about theprocedure.

8 PROCEDURE_TYPE SMALLINT Defines the procedure type:

v SQL_PT_UNKNOWN: It cannot be determined whetherthe procedure returns a value.

v SQL_PT_PROCEDURE: The returned object is aprocedure; that is, it does not have a return value.

v SQL_PT_FUNCTION: The returned object is a function;that is, it has a return value.

DB2 CLI always returns SQL_PT_PROCEDURE.

Note: The column names used by Db2 for i CLI follow the X/Open CLI CAE specification style. The column types,contents and order are identical to those defined for the SQLProcedures() result set in ODBC.


Error conditions

Table 138. SQLProcedures SQLSTATEs












SQLProcedures


Table 138. SQLProcedures SQLSTATEs (continued)


HYC00 Driver not capable Db2 for i CLI does not support catalog as a qualifier for procedurename.

The connected data source does not support schema as a qualifierfor a procedure name.


Restrictions

If an application is connected to a DB2 server that does not provide support for a stored procedurecatalog, or does not provide support for stored procedures, SQLProcedureColumns() returns an emptyresult set.

Example

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./* From CLI sample procs.c *//* ... */

printf("Enter Procedure Schema Name Search Pattern:\n");gets((char *)proc_schem.s);

rc = SQLProcedures(hstmt, NULL, 0, proc_schem.s, SQL_NTS, (SQLCHAR *)"%", SQL_NTS);CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;

rc = SQLBindCol(hstmt, 2, SQL_C_CHAR, (SQLPOINTER) proc_schem.s, 129,&proc_schem.ind);


rc = SQLBindCol(hstmt, 3, SQL_C_CHAR, (SQLPOINTER) proc_name.s, 129,&proc_name.ind);


rc = SQLBindCol(hstmt, 7, SQL_C_CHAR, (SQLPOINTER) remarks.s, 255,&remarks.ind);


printf("PROCEDURE SCHEMA PROCEDURE NAME \n");printf("------------------------- ------------------------- \n");/* Fetch each row, and display */while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS) {

printf("%-25s %-25s\n", proc_schem.s, proc_name.s);if (remarks.ind != SQL_NULL_DATA) {

printf(" (Remarks) %s\n", remarks.s);}

} /* endwhile */

References

“SQLProcedureColumns - Get input/output parameter information for a procedure” on page 206

SQLProcedures


SQLPutData - Pass data value for a parameterSQLPutData() is called following an SQLParamData() call returning SQL_NEED_DATA to supplyparameter data values. This function can be used to send large parameter values in pieces.

SyntaxSQLRETURN SQLPutData (SQLHSTMT hstmt,

SQLPOINTER rgbValue,SQLINTEGER cbValue);

Function arguments

Table 139. SQLPutData arguments



SQLPOINTER rgbValue Input Pointer to the actual data, or portion of data,for a parameter. The data must be in theform specified in the SQLBindParam() callthat the application used when specifyingthe parameter.

SQLINTEGER cbValue Input Length of rgbValue. This specifies the amountof data sent in a call to SQLPutData().

The amount of data can vary with each callfor a given parameter. The application canalso specify SQL_NTS or SQL_NULL_DATAfor cbValue.

cbValue is ignored for date and time datatypes, except SQL_TYPE_TIMESTAMP, andall numeric data types exceptSQL_NUMERIC and SQL_DECIMAL.

For cases where the C buffer type isSQL_CHAR or SQL_BINARY, or ifSQL_DEFAULT is specified as the C buffertype and the C buffer type default isSQL_CHAR or SQL_BINARY, this is thenumber of bytes of data in the rgbValuebuffer.

Usage

The application calls SQLPutData() after calling SQLParamData() on a statement in the SQL_NEED_DATAstate to supply the data values for an SQL_DATA_AT_EXEC parameter. Long data can be sent in piecesthrough repeated calls to SQLPutData(). After all the pieces of data for the parameter have been sent, theapplication again calls SQLParamData(). SQLParamData(). proceeds to the next SQL_DATA_AT_EXECparameter, or, if all parameters have data values, executes the statement.

SQLPutData() cannot be called more than once for a fixed length parameter.

After an SQLPutData() call, the only legal function calls are SQLParamData(), SQLCancel(), or anotherSQLPutData() if the input data is character or binary data. As with SQLParamData(), all other function callsusing this statement handle fail. In addition, all function calls referencing the parent hdbc of hstmt fail ifthey involve changing any attribute or state of that connection. For a list of these functions, see the Usagesection for “SQLParamData - Get next parameter for which a data value is needed” on page 196.

SQLPutData


||||

If one or more calls to SQLPutData() for a single parameter result in SQL_SUCCESS, attempting to callSQLPutData() with cbValue set to SQL_NULL_DATA for the same parameter results in an error withSQLSTATE of HY011. This error does not result in a change of state; the statement handle is still in a NeedData state and the application can continue sending parameter data.


Diagnostics

Some of the following diagnostics conditions might be reported on the final SQLParamData() call ratherthan at the time the SQLPutData() is called.

Table 140. SQLPutData SQLSTATEs


22001 Too much data The size of the data supplied to the current parameter bySQLPutData() exceeds the size of the parameter. The datasupplied by the last call to SQLPutData() is ignored.

01004 Data truncated The data sent for a numeric parameter is truncatedwithout the loss of significant digits.

Timestamp data sent for a date or time column istruncated.

Function returns with SQL_SUCCESS_WITH_INFO.



The argument rgbValue is a null pointer.

The argument rgbValue is not a NULL pointer and theargument cbValue is less than 0, but not equal toSQL_NTS or SQL_NULL_DATA.

HY010 Function sequence error The statement handle hstmt must be in a need data stateand must have been positioned on anSQL_DATA_AT_EXEC parameter through a previousSQLParamData() call.

SQLPutData


SQLReleaseEnv - Release all environment resourcesSQLReleaseEnv() invalidates and frees the environment handle. All Db2 for i CLI resources associatedwith the environment handle are freed.

SQLFreeConnect() must be called before calling this function.

This function is the last Db2 for i CLI step that an application needs to do before it ends.

SyntaxSQLRETURN SQLReleaseEnv (SQLHENV henv);

Function arguments

Table 141. SQLReleaseEnv arguments



Usage

If this function is called when there is still a valid connection handle, SQL_ERROR is returned, and theenvironment handle remains valid.


Diagnostics

Table 142. SQLReleaseEnv SQLSTATEs




HY010 Function sequence error There is an hdbc which is in allocated or connected state.Call SQLDisconnect and SQLFreeConnect for the hdbcbefore calling SQLReleaseEnv.



Example

Refer to the example in the “SQLAllocEnv - Allocate environment handle” on page 30.

References

“SQLFreeConnect - Free connection handle” on page 121

SQLReleaseEnv


SQLRowCount - Get row countSQLRowCount() returns the number of rows in a table affected by an UPDATE, INSERT, MERGE, SELECTfrom INSERT, or DELETE statement processed against the table, or a view based on the table.

SQLExecute() or SQLExecDirect() must be called before calling this function.

SyntaxSQLRETURN SQLRowCount (SQLHSTMT hstmt,

SQLINTEGER *pcrow);

Function arguments

Table 143. SQLRowCount arguments



SQLINTEGER * pcrow Output Pointer to location where the number ofrows affected is stored.

Usage

If the last processed statement referenced by the input statement handle is not an SELECT from INSERT,UPDATE, INSERT, MERGE, or DELETE statement, or if it is not processed successfully, then the functionsets the contents of pcrow to 0.

Any rows in other tables that might have been affected by the statement (for example, cascading deletes)are not included in the count.


Diagnostics

Table 144. SQLRowCount SQLSTATEs







pcrow is a null pointer.

HY010 Function sequence error The function is called before calling SQLExecute orSQLExecDirect for the hstmt.



SQLRowCount


Referencesv “SQLExecDirect - Execute a statement directly” on page 102v “SQLExecute - Execute a statement” on page 104v “SQLNumResultCols - Get number of result columns” on page 194

SQLRowCount


SQLSetConnectAttr - Set a connection attributeSQLSetConnectAttr() sets connection attributes for a particular connection.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLSetConnectAttrW(). Refer to “Unicode in Db2 for i CLI” on page307 for more information about Unicode support for Db2 for iCLI.

SyntaxSQLRETURN SQLSetConnectAttr (SQLHDBC hdbc,

SQLINTEGER fAttr,SQLPOINTER vParam,SQLINTEGER sLen);

Function arguments

Table 145. SQLSetConnectAttr arguments



SQLINTEGER fAttr Input Connect attribute to set, refer to Table 146 formore information.

SQLPOINTER vParam Input Value associated with fAttr. Depending onthe option, this can be a pointer to a 32-bitinteger value, or a character string.

SQLINTEGER sLen Input Length of input value, if it is a characterstring; otherwise, unused.

Usage

All connection and statement options set through the SQLSetConnectAttr() persist until SQLFreeConnect()is called or the next SQLSetConnectAttr() call.

The format of information set through vParam depends on the specified fAttr. The option information canbe either a 32-bit integer or a pointer to a null-terminated character string.

Table 146. Connect options

fAttr Contents

SQL_ATTR_2ND_LEVEL_TEXT A 32-bit integer value:

v SQL_TRUE – Error text obtained by calling SQLError()contains the complete text description of the error.

v SQL_FALSE – Error text obtained by calling SQLError()contains the first-level description of the error only.This is the default.

SQL_ATTR_AUTOCOMMIT A 32-bit value that sets the commit behavior for theconnection. These are the possible values:

v SQL_TRUE – Each SQL statement is automaticallycommitted as it is processed.

v SQL_FALSE – The SQL statements are notautomatically committed. If running with commitmentcontrol, changes must be explicitly committed or rolledback using either SQLEndTran() or SQLTransact(). Thisis the default.

SQLSetConnectAttr


Table 146. Connect options (continued)

fAttr Contents

SQL_ATTR_CONCURRENT_ACCESS_RESOLUTION A 32-bit integer value that specifies the concurrent accessresolution to use at the statement level. This attributeonly applies to the transaction isolation level of CursorStability or Read Stability, otherwise, it is ignored. Theseare the possible values :

v SQL_USE_CURRENTLY_COMMITTED -- Use currentlycommitted semantics.Db2 for iCLI flows "currentlycommitted" on every prepare, which means that thedatabase manager can use the currently committedversion of the data for applicable scans when the datais in the process of being updated or deleted. Rows inthe process of being inserted that have not beencommitted are skipped.

v SQL_WAIT_FOR_OUTCOME -- Wait for outcome. Db2for iCLI flows "wait for outcome" on every prepare,which causes the application to wait for conflicting rowlocks held by other users to be released whenencountering rows in the process of being updated.Rows in the process of being inserted or deleted rowsare not skipped.

v SQL_SKIP_LOCKED_DATA -- Skip locked data. Ratherthan waiting for conflicting row locks to be released,Db2 for i skips those rows which have conflicting locksheld by another user. As a result, skipped rows are notreturned in the result set returned to CLI.

CLI flows "skip locked data" on every prepare.

SQL_ATTR_CONN_SORT_SEQUENCE A 32-bit integer value that specifies the sort sequence touse with the connection. The possible values are:

v SQL_HEX_SORT_SEQUENCE – use *HEX sortsequence.

v SQL_JOB_SORT_SEQUENCE – Extract sort sequencefrom the job in which the CLI API requests are beingmade and use that sort sequence.

v SQL_JOBRUN_SORT_SEQUENCE – Extract sortsequence from the job in which the database access isdone and use that sort sequence.

The distinction between SQL_JOB_SORT_SEQUENCE andSQL_JOBRUN_SORT_SEQUENCE will only be seen whenrunning in server-mode. In that case, theSQL_JOBRUN_SORT_SEQUENCE will cause the effectivesort sequence of the server-mode job to be used, ratherthe front-end job where the CLI is being executed.

SQLSetConnectAttr



fAttr Contents

SQL_ATTR_COMMITorSQL_TXN_ISOLATION

A 32-bit value that sets the transaction-isolation level forthe current connection referenced by hdbc. The followingvalues are accepted by Db2 for i CLI, but each datasource might only support some of these isolation levels:

v SQL_TXN_NO_COMMIT – Commitment control is notused.

v SQL_TXN_READ_UNCOMMITTED – Dirty reads,nonrepeatable reads, and phantoms are possible. This isthe default isolation level.

v SQL_TXN_READ_COMMITTED – Dirty reads are notpossible. Non-repeatable reads and phantoms arepossible.

v SQL_TXN_REPEATABLE_READ – Dirty reads andnonrepeatable reads are not possible. Phantoms arepossible.

v SQL_TXN_SERIALIZABLE – Transactions areserializable. Dirty reads, non-repeatable reads, andphantoms are not possible.

In IBM terminology,

v SQL_TXN_READ_UNCOMMITTED is uncommittedread

v SQL_TXN_READ_COMMITTED is cursor stability

v SQL_TXN_REPEATABLE_READ is read stability

v SQL_TXN_SERIALIZABLE is repeatable read

For a detailed explanation of isolation levels, refer to theDb2 for i SQL Reference.

SQL_ATTR_CURRENT_IMPLICIT_XMLPARSE_OPTION A null-terminated character string that is the stringconstant used to set the CURRENT IMPLICITXMLPARSE OPTION special register.

Setting this attribute causes the SET CURRENT IMPLICITXMLPARSE OPTION SQL statement to be issued. If thisattribute is set before a connection has been established,the SET CURRENT IMPLICIT XMLPARSE OPTION SQLstatement will be issued when the connection is made.The valid values include:

v STRIP WHITESPACE In the XML Standard, whitespaceis space characters (U+0020), carriage returns(U+000D), line feeds (U+000A), or tabs (U+0009) thatare in the document to improve readability. Boundarywhitespace is whitespace characters that appearbetween elements. The STRIP WHITESPACE optionremoves whitespace.

v PRESERVE WHITESPACE Whitespace is not removed.

The default value of the CURRENT IMPLICITXMLPARSE OPTION special register is 'STRIPWHITESPACE'.

SQLSetConnectAttr



fAttr Contents

SQL_ATTR_DATE_FMT A 32-bit integer value:

v SQL_FMT_ISO – The International Organization forStandardization (ISO) date format yyyy-mm-dd is used.This is the default.

v SQL_FMT_USA – The United States date formatmm/dd/yyyy is used.

v SQL_FMT_EUR – The European date formatdd.mm.yyyy is used.

v SQL_FMT_JIS – The Japanese Industrial Standard dateformat yyyy-mm-dd is used.

v SQL_FMT_MDY – The date format mm/dd/yy is used.

v SQL_FMT_DMY – The date format dd/mm/yy is used.

v SQL_FMT_YMD – The date format yy/mm/dd is used.

v SQL_FMT_JUL – The Julian date format yy/ddd isused.

v SQL_FMT_JOB – The job default is used.

SQL_ATTR_DATE_SEP A 32-bit integer value:

v SQL_SEP_SLASH – A slash ( / ) is used as the dateseparator. This is the default.

v SQL_SEP_DASH – A dash ( - ) is used as the dateseparator.

v SQL_SEP_PERIOD – A period ( . ) is used as the dateseparator.

v SQL_SEP_COMMA – A comma ( , ) is used as the dateseparator.

v SQL_SEP_BLANK – A blank is used as the dateseparator.

v SQL_SEP_JOB – The job default is used.

Separators only apply to the followingSQL_ATTR_DATE_FMT attribute types:

v SQL_FMT_MDY

v SQL_FMT_DMY

v SQL_FMT_YMD

v SQL_FMT_JUL

SQL_ATTR_DBC_DEFAULT_LIB A character value that indicates the default library that isused for resolving unqualified file references.

SQL_ATTR_DBC_SYS_NAMING A 32-bit integer value:

v SQL_TRUE – Db2 for i CLI uses the IBM i systemnaming mode. Files are qualified using the slash (/)delimiter. Unqualified files are resolved using thelibrary list for the job.

v SQL_FALSE – Db2 for i CLI uses the default namingmode, which is SQL naming. Files are qualified usingthe period (.) delimiter. Unqualified files are resolvedusing either the default library or the current user ID.

SQLSetConnectAttr



fAttr Contents

SQL_ATTR_DECFLOAT_ROUNDING_MODE A 32-bit integer value:

v ROUND_CEILING

v ROUND_DOWN

v ROUND_FLOOR

v ROUND_HALF_DOWN

v ROUND_HALF_EVEN - This is the default.

v ROUND_HALF_UP

v ROUND_UP

Specifying this attribute causes the decimal floating pointrounding mode to be set in the following manner:

v For a local non-server mode connection, the local jobwill use the specified rounding mode.

v For a local server mode connection, the server job willuse the specified rounding mode.

v For a remote connection, the application requestor's jobwill use the rounding mode specified on the connectionattribute. Additionally, a SET CURRENT DECFLOATROUNDING MODE statement will be sent to theapplication server to set the initial rounding modethere.

Applications should avoid setting the rounding modeusing an SQL statement. Using the SET CURRENTDECFLOAT ROUNDING MODE statement will have noeffect on the current connection if a local connection hasbeen made. Executing the SQL statement for a remoteconnection will change the rounding mode for theapplication server, but will not affect the rounding modein the application requestor job.

SQL_ATTR_DECIMAL_SEP A 32-bit integer value:

v SQL_SEP_PERIOD – A period ( . ) is used as thedecimal separator. This is the default.

v SQL_SEP_COMMA – A comma ( , ) is used as thedecimal separator.


SQL_ATTR_EXTENDED_COL_INFO A 32-bit integer value:

v SQL_TRUE – Statement handles allocated against thisconnection handle can be used on SQLColAttribute()to retrieve extended column information, such as basetable, base schema, base column, and label.

v SQL_FALSE – Statement handles allocated against thisconnection handle cannot be used on theSQLColAttribute() function to retrieve extendedcolumn information. This is the default.

SQL_ATTR_EXTENDED_INDICATORS A 32-bit integer value:

v SQL_TRUE – Extended indicator support will beenabled. The user will be able to specify values tosignify UNASSIGNED and DEFAULT on theSQLBindParameter API.

v SQL_FALSE – Extended indicator support is notenabled. This is the default.

SQLSetConnectAttr



fAttr Contents

SQL_ATTR_FREE_LOCATORS A pointer to an array of 32-bit integer values containingthe locator handles to be freed. The sLen parameterindicates the number of locators to be freed.

A special value of '-99' for the sLen parameter indicatesthat all locators and locator storage that has beenallocated up to that point in the connection should befreed. A non-null pointer to the array of locator handlesmust still be passed, though it is not used.

SQL_ATTR_HEX_LITERALS A 32-bit integer value:

v SQL_HEX_IS_CHAR – Hexadecimal constants aretreated as character data. This is the default.

v SQL_HEX_IS_BINARY – Hexadecimal constants aretreated as binary data.

SQL_ATTR_INFO_ACCTSTR A character value used to identify the client accountingstring that is sent to the host database server at connecttime. Db2 for i servers support a length of up to 255characters.

When the value is being set, some servers might nothandle the entire length provided and might truncate thevalue.

To ensure that the data is converted correctly whentransmitted to a host system, use only the characters A toZ, 0 to 9, and the underscore (_) or period (.).

SQL_ATTR_INFO_APPLNAME A character value used to identify the client applicationname that is sent to the host database server at connecttime.Db2 for i servers support a length of up to 255characters.



SQL_ATTR_INFO_PROGRAMID A character value used to identify the client programname that is sent to the host database server at connecttime.Db2 for i servers support a length of up to 255characters.



SQLSetConnectAttr



fAttr Contents

SQL_ATTR_INFO_USERID A character value used to identify the client user-id thatis sent to the host database server at connect time.Db2 fori servers support a length of up to 255 characters.


This user-id is not to be confused with the authenticationuser-id. This user-id is for identification purposes onlyand is not used for any authorization.


SQL_ATTR_INFO_WRKSTNNAME A character value used to identify the client workstationname that is sent to the host database server at connecttime. Db2 for i servers support a length of up to 255characters.



SQL_ATTR_MAX_PRECISION An integer constant that is the maximum precision(length) that should be returned for the result data types.The value can be 31 or 63.

SQL_ATTR_MAX_SCALE An integer constant that is the maximum scale (numberof decimal positions to the right of the decimal point) thatshould be returned for the result data types. The valuecan range from 0 to the maximum precision.

SQL_ATTR_MIN_DIVIDE_SCALE Specify the minimum divide scale (number of decimalpositions to the right of the decimal point) that should bereturned for the result data types resulting from a divideoperation. The value can range from 0 to 9, not to exceedthe maximum scale. If 0 is specified, minimum dividescale is not used.

SQL_ATTR_OLD_MTADTA_BEHAVIOR A 32-bit integer value:

v SQL_TRUE – Run with the internal implementation formeta-data APIs as defined before V6R1M0.Compatibility with other DB2 CLI meta-data APIs isnot guaranteed if this option is set. This is notrecommended.

v SQL_FALSE – Run with the new internalimplementation for meta-data APIs. This is the default.

Meta-data APIs are functions that query the DB2 catalogssuch as SQLTables, SQLColumns(), and SQLStatistics().

SQLSetConnectAttr



fAttr Contents

SQL_ATTR_NULLT_ARRAY_RESULTS A 32-bit integer value:

v SQL_TRUE – DB2 CLI uses null termination to indicatethe length of output character string columns in arrayresult set data.

v SQL_FALSE – DB2 CLI does not null terminate outputcharacter string columns in array result set data. This isthe default.

SQL_ATTR_NULLT_OUTPUT_PARMS A 32-bit integer value:

v SQL_TRUE – DB2 CLI uses null termination to indicatethe length of SQL CALL statement output characterstring parameters.

v SQL_FALSE – DB2 CLI does not null terminate stringoutput parameters of SQL CALL statement . This is thedefault.

SQL_ATTR_QUERY_OPTIMIZE_GOAL A 32-bit integer value that tells the optimizer to behave ina specified way when processing a query:

v SQL_FIRST_IO – All queries are optimized with thegoal of returning the first page of output as fast aspossible. This goal works well when the output iscontrolled by a user who is most likely to cancel thequery after viewing the first page of output data.Queries coded with an OPTIMIZE FOR nnn ROWSclause honor the goal specified by the clause.

v SQL_ALL_IO – All queries are optimized with the goalof running the entire query to completion in theshortest amount of elapsed time. This is a good optionwhen the output of a query is being written to a file orreport, or the interface is queuing the output data.Queries coded with an OPTIMIZE FOR nnn ROWSclause honor the goal specified by the clause. This isthe default.

SQL_ATTR_SAVEPOINT_NAME A character value that indicates the savepoint name to beused by SQLEndTran() on the functionsSQL_SAVEPOINT_NAME_ROLLBACK orSQL_SAVEPOINT_NAME_RELEASE.

SQL_ATTR_SERVERMODE_SUBSYSTEM A null terminated character string that is used to specifythe subsystem in which the associated QSQSRVR jobswill run. The default behavior is to have the jobs run inthe QSYSWRK subsystem. If the value *SAME is used,then the QSQSRVR jobs will run in the same subsystemas the job using the CLI API.

SQL_ATTR_TIME_FMT A 32-bit integer value:

v SQL_FMT_ISO – The International Organization forStandardization (ISO) time format hh.mm.ss is used.This is the default.

v SQL_FMT_USA – The United States time formathh:mmxx is used, where xx is AM or PM.

v SQL_FMT_EUR – The European time format hh.mm.ssis used.

v SQL_FMT_JIS – The Japanese Industrial Standard timeformat hh:mm:ss is used.

v SQL_FMT_HMS – The hh:mm:ss format is used.

SQLSetConnectAttr


||

|||

|||

||

|||

|||


fAttr Contents

SQL_ATTR_TIME_SEP A 32-bit integer value:

v SQL_SEP_COLON – A colon ( : ) is used as the timeseparator. This is the default.

v SQL_SEP_PERIOD – A period ( . ) is used as the timeseparator.

v SQL_SEP_COMMA – A comma ( , ) is used as the timeseparator.

v SQL_SEP_BLANK – A blank is used as the timeseparator.


SQL_ATTR_TIMESTAMP_PREC A 32-bit integer value:

v SQL_TRUE – Timestamps are treated as fixed lengthtypes with a length of 26 and precision of 6. Thefollowing functions are affected :

– SQLBindCol - cbValueMax is ignored and alwaystreated as 26.

– SQLBindParam - cbParamDef is ignored and alwaystreated as 26. ibScale is ignored and always treatedas 6.

– SQLBindParameter -ColumnSize is ignored andalways treated as 26. DecimalDigits is ignored andalways treated as 6.

– SQLColAttribute - SQL_DESC_LENGTH is always26, SQL_DESC_PRECISION is always 26,SQL_DESC_SCALE is always 6, andSQL_DESC_DISPLAY_SIZE is either 26 or 27,depending on whether connection attributeSQL_ATTR_INCLUDE_NULL_IN_LEN has been set.

– SQLColAttributes - SQL_DESC_LENGTH is always26, SQL_DESC_PRECISION is always 26,SQL_DESC_SCALE is always 6, andSQL_DESC_DISPLAY_SIZE is either 26 or 27,depending on whether connection attributeSQL_ATTR_INCLUDE_NULL_IN_LEN has been set.

– SQLDescribeCol - pcbColDef is always 26 and pibScaleis always 6.

– SQLDescribeParam - ParameterSizePtr is always 26and DecimalDigitsPtr is always 6.

– SQLGetDescRec - prec is always 26 and scale isalways 6.

– SQLPutData - cbValue is ignored and treated as 26.

v SQL_FALSE - Timestamps are treated as varying lengthtypes with a length between 19 and 32 and acorresponding precision between 0 and 12. SQL_FALSEis the default.

SQLSetConnectAttr


||

|||

||

|||

|||

||||||

||||||

||

||

||

|

||||


fAttr Contents

SQL_ATTR_TXN_EXTERNAL A 32-bit integer value that must be SQL_TRUE to enablethe use of XA transaction setting in the CLI connection.SQL_ATTR_TXN_EXTERNAL must be set to SQL_TRUEto use the XA transaction options by theSQL_ATTR_TXN_INFO connection attribute.

The default is SQL_FALSE, which is not to enable XAtransaction support. However, as soon as transactionsupport is enabled for the connection, it cannot bedisabled. (Attempting to setSQL_ATTR_TXN_EXTERNAL to SQL_FALSE results in aCLI error.)

Further information as well as an example of use of theSQL_ATTR_TXN_EXTERNAL connection attribute can befound in “Example: Using the CLI XA transactionconnection attributes” on page 311.

SQLSetConnectAttr



fAttr Contents

SQL_ATTR_TXN_INFO A 32-bit integer value:

v SQL_TXN_CREATE – Create and start a transaction.This parallels the xa_start(TMNOFLAGS) XA option.

v SQL_TXN_END – End the specified transaction. Theuser is responsible to commit or roll back the work.This parallels the xa_end(TMSUCCESS) XA option.

v SQL_TXN_END_FAIL – End the specified transactionand mark the transaction as rollback required. Thisparallels the xa_end(TMFAIL) XA option.

v SQL_TXN_CLEAR – Suspend the transaction to workon a different transaction. This parallels thexa_end(TMSUSPEND) XA option.

v SQL_TXN_FIND – Find, retrieve, and use thenonsuspended transaction specified in vParam for thecurrent connection. This allows work to continue onthe open cursors for the previously nonsuspendedtransaction. This parallels the xa_start(TMJOIN) XAoption.

v SQL_TXN_RESUME – Find, retrieve, and use thesuspended transaction specified in vParam for thecurrent connection. This allows work to continue onthe open cursors for the previously suspendedtransaction. This parallels the xa_start(TMRESUME) XAoption.

Use of this connection attribute requires the user to berunning in server mode. Keep in mind, a user cannottoggle between a non-server mode and server modeenvironment.

The input argument vParam must point to aTXN_STRUCT object. This structure can be found in theheader file QSYSINC/h.SQLCLI.

The xa_info argument for the xa_open XA API mustinclude the THDCTL=C keyword and value when usingSQLSetConnectAttr()API instead of xa_start and xa_endto start and end XA transaction branch associations.

See XA transaction support for commitment control in theCommitment control topic for more information aboutXA transactions.

See XA APIs for more information.

See “Example: Using the CLI XA transaction connectionattributes” on page 311 for more information and anexample that shows how you can use theSQL_ATTR_TXN_INFO connection attribute.

When running XA calls through CLI, the return codesfrom CLI reflect the XA return code specifications. Thesevalues can be found in the XA specificationdocumentation, as well as in the XA.h include file. Notethat the return code values that are listed in the XAinclude file take precedence over the CLI return codevalues when calling XA through this connection attribute.

SQLSetConnectAttr



fAttr Contents

SQL_ATTR_UCS2 A 32-bit integer value:

v SQL_TRUE – When using statement handles allocatedagainst this connection handle for SQLPrepare() andSQLExecDirect() functions, the statement text is passedin the UCS-2 (Unicode) coded character set identifier(CCSID).

v SQL_FALSE – When using statement handles allocatedagainst this connection handle for SQLPrepare() andSQLExecDirect() functions, the statement text is passedin the job's CCSID. This is the default.

SQL_ATTR_XML_DECLARATION A 32-bit unsigned integer that specifies which elements ofan XML declaration are added to XML data when it isimplicitly serialized. This attribute does not affect theresult of the XMLSERIALIZE function. Set this attributeto the sum of each component required:

v 0: No declarations or byte order marks (BOMs) areadded to the output buffer.

v 1: A byte order mark (BOM) in the appropriateendianness is prepended to the output buffer if thetarget encoding is UTF-16 (Although a UTF-8 BOMexists, DB2 does not generate it, even if the targetencoding is UTF-8.)

v 2: A minimal XML declaration is generated, containingonly the XML version.

v 4: An encoding attribute that identifies the targetencoding is added to any generated XML declaration.Therefore, this setting only has effect when the settingof 2 is also included when computing the value of thisattribute.

Attempts to set any other value usingSQLSetConnectAttr() or SQLSetConnectOption()will resultin a CLI0191E (SQLSTATE HY024) error, and the valuewill remain unchanged. The default setting is 7, whichindicates that a BOM and an XML declaration containingthe XML version and encoding attribute are generatedduring implicit serialization. This setting affects anystatement handles allocated after the value is changed.Existing statement handles retain their original values..


Diagnostics

Table 147. SQLSetConnectAttr SQLSTATEs



SQLSetConnectAttr


Table 147. SQLSetConnectAttr SQLSTATEs (continued)



Given the fAttr value, a value that is not valid isspecified for the argument vParam.

An fAttr that is not valid value is specified.

Referencesv “SQLSetConnectOption - Set connection option” on page 233v “SQLSetStmtOption - Set statement option” on page 253

SQLSetConnectAttr


SQLSetConnectOption - Set connection optionSQLSetConnectOption() has been deprecated and replaced with SQLSetConnectAttr(). Although thisversion of Db2 for i CLI continues to support SQLSetConnectOption(), it is recommended that you beginusing SQLSetConnectAttr() in your Db2 for i CLI programs so that they conform to the latest standards.

SQLSetConnectOption() sets connection attributes for a particular connection.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLSetConnectOptionW(). Refer to “Unicode in Db2 for i CLI” onpage 307 for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLSetConnectOption (SQLHDBC hdbc,

SQLSMALLINT fOption,SQLPOINTER vParam);

Function arguments

Table 148. SQLSetConnectOption arguments



SQLSMALLINT fOption Input Connect option to set, refer to Table 146 onpage 220 for more information.

SQLPOINTER vParam Input Value associated with fOption. Depending onthe option, this can be a pointer to a 32-bitinteger value, or a character string.

Usage

The SQLSetConnectOption() provides many of the same attribute functions as SQLSetConnectAttr() beforeV5R3. However, SQLSetConnectOption() has since been deprecated, and support for all new attributefunctions has gone into SQLSetConnectAttr(). Users should migrate to the nondeprecated interface.

All connection and statement options set through the SQLSetConnectOption() persist untilSQLFreeConnect() is called or the next SQLSetConnectOption() call.

The format of information set through vParam depends on the specified fOption. The option informationcan be either a 32-bit integer or a pointer to a null-terminated character string.

Refer to Table 146 on page 220 for the appropriate connect options.

Note: Because SQLSetConnectOption() has been deprecated, not all the options listed in the table aresupported.


SQLSetConnectOption


Diagnostics

Table 149. SQLSetConnectOption SQLSTATEs




Given the fOption value, a value that is not valid isspecified for the argument vParam.

A fOption value that is not valid is specified.

HYC00 Driver not capable The specified fOption is not supported by Db2 for i CLIor the data source.

Given the specified fOptionvalue, the value specified forthe argument vParam is not supported.

References

“SQLSetConnectAttr - Set a connection attribute” on page 220

SQLSetConnectOption


SQLSetCursorName - Set cursor nameSQLSetCursorName() associates a cursor name with the statement handle. This function is optional becauseDb2 for i CLI implicitly generates a cursor name when needed.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLSetCursorNameW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for Db2 for i CLI.

SyntaxSQLRETURN SQLSetCursorName (SQLHSTMT hstmt,

SQLCHAR *szCursor,SQLSMALLINT cbCursor);

Function arguments

Table 150. SQLSetCursorName arguments



SQLCHAR * szCursor Input Cursor name.

SQLSMALLINT cbCursor Input Length of contents of szCursor argument.

Usage

Db2 for i CLI always generates and uses an internally generated cursor name when a SELECT statementis prepared or executed directly. SQLSetCursorName() allows an application-defined cursor name to beused in an SQL statement (a Positioned UPDATE or DELETE). Db2 for i CLI maps this name to aninternal name. SQLSetCursorName() must be called before an internal name is generated. The nameremains associated with the statement handle, until the handle is dropped. The name also remains afterthe transaction has ended, but at this point SQLSetCursorName() can be called to set a different name forthis statement handle.

Cursor names must follow the following rules:v All cursor names within the connection must be unique.v Each cursor name must be less than or equal to 128 characters in length. Any attempt to set a cursor

name longer than 128 characters results in an SQL0504 error.v Because a cursor name is considered an identifier in SQL, it must begin with an English letter (a-z,

A-Z) followed by any combination of digits (0-9), English letters or the underscore character (_).v Unless the input cursor name is enclosed in double quotation marks, all leading and trailing blanks

from the input cursor name string are removed.


SQLSetCursorName


Diagnostics

Table 151. SQLSetCursorName SQLSTATEs


34000 Cursor name that is notvalid

The cursor name specified by the argument szCursor isnot valid. The cursor name either begins with "SQLCUR"or "SQL_CUR" or violates either the driver or the datasource cursor naming rules (Must begin with a-z or A-Zfollowed by any combination of English letters, digits, orthe '_' character.

The cursor name specified by the argument szCursorexists.




szCursor is a null pointer.

The argument cbCursor is less than 1, but not equal toSQL_NTS.

HY010 Function sequence error The statement handle is not in allocated state.

SQLPrepare() or SQLExecDirect() is called beforeSQLSetCursorName().



References

“SQLGetCursorName - Get cursor name” on page 135

SQLSetCursorName


SQLSetDescField - Set a descriptor fieldSQLSetDescField() sets a field in a descriptor. SQLSetDescField() is a more extensible alternative to theSQLSetDescRec() function.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLSetDescFieldW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLSetDescField (SQLHDESC hdesc,

SQLSMALLINT irec,SQLSMALLINT fDescType,SQLPOINTER rgbDesc,SQLINTEGER bLen);

Function arguments

Table 152. SQLSetDescField arguments



SQLSMALLINT irec Input Record number from which the specifiedfield is to be retrieved.

SQLSMALLINT fDescType Input See Table 153.

SQLPOINTER rgbDesc Input Pointer to buffer.

SQLINTEGER bLen Input Length of descriptor buffer (rgbDesc).

Table 153. fDescType descriptor types


SQL_DESC_COUNT SMALLINT Set the number of records inthe descriptor. irec is ignored.

SQL_DESC_DATA_PTR SQLPOINTER Set the data pointer field forirec.

SQL_DESC_DATETIME_INTERVAL_CODE SMALLINT Set the interval code for recordswith a type of SQL_DATETIME

SQL_DESC_INDICATOR_PTR SQLPOINTER Set the indicator pointer fieldfor irec.

SQL_DESC_LENGTH_PTR SQLPOINTER Set the length pointer field forirec.

SQL_DESC_LENGTH INTEGER Set the length field of irec.

SQL_DESC_PRECISION SMALLINT Set the precision field of irec.

SQL_DESC_SCALE SMALLINT Set the scale field of irec.

SQL_DESC_TYPE SMALLINT Set the type field of irec.

Usage

Instead of requiring an entire set of arguments like SQLSetDescRec(), SQLSetDescField() specifies whichattribute you want to set for a specific descriptor record.

Although SQLSetDescField() allows for future extensions, it requires more calls to set the sameinformation than SQLSetDescRec() for each descriptor record.

SQLSetDescField



Diagnostics

Table 154. SQLGetDescField SQLSTATEs



The value specified for the argument fDescType or irec isnot valid.

The argument rgbValue is a null pointer.






SQLSetDescField


SQLSetDescRec - Set a descriptor recordSQLSetDescRec() sets all the attributes for a descriptor record. SQLSetDescRec() is a more concisealternative to the SQLSetDescField() function.

SyntaxSQLRETURN SQLSetDescRec (SQLHDESC hdesc,

SQLSMALLINT irec,SQLSMALLINT type,SQLSMALLINT subtype,SQLINTEGER length,SQLSMALLINT prec,SQLSMALLINT scale,SQLPOINTER data,SQLINTEGER *sLen,SQLINTEGER *indic);

Function arguments

Table 155. SQLSetDescRec arguments


SQLDESC hdesc Input Descriptor handle.

SQLSMALLINT irec Input Record number within the descriptor.

SQLSMALLINT type Input TYPE field for the record.

SQLSMALLINT subtype Input DATETIME_INTERVAL_CODE field forrecords whose TYPE is SQL_DATETIME.

SQLINTEGER length Input LENGTH field for the record.

SQLSMALLINT prec Input PRECISION field for the record.

SQLSMALLINT scale Input SCALE field for the record.

SQLPOINTER data Input (deferred) DATA_PTR field for the record.

SQLINTEGER * sLen Input (deferred) LENGTH_PTR field for the record.

SQLINTEGER * indic Input (deferred) INDICATOR_PTR field for the record.

Usage

Calling SQLSetDescRec() sets all the fields in a descriptor record in one call.


Diagnostics

Table 156. SQLSetDescRec SQLSTATEs



The value specified for the argument irec is less than 1.

A value that is not valid for another argument isspecified.

SQLSetDescRec


Table 156. SQLSetDescRec SQLSTATEs (continued)


HY016 Descriptor that is not valid The descriptor handle referred to an implementation rowdescriptor.




SQLSetDescRec


SQLSetEnvAttr - Set environment attributeSQLSetEnvAttr() sets an environment attribute for the current environment.

Syntax

An environment attribute cannot be set if a connection handle has been allocated. In order for theattribute to apply to the entire CLI environment, the environment attributes must be in place before thisinitial connection is made. An HY010 error code is returned otherwise.SQLRETURN SQLSetEnvAttr (SQLHENV henv,

SQLINTEGER Attribute,SQLPOINTER Value,SQLINTEGER StringLength);

Function arguments

Table 157. SQLSetEnvAttr arguments


SQLHEN henv Input Environment handle.

SQLINTEGER Attribute Input Environment attribute to set. Refer toTable 158 for more information.

SQLPOINTER Value Input Appropriate value for Attribute.

SQLINTEGER StringLength Input Length of Value in bytes if the attribute valueis a character string; if Attribute does notdenote a string, then Db2 for i CLI ignoresStringLength.

Usage

In environments where the current application may exist in the same job as other applications using CLI,connections attributes should be used instead of environment attributes. Otherwise, setting environmentattributes may cause the other application to behave unexpectedly. Ideally, the only environmentattributes that should be used are SQL_ATTR_ENVHNDL_COUNTER and SQL_ATTR_SERVER_MODE.

Table 158. Environment attributes

Attribute Contents

SQL_ATTR_DATE_FMT A 32-bit integer value:

v SQL_FMT_ISO – The International Organization forStandardization (ISO) date format yyyy-mm-dd is used.This is the default.

v SQL_FMT_USA – The United States date formatmm/dd/yyyy is used.

v SQL_FMT_EUR – The European date formatdd.mm.yyyy is used.

v SQL_FMT_JIS – The Japanese Industrial Standard dateformat yyyy-mm-dd is used.

v SQL_FMT_MDY – The date format mm/dd/yy is used.

v SQL_FMT_DMY – The date format dd/mm/yy is used.

v SQL_FMT_YMD – The date format yy/mm/dd is used.

v SQL_FMT_JUL – The Julian date format yy/ddd isused.

v SQL_FMT_JOB – The job default is used.

SQLSetEnvAttr


Table 158. Environment attributes (continued)

Attribute Contents

SQL_ATTR_DATE_SEP A 32-bit integer value:

v SQL_SEP_SLASH – A slash ( / ) is used as the dateseparator. This is the default.

v SQL_SEP_DASH – A dash ( - ) is used as the dateseparator.

v SQL_SEP_PERIOD – A period ( . ) is used as the dateseparator.

v SQL_SEP_COMMA – A comma ( , ) is used as the dateseparator.

v SQL_SEP_BLANK – A blank is used as the dateseparator.


Separators only apply to the followingSQL_ATTR_DATE_FMT attribute types:

v SQL_FMT_MDY

v SQL_FMT_DMY

v SQL_FMT_YMD

v SQL_FMT_JUL

SQL_ATTR_DECIMAL_SEP A 32-bit integer value:

v SQL_SEP_PERIOD – A period ( . ) is used as thedecimal separator. This is the default.

v SQL_SEP_COMMA – A comma ( , ) is used as thedecimal separator.


SQL_ATTR_DEFAULT_LIB A character value that indicates the default library that isused for resolving unqualified file references.

SQL_ATTR_ENVHNDL_COUNTER A 32-bit integer value:

v SQL_FALSE – Db2 for i CLI does not count the numberof times the environment handle is allocated. Therefore,the first call to free the environment handle and allassociated resources.

v SQL_TRUE – Db2 for i CLI keeps a counter of thenumber of times the environment handle is allocated.Each time the environment handle is freed, the counteris decremented. Only when the counter reaches zerodoes the Db2 for i CLI actually free the handle and allassociated resources. This allows nested calls toprograms using the CLI that allocate and free the CLIenvironment handle.

SQL_ATTR_ESCAPE_CHAR A character value that indicates the escape character to beused when specifying a search pattern in eitherSQLColumns( ) or SQLTables( ).

SQL_ATTR_ESCAPE_CHAR is only honored if theconnection attributeSQL_ATTR_OLD_MTADTA_BEHAVIOR is set toSQL_TRUE.

SQLSetEnvAttr



Attribute Contents

SQL_ATTR_FOR_FETCH_ONLY A 32-bit integer value:

v SQL_TRUE – Cursors are read-only and cannot be usedfor positioned update or delete operations. This is thedefault.

v SQL_FALSE – Cursors can be used for positionedupdates or delete operations.

The attribute SQL_ATTR_FOR_FETCH_ONLY can also beset for individual statements using SQLSetStmtAttr().

SQL_ATTR_INCLUDE_NULL_IN_LEN A 32-bit integer value:

v SQL_TRUE – If a null terminator exists, it will beincluded in the length value that is returned for outputcharacter information. To include the null terminator inthe actual output string, the environment attributeSQL_ATTR_OUTPUT_NTS must be set to SQL_TRUE.This is the default.

v SQL_FALSE – The null terminator, even if it exists, willnot be included in the length value that is returned foroutput character information.

SQL_ATTR_JOB_SORT_SEQUENCE A 32-bit integer value:

v SQL_TRUE – Db2 for i CLI uses the sort sequence thathas been set for the job.

v SQL_FALSE – Db2 for i CLI uses the default sortsequence, which is *HEX.

SQL_ATTR_NON_HEXCCSID A 32-bit integer value:

v SQL_TRUE – Db2 for i CLI set the job CCSID to the jobdefault CCSID if the job CCSID is set to 65535.

v SQL_FALSE – Db2 for i CLI does not change the jobCCSID. This is the default.

SQL_ATTR_OUTPUT_NTS A 32-bit integer value:

v SQL_TRUE – Db2 for i CLI uses null termination toindicate the length of output character strings. This isthe default.

v SQL_FALSE – Db2 for i CLI does not use nulltermination.

The CLI functions affected by this attribute are allfunctions called for the environment (and for anyconnections allocated under the environment) that havecharacter string parameters.

SQL_ATTR_REQUIRE_PROFILE A 32-bit integer value:

v SQL_TRUE – If in server mode, then a profile andpassword are required when running SQLConnect() andSQLDriverConnect() functions.

v SQL_FALSE – If profile is omitted on the SQLConnect()or SQLDriverConnect() function, then connection ismade using current user profile. This is the default.

SQLSetEnvAttr



Attribute Contents

SQL_ATTR_SERVER_MODE A 32-bit integer value:

v SQL_FALSE – Db2 for i CLI processes the SQLstatements of all connections within the same job. Allchanges compose a single transaction. This is thedefault mode of processing.

v SQL_TRUE – Db2 for i CLI processes the SQLstatements of each connection in a separate job. Thisallows multiple connections to the same data source,possibly with different user IDs for each connection. Italso separates the changes made under each connectionhandle into its own transaction. This allows eachconnection handle to be committed or rolled back,without impacting pending changes made under otherconnection handles. See “Running Db2 for i CLI inserver mode” on page 305 for more information.

SQL_ATTR_SYS_NAMING A 32-bit integer value:

v SQL_TRUE – Db2 for i CLI uses the IBM i systemnaming mode. Files are qualified using the slash (/)delimiter. Unqualified files are resolved using thelibrary list for the job.

v SQL_FALSE – Db2 for i CLI uses the default namingmode, which is SQL naming. Files are qualified usingthe period (.) delimiter. Unqualified files are resolvedusing either the default library or the current user ID.

SQL_ATTR_TIME_FMT A 32-bit integer value:

v SQL_FMT_ISO – The International Organization forStandardization (ISO) time format hh.mm.ss is used.This is the default.

v SQL_FMT_USA – The United States time formathh:mmxx is used, where xx is a.m. or p.m.

v SQL_FMT_EUR – The European time format hh.mm.ssis used.

v SQL_FMT_JIS – The Japanese Industrial Standard timeformat hh:mm:ss is used.

v SQL_FMT_HMS – The hh:mm:ss format is used.

SQL_ATTR_TIME_SEP A 32-bit integer value:

v SQL_SEP_COLON – A colon ( : ) is used as the timeseparator. This is the default.

v SQL_SEP_PERIOD – A period ( . ) is used as the timeseparator.

v SQL_SEP_COMMA – A comma ( , ) is used as the timeseparator.

v SQL_SEP_BLANK – A blank is used as the timeseparator.


SQLSetEnvAttr



Attribute Contents

SQL_ATTR_TRUNCATION_RTNC A 32-bit integer value:

v SQL_TRUE – CLI returns SQL_SUCCESS_WITH_INFOin the SQLFetch(),SQLExtendedFetch(), andSQLFetchScroll() return codes if truncation occurs.

v SQL_FALSE – CLI does not returnSQL_SUCCESS_WITH_INFO in the SQLFetch(),SQLExtendedFetch() , and SQLFetchScroll() returncodes if truncation occurs. This is the default.

SQL_ATTR_UTF8 A 32-bit integer value:

v SQL_FALSE – Character data is treated as being in thedefault job coded character set identifier (CCSID). Thisis the default.

v SQL_TRUE – Character data is treated as being in theUTF–8 CCSID (1208).


Diagnostics

Table 159. SQLSetEnvAttr SQLSTATEs


HY009 Parameter value that is notvalid

The specified Attribute is not supported by Db2 for i CLI.

Given specified Attributevalue, the value specified for theargument Value is not supported.

The argument pValue is a null pointer.

HY010 Function sequence error Connection handles are already allocated.

SQLSetEnvAttr


SQLSetParam - Set parameterSQLSetParam() has been deprecated and replaced by SQLBindParameter(). Although this version of Db2for i CLI continues to support SQLSetParam(), it is recommended that you begin usingSQLBindParameter() in your Db2 for i CLI programs so that they conform to the latest standards.

SQLSetParam() associates (binds) an application variable to a parameter marker in an SQL statement.When the statement is processed, the contents of the bound variables are sent to the database server. Thisfunction is also used to specify any required data conversion.

SyntaxSQLRETURN SQLSetParam (SQLHSTMT hstmt,

SQLSMALLINT ipar,SQLSMALLINT fCType,SQLSMALLINT fSqlType,SQLINTEGER cbParamDef,SQLSMALLINT ibScale,SQLPOINTER rgbValue,SQLINTEGER *pcbValue);

References

“SQLBindParameter - Bind a parameter marker to a buffer” on page 52

SQLSetParam


SQLSetStmtAttr - Set a statement attributeSQLSetStmtAttr() sets an attribute of a specific statement handle. To set an option for all statementhandles associated with a connection handle, the application can call SQLSetConnectOption().

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLSetStmtAttrW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLSetStmtAttr (SQLHSTMT hstmt,

SQLINTEGER fAttr,SQLPOINTER vParam,SQLINTEGER sLen);

Function arguments

Table 160. SQLSetStmtAttr arguments



SQLINTEGER fAttr Input Attribute to set. Refer to Table 161 for the listof settable statement attributes.

SQLPOINTER vParam Input Value associated with fAttr. vParam can be a32-bit integer value or a character string.

SQLINTEGER sLen Input Length of data if data is a character string;otherwise, unused.

Usage

Statement options for an hstmt remain in effect until they are changed by another call toSQLSetStmtAttr() or the hstmt is dropped by calling SQLFreeStmt() with the SQL_DROP option. CallingSQLFreeStmt() with the SQL_CLOSE, SQL_UNBIND, or SQL_RESET_PARAMS options does not reset thestatement options.

The format of information set through vParam depends on the specified fOption. The format of each isnoted in Table 161.

Table 161. Statement attributes

fAttr Contents

SQL_ATTR_APP_PARAM_DESC VParam must be a descriptor handle. The specifieddescriptor serves as the application parameter descriptorfor later calls to SQLExecute() and SQLExecDirect() onthe statement handle.

SQL_ATTR_APP_ROW_DESC VParam must be a descriptor handle. The specifieddescriptor serves as the application row descriptor forlater calls to SQLFetch() on the statement handle.

SQLSetStmtAttr



fAttr Contents

SQL_ATTR_BIND_TYPE This specifies whether row-wise or column-wise bindingis used.

v SQL_BIND_BY_ROW – Binding is row-wise. This is thedefault.

When using row-wise binding for a multiple row fetch,all of the data for a row is returned in contiguousstorage, followed by the data for the next row, and soon.

v SQL_BIND_BY_COLUMN – Binding is column-wise.

When using column-wise binding for a multiple rowfetch, all of the data for each column is returned incontiguous storage. The storage for each row need notbe contiguous. A different address is provided by theuser for each column in the result set, and it is theresponsibility of the user to ensure that each addresshas space for all the data to be retrieved.

SQL_ATTR_CURSOR_HOLD A 32-bit integer value that specifies if cursors opened forthis statement handle should be held.

v SQL_FALSE – An open cursor for this statement handleis closed on a commit or rollback operation. This is thedefault.

v SQL_TRUE – An open cursor for this statement handleis not closed on a commit or rollback operation.

SQL_ATTR_CURSOR_SCROLLABLE A 32-bit integer value that specifies if cursors opened forthis statement handle should be scrollable.

v SQL_FALSE – Cursors are not scrollable, andSQLFetchScroll() cannot be used against them. This isthe default.

v SQL_TRUE – Cursors are scrollable. SQLFetchScroll()can be used to retrieve data from these cursors.

SQL_ATTR_CURSOR_SENSITIVITY A 32-bit integer value that specifies whether cursorsopened for this statement handle make visible thechanges made to the result set by another cursor. SeeDECLARE CURSOR for a more precise definition of thefollowing options:

v SQL_UNSPECIFIED – Cursors on the statement handlemight make visible none, some, or all such changesdepending on the cursor type. This is the default.

v SQL_INSENSITIVE – All valid cursors on the statementhandle show the result set without reflecting anychanges made to it by any other cursor.

v SQL_SENSITIVE – All valid cursors on the statementhandle make visible all changes made to a result byanother cursor.

SQLSetStmtAttr



fAttr Contents

SQL_ATTR_CURSOR_TYPE A 32-bit integer value that specifies the behavior ofcursors opened for this statement handle.

v SQL_CURSOR_FORWARD_ONLY – Cursors are notscrollable, and the SQLFetchScroll() function cannot beused against them. This is the default.

v SQL_CURSOR_DYNAMIC – Cursors are scrollableexcept for insensitive cursor sensitivity. TheSQLFetchScroll() function can be used to retrieve datafrom these cursors.

v SQL_CURSOR_STATIC – Cursors are scrollable exceptfor sensitive cursor sensitivity. The SQLFetchScroll()function can be used to retrieve data from thesecursors.

SQL_ATTR_EXTENDED_COL_INFO A 32-bit integer value that specifies if cursors opened forthis statement handle should provide extended columninformation.

v SQL_FALSE – This statement handle cannot be used onthe SQLColAttribute() function to retrieve extendedcolumn information. This is the default. Setting thisattribute at the statement level overrides the connectionlevel setting of the attribute.

v SQL_TRUE – This statement handle can be used on theSQLColAttribute() function to retrieve extendedcolumn information, such as base table, base schema,base column, and label.

SQL_ATTR_FOR_FETCH_ONLY A 32-bit integer value that specifies whether cursorsopened for this statement handle should be read only:

v SQL_TRUE – Cursors are read-only and cannot be usedfor positioned update or delete operations. This is thedefault unless SQL_ATTR_FOR_FETCH_ONLYenvironment has been set to SQL_FALSE.

v SQL_FALSE – Cursors can be used for positionedupdate or delete operations.

SQL_ATTR_FULL_OPEN A 32-bit integer value that specifies if cursors opened forthis statement handle should be full open operations.

v SQL_FALSE – Opening a cursor for this statementhandle might use a cached cursor for performancereasons. This is the default.

v SQL_TRUE – Opening a cursor for this statementhandle always forces a full open operation of a newcursor.

SQL_ATTR_NUMBER_RESULTSET_ROWS_PTR A 32-bit integer * value the points to a buffer whichcontains the total number of rows available from theresult set. This attribute will only return a valid result ifthe cursor sensitivity is insensitive and the cursor type isstatic. Without these settings, the returned result will bezero. This value is set after a successful call toSQLExecute() or SQLExecDirect().

SQLSetStmtAttr



fAttr Contents

SQL_ATTR_PARAM_BIND_TYPE A 32-bit integer value:

v SQL_BIND_BY_ROW - Binding is row-wise. This is thedefault. When using row-wise binding for a multiplerow statements, all of the data for each row must becontiguous storage, followed by the data for the nextrow, and so on.

v SQL_BIND_BY_COLUMN - Binding is column-wise.When using column-wise binding for a multiple rowstatements, all of the data for each column is incontiguous storage. A different address is provided bythe user for each column in the statement, and it is theresponsibility of the user to ensure that each addresshas space for all the parameter data to be passed to thedatabase.

SQL_ATTR_PARAM_STATUS_PTR A 32-bit integer * value that points to an array of valuescontaining status information for each row of parametervalues. The status values are set after a call toSQLExecDirect() or SQLExecute(). This field is used onlyif SQL_ATTR_PARAMSET_SIZE is greater than 1. Thefollowing status values can be returned.

v SQL_PARAM_SUCCESS: The SQL statement wassuccessfully executed for this set of parameters.

v SQL_PARAM_SUCCESS_WITH_INFO: The SQLstatement was successfully executed for this set ofparameters; however, warning information wasreturned.

v SQL_PARAM_ERROR: There was an error inprocessing this set of parameters.

v SQL_PARAM_UNUSED: The parameter that was set isunused. This can occur if a previously set parametercaused an error which aborted further processing.

v SQL_PARAM_DIAG_UNAVAILABLE: This is notcurrently set by DB2 CLI.

This statement attribute can be set to a null pointer, inwhich case DB2 CLI does not return parameter statusvalues.

SQL_ATTR_PARAMS_PROCESSED_PTR A 32-bit integer * value that points to the current rownumber. As each row of parameters is processed this isset to the number of that row. If the call toSQLExecDirect() or SQLExecute() that fills in theSQLINTEGER buffer pointed to by this attribute does notreturn SQL_SUCCESS or SQL_SUCCESS_WITH_INFO,the contents of the buffer are undefined.

This statement attribute can be set to a null pointer, inwhich case DB2 CLI does not return the row number.

SQL_ATTR_PARAMSET_SIZE A 32-bit integer value that specifies the number of valuesto be associated with each parameter marker. If this isgreater that 1, the rgbValue argumentin SQLBindParameter() points to an array of parametervalues, and pcbValue points to an array of lengths. This isan alternative to setting a value size through theSQLParamOptions() API.

SQLSetStmtAttr



fAttr Contents

SQL_ATTR_ROW_BIND_TYPE A 32-bit integer value:

v SQL_BIND_BY_ROW - Binding is row-wise. This is thedefault. When using row-wise binding for a multiplerow fetch, all of the data for a row is returned incontiguous storage, followed by the data for the nextrow, and so on.

v SQL_BIND_BY_COLUMN - Binding is column-wise.When using column-wise binding for a multiple rowfetch, all the data for each column is returned incontiguous storage. The storage for each column neednot be contiguous. A different address is provided bythe user for each column in the result set, and it is theresponsibility of the user to ensure that each addresshas space for all the data to be retrieved.

SQL_ATTR_ROW_STATUS_PTR A 16-bit SMALLINT * value that points to an array ofstatus values at SQLFetchScroll(). The number ofelements must equal the number of rows in the row set(as defined by the SQL_ROWSET_SIZE attribute). Astatus value SQL_ROW_SUCCESS for each row fetched isreturned.

If the number of rows fetched is less than the number ofelements in the status array (that is, less than the row setsize), the remaining status elements are set toSQL_ROW_NOROW. The number of rows fetched isreturned in the output pointer. This can be set by theSQLSetStmtAttr attributeSQL_ATTR_ROWS_FETCHED_PTR.

Db2 for i CLI cannot detect whether a row has beenupdated or deleted since the start of the fetch. Therefore,the following ODBC defined status values are notreported:

v SQL_ROW_DELETED.

v SQL_ROW_UPDATED.

SQL_ATTR_ROWS_FETCHED_PTR A 32-bit integer * value that points to a buffer thatcontains the number of rows actually fetched bySQLFetchScroll(). If an error occurs during processing,the pointer points to the ordinal position of the row (inthe row set) that precedes the row where the erroroccurred. If an error occurs retrieving the first row, thepointer points to the value 0.

SQL_ATTR_ROWSET_SIZE A 32-bit integer value that specifies the number of rowsin the row set. This is the number of rows returned byeach call to SQLExtendedFetch(). The maximum value is32767. The default value is 1.


SQLSetStmtAttr


Diagnostics

Table 162. SQLStmtAttr SQLSTATEs




HY000 General error An error occurred for which there is no specificSQLSTATE and for which no implementation definedSQLSTATE is defined. The error message returned bySQLError in the argument szErrorMsg describes the errorand its cause.



Given the specified fAttr value, a value that is not validis specified for the argument vParam.

An fAttr value that is not valid is specified.

The argument vParam is a null pointer.

HY010 Function sequence error The function is called out of sequence.

HYC00 Driver not capable The driver or the data sources does not support thespecified option.

Referencesv “SQLFetchScroll - Fetch from a scrollable cursor” on page 114v “SQLSetStmtOption - Set statement option” on page 253

SQLSetStmtAttr


SQLSetStmtOption - Set statement optionSQLSetStmtOption() has been deprecated and replaced with SQLSetStmtAttr(). Although this version ofDb2 for i CLI continues to support SQLSetStmtOption(), it is recommended that you begin usingSQLSetStmtAttr() in your Db2 for i CLI programs so that they conform to the latest standards.

SQLSetStmtOption() sets an attribute of a specific statement handle. To set an option for all statementhandles associated with a connection handle, the application can call SQLSetConnectAttr(). See“SQLSetConnectAttr - Set a connection attribute” on page 220 for additional details.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLSetStmtOptionW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLSetStmtOption (SQLHSTMT hstmt,

SQLSMALLINT fOption,SQLPOINTER vParam);

Function arguments

Table 163. SQLSetStmtOption arguments



SQLSMALLINT fOption Input Option to set. Refer to Table 161 on page 247 for the listof settable statement options.

SQLPOINTER vParam Input Value associated with fOption. vParam can be a pointerto a 32-bit integer value or a character string.

Usage

The SQLSetStmtOption() provides many of the same attribute functions as SQLSetStmtAttr() before V5R3.However, it has since been deprecated, and support for all new attribute functions has gone intoSQLSetStmtAttr(). Users should migrate to the nondeprecated interface.

Statement options for an hstmt remain in effect until they are changed by another call toSQLSetStmtOption() or the hstmt is dropped by calling SQLFreeStmt() with the SQL_DROP option.Calling SQLFreeStmt() with the SQL_CLOSE, SQL_UNBIND, or SQL_RESET_PARAMS options does notreset statement options.

The format of information set through vParam depends on the specified fOption. The format of each isnoted in Table 161 on page 247.

Refer to Table 161 on page 247 for the proper statement options.

Note: Because the SQLSetStmtOption() function has been deprecated, not all the options listed in thetable are supported."


SQLSetStmtOption


Diagnostics

Table 164. SQLStmtOption SQLSTATEs


40003 * Statementcompletionunknown

The communication link between the CLI and the data source fails before the functioncompletes processing.

HY000 General error An error occurred for which there is no specific SQLSTATE and for which noimplementation defined SQLSTATE is defined. The error message returned by SQLErrorin the argument szErrorMsg describes the error and its cause.

HY001 Memory allocationfailure

The driver is unable to allocate memory required to support the processing orcompletion of the function.

HY009 Argument valuethat is not valid

Given the specified fOption value, a value that is not valid is specified for the argumentvParam.

A fOption that is not valid value is specified.

The argument szSchemaName or szTableName is a null pointer.

HY010 Function sequenceerror

The function is called out of sequence.

HYC00 Driver not capable The driver or the data sources does not support the specified option.

Referencesv “SQLSetConnectAttr - Set a connection attribute” on page 220v “SQLSetStmtAttr - Set a statement attribute” on page 247

SQLSetStmtOption


SQLSpecialColumns - Get special (row identifier) columnsSQLSpecialColumns() returns unique row identifier information (primary key or unique index) for a table.For example, unique index or primary key information. The information is returned in an SQL result set,which can be retrieved using the same functions that are used to fetch a result set generated by aSELECT statement.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLSpecialColumnsW(). Refer to “Unicode in Db2 for i CLI” on page307 for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLSpecialColumns (SQLHSTMT hstmt,

SQLSMALLINT fColType,SQLCHAR *szCatalogName,SQLSMALLINT cbCatalogName,SQLCHAR *szSchemaName,SQLSMALLINT cbSchemaName,SQLCHAR *szTableName,SQLSMALLINT cbTableName,SQLSMALLINT fScope,SQLSMALLINT fNullable);

Function arguments

Table 165. SQLSpecialColumns arguments



SQLSMALLINT fColType Input Reserved for future use to support additionaltypes of special columns.

This data type is currently ignored.

SQLCHAR * szCatalogName Input Catalog qualifier of a three-part table name.This must be a null pointer or a zero lengthstring.

SQLSMALLINT cbCatalogName Input Length of szCatalogName. This must be a setto 0.

SQLCHAR * szSchemaName Input Schema qualifier of the specified table.

SQLSMALLINT cbSchemaName Input Length of szSchemaName.

SQLCHAR * szTableName Input Table name.

SQLSMALLINT cbTableName Input Length of cbTableName.

SQLSpecialColumns


Table 165. SQLSpecialColumns arguments (continued)


SQLSMALLINT fScope Input Minimum required duration for which theunique row identifier is valid.

fScope must be one of the following values:

v SQL_SCOPE_CURROW - The rowidentifier is guaranteed to be valid onlywhile positioned on that row. A laterreselect using the same row identifiervalues might not return a row if the row isupdated or deleted by another transaction.

v SQL_SCOPE_TRANSACTION - The rowidentifier is guaranteed to be valid for theduration of the current transaction.

v SQL_SCOPE_SESSION - The rowidentifier is guaranteed to be valid for theduration of the connection.

The duration over which a row identifiervalue is guaranteed to be valid depends onthe current transaction isolation level. Forinformation and scenarios involving isolationlevels, refer to the IBM DB2 SQL reference.

SQLSMALLINT fNullable Input This determines whether to return specialcolumns that can have a NULL value.

Must be one of the following values:

v SQL_NO_NULLS

The row identifier column set returnedcannot have any NULL values.

v SQL_NULLABLE

The row identifier column set returnedcan include columns where NULL valuesare permitted.

Usage

If multiple ways exist to uniquely identify any row in a table (for example, if there are multiple uniqueindexes on the specified table), then Db2 for i CLI returns the best set of row identifier columns based onits internal criterion.

If there is no column set that allows any row in the table to be uniquely identified, an empty result set isreturned.

The unique row identifier information is returned in the form of a result set where each column of therow identifier is represented by one row in the result set. The result set returned by SQLSpecialColumns()has the following columns in the following order:

SQLSpecialColumns


Table 166. Columns returned by SQLSpecialColumns


1 SCOPE SMALLINT not NULL Actual scope of the rowid. Thiscontains one of the following values:

v SQL_SCOPE_CURROW

v SQL_SCOPE_TRANSACTION

v SQL_SCOPE_SESSION

Refer to fScope in Table 165 on page255 for a description of each value.

2 COLUMN_NAME VARCHAR(128) not NULL Name of the row identifier column.

3 DATA_TYPE SMALLINT not NULL SQL data type of the column.

4 TYPE_NAME VARCHAR(128) not NULL Database Management System(DBMS) character string representedof the name associated withDATA_TYPE column value.

5 COLUMN_SIZE INTEGER The precision of the column. NULL isreturned for data types whereprecision is not applicable.

6 BUFFER_LENGTH INTEGER The length, in bytes, of the datareturned in the default C type. ForCHAR data types, this is the same asthe value in theLENGTH_PRECISION column.

7 DECIMAL_DIGITS SMALLINT The scale of the column. NULL isreturned for data types where scale isnot applicable.

8 PSEUDO_COLUMN SMALLINT This indicates whether the column isa pseudo-column; Db2 for i CLI onlyreturns:

v SQL_PC_NOT_PSEUDO


Diagnostics

Table 167. SQLSpecialColumns SQLSTATEs






HY009 Argument length that is notvalid

The value of one of the length arguments is less than 0,but not equal to SQL_NTS.

SQLSpecialColumns


Table 167. SQLSpecialColumns SQLSTATEs (continued)




HYC00 Driver not capable The data source does not support the catalog portion(first part) of a three-part table name.

SQLSpecialColumns


SQLStatistics - Get index and statistics information for a base tableSQLStatistics() retrieves index information for a given table. It also returns the cardinality and thenumber of pages associated with the table and the indexes on the table. The information is returned in aresult set, which can be retrieved using the same functions that are used to fetch a result set generated bya SELECT statement.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLStatisticsW(). Refer to “Unicode in Db2 for i CLI” on page 307for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLStatistics (SQLHSTMT hstmt,

SQLCHAR *szCatalogName,SQLSMALLINT cbCatalogName,SQLCHAR *szSchemaName,SQLSMALLINT cbSchemaName,SQLCHAR *szTableName,SQLSMALLINT cbTableName,SQLSMALLINT fUnique,SQLSMALLINT fAccuracy);

Function arguments

Table 168. SQLStatistics arguments



SQLCHAR * szCatalogName Input Catalog qualifier of a three-part table name. Thismust be a null pointer or a zero length string.

SQLSMALLINT cbCatalogName Input Length of cbCatalogName. This must be set to 0.

SQLCHAR * szSchemaName Input Schema qualifier of the specified table.


SQLCHAR * szTableName Input Table name.

SQLSMALLINT cbTableName Input Length of cbTableName.

SQLSMALLINT fUnique Input Type of index information to return:

v SQL_INDEX_UNIQUE

Only unique indexes are returned.

v SQL_INDEX_ALL

All indexes are returned.

SQLSMALLINT fAccuracy Input Not currently used, must be set to 0.

Usage

SQLStatistics() returns the following types of information:v Statistics information for the table (if available):

– When the TYPE column in the following table is set to SQL_TABLE_STAT, the number of rows inthe table and the number of pages used to store the table.

– When the TYPE column indicates an index, the number of unique values in the index, and thenumber of pages used to store the indexes.

SQLStatistics


– Information about each index, where each index column is represented by one row of the result set.The result set columns are given in the following table in the order shown; the rows in the result setare ordered by NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_QUALIFIER, INDEX_NAMEand ORDINAL_POSITION.

Table 169. Columns returned by SQLStatistics


1 TABLE_CAT VARCHAR(128) The name of the catalog containingTABLE_SCHEM. This is set to NULL.


3 TABLE_NAME VARCHAR(128) not NULL Name of the table.

4 NON_UNIQUE SMALLINT This indicates whether the indexprohibits duplicate values:

v TRUE if the index allows duplicatevalues.

v FALSE if the index values must beunique.

v NULL is returned if the TYPEcolumn indicates that this row isSQL_TABLE_STAT (statisticsinformation about the table itself).

5 INDEX_QUALIFIER VARCHAR(128) The identifier used to qualify theindex name. This is NULL if theTYPE column indicatesSQL_TABLE_STAT.

6 INDEX_NAME VARCHAR(128) The name of the index. If the TYPEcolumn has the valueSQL_TABLE_STAT, this column hasthe value NULL.

7 TYPE SMALLINT not NULL This indicates the type of informationcontained in this row of the result set:

v SQL_TABLE_STAT

This indicates this row containsstatistics information about thetable itself.

v SQL_INDEX_CLUSTERED

This indicates this row containsinformation about an index, andthe index type is a clustered index.

v SQL_INDEX_HASHED

This indicates this row containsinformation about an index, andthe index type is a hashed index.

v SQL_INDEX_OTHER

This indicates this row containsinformation about an index, andthe index type is other thanclustered or hashed.

Note: Currently,SQL_INDEX_OTHER is the onlypossible type.

SQLStatistics


Table 169. Columns returned by SQLStatistics (continued)


8 ORDINAL_POSITION SMALLINT Ordinal position of the column withinthe index whose name is given in theINDEX_NAME column. A NULLvalue is returned for this column ifthe TYPE column has the value ofSQL_TABLE_STAT.

9 COLUMN_NAME VARCHAR(2000) Name of the column in the index.

10 ASC_OR_DESC CHAR(1) Sort sequence for the column; "A" forascending, "D" for descending. NULLvalue is returned if the value in theTYPE column is SQL_TABLE_STAT.

11 CARDINALITY INTEGER v If the TYPE column contains thevalue SQL_TABLE_STAT, thiscolumn contains the number ofrows in the table.

v If the TYPE column value is notSQL_TABLE_STAT, this columncontains the number of uniquevalues in the index.

v A NULL value is returned ifinformation is not available fromthe Database Management System(DBMS).

12 PAGES INTEGER v If the TYPE column contains thevalue SQL_TABLE_STAT, thiscolumn contains the number ofpages used to store the table.

v If the TYPE column value is notSQL_TABLE_STAT, this columncontains the number of pages usedto store the indexes.

v A NULL value is returned ifinformation is not available fromthe DBMS.

13 FILTER_CONDITION VARCHAR(128) If the index is a filtered index, this isthe filter condition. Since DB2 serversdo not support filtered indexes,NULL is always returned. NULL isalso returned if TYPE isSQL_TABLE_STAT.

For the row in the result set that contains table statistics (TYPE is set to SQL_TABLE_STAT), the columnsvalues of NON_UNIQUE, INDEX_QUALIFIER, INDEX_NAME, ORDINAL_POSITION,COLUMN_NAME, and COLLATION are set to NULL. If the CARDINALITY or PAGES informationcannot be determined, then NULL is returned for those columns.

If argument szSchemaName is not specified, the schema name qualifier defaults to the one currently ineffect for the current connection.

Passing a NULL pointer for argument szTableName will result in an error.

SQLStatistics



Diagnostics

Table 170. SQLStatistics SQLSTATEs






HY009 Argument or buffer lengththat is not valid

The value of one of the name length arguments is lessthan 0, but not equal to SQL_NTS.



HYC00 Driver not capable The catalog part (the first part) of a three-part table nameis not supported by the data source.

SQLStatistics


SQLTablePrivileges - Get privileges associated with a tableSQLTablePrivileges() returns a list of tables and associated privileges for each table. The information isreturned in an SQL result set, which can be retrieved using the same functions that are used to process aresult set generated by a query.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLTablePrivilegesW(). Refer to “Unicode in Db2 for i CLI” on page307 for more information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLTablePrivileges (SQLHSTMT StatementHandle,

SQLCHAR *CatalogName,SQLSMALLINT NameLength1,SQLCHAR *SchemaName,SQLSMALLINT NameLength2,SQLCHAR *TableName,SQLSMALLINT NameLength3);

Function arguments

Table 171. SQLTablePrivileges arguments



SQLCHAR * szTableQualifier Input Catalog qualifier of a 3 part table name. Thismust be a null pointer or a zero lengthstring.

SQLSMALLINT cbTableQualifier Input Length of CatalogName. This must be set to 0.

SQLCHAR * SchemaName Input Buffer that might contain a pattern-value toqualify the result set by schema name.


SQLCHAR * TableName Input Buffer that might contain a pattern-value toqualify the result set by table name.


Usage

The results are returned as a standard result set containing the columns listed in the following table. Theresult set is ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME, and PRIVILEGE. If multipleprivileges are associated with any given table, each privilege is returned as a separate row.

The granularity of each privilege reported here might or might not apply at the column level; forexample, for some data sources, if a table can be updated, every column in that table can also beupdated. For other data sources, the application must call SQLColumnPrivileges() to discover if theindividual columns have the same table privileges.

Because calls to SQLColumnPrivileges() in many cases map to a complex and thus expensive queryagainst the system catalog, they should be used sparingly, and the results saved rather than repeatingcalls.

The VARCHAR columns of the catalog functions result set have been declared with a maximum lengthattribute of 128 to be consistent with SQL92 limits. Because DB2 names are always 128 characters or less ,the application may choose to always set aside 128 characters (plus the null-terminator) for the outputbuffer, or alternatively, call SQLGetInfo() with SQL_MAX_CATALOG_NAME_LEN,

SQLTablePrivileges


SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN, andSQL_MAX_COLUMN_NAME_LEN. The SQL_MAX_CATALOG_NAME_LEN value determines the actuallength of the TABLE_CAT supported by the connected DBMS. The SQL_MAX_SCHEMA_NAME_LENvalue determines the actual length of the TABLE_SCHEM supported by the connected DatabaseManagement System (DBMS). The SQL_MAX_TABLE_NAME_LEN value determines the actual length ofthe TABLE_NAME supported by the connected DBMS. The SQL_MAX_COLUMN_NAME_LEN valuedetermines the actual length of the COLUMN_NAME supported by the connected DBMS.

Although new columns can be added and the names of the existing columns changed in future releases,the position of the current columns does not change.

Table 172. Columns returned by SQLTablePrivileges


1 TABLE_CAT VARCHAR(128) This is always null.


3 TABLE_NAME VARCHAR(128) not NULL The name of the table.

4 GRANTOR VARCHAR(128) Authorization ID of the user whogranted the privilege.

5 GRANTEE VARCHAR(128) Authorization ID of the user to whomthe privilege is granted.

6 PRIVILEGE VARCHAR(128) The table privilege. This can be one ofthe following strings:

v ALTER

v CONTROL

v INDEX

v DELETE

v INSERT

v REFERENCES

v SELECT

v UPDATE

7 IS_GRANTABLE VARCHAR(3) This indicates whether the grantee ispermitted to grant the privilege toother users.

This can be "YES", "NO" or "NULL".

Note: The column names used by Db2 for i CLI follow the X/Open CLI CAE specification style. Thecolumn types, contents and order are identical to those defined for the SQLProcedures() result set inODBC.


SQLTablePrivileges


Diagnostics

Table 173. SQLTablePrivileges SQLSTATEs




The value of one of the name length arguments is lessthan 0, but not equal SQL_NTS.

HY010 Function sequence error There is an open cursor for this statement handle, orthere is no connection for this statement handle.



Restrictions

None.

Example/* From the CLI sample TBINFO.C *//* ... */

/* call SQLTablePrivileges */printf("\n Call SQLTablePrivileges for:\n");printf(" tbSchemaPattern = %s\n", tbSchemaPattern);printf(" tbNamePattern = %s\n", tbNamePattern);sqlrc = SQLTablePrivileges( hstmt, NULL, 0,

tbSchemaPattern, SQL_NTS,tbNamePattern, SQL_NTS);

STMT_HANDLE_CHECK( hstmt, sqlrc);

SQLTablePrivileges


SQLTables - Get table informationSQLTables() returns a list of table names and associated information stored in the system catalogs of theconnected data source. The list of table names is returned as a result set, which can be retrieved using thesame functions that are used to retrieve a result set generated by a SELECT statement.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. Thecorresponding Unicode function is SQLTablesW(). Refer to “Unicode in Db2 for i CLI” on page 307 formore information about Unicode support for DB2 CLI.

SyntaxSQLRETURN SQLTables (SQLHSTMT hstmt,

SQLCHAR *szCatalogName,SQLSMALLINT cbCatalogName,SQLCHAR *szSchemaName,SQLSMALLINT cbSchemaName,SQLCHAR *szTableName,SQLSMALLINT cbTableName,SQLCHAR *szTableType,SQLSMALLINT cbTableType);

Function arguments

Table 174. SQLTables arguments



SQLCHAR * szCatalogName Input Buffer that might contain a pattern-value toqualify the result set. Catalog is the first partof a three-part table name.

This must be a NULL pointer or a zerolength string.

SQLSMALLINT cbCatalogName Input Length of szCatalogName. This must be set to0.

SQLCHAR * szSchemaName Input Buffer that might contain a pattern-value toqualify the result set by schema name.


SQLCHAR * szTableName Input Buffer that might contain a pattern-value toqualify the result set by table name.

SQLSMALLINT cbTableName Input Length of szTableName.

SQLTables


Table 174. SQLTables arguments (continued)


SQLCHAR * szTableType Input Buffer that might contain a value list toqualify the result set by table type.

The value list is a list of values separated bycommas for the types of interest. Valid tabletype identifiers might include: ALL, ALIAS,BASE TABLE, MATERIALIZED QUERYTABLE, SYSTEM TABLE, TABLE, VIEW. IfszTableType argument is a NULL pointer or azero length string, then this is equivalent tospecifying all of the possibilities for the tabletype identifier.

If SYSTEM TABLE is specified, then bothsystem tables and system views (if there areany) are returned.

The table types can be specified with orwithout quotation marks.

SQLSMALLINT cbTableType Input Size of szTableType

Note: The szCatalogName, szSchemaName, and szTableName arguments accept search patterns.

An escape character can be specified in conjunction with a wildcard character to allow that actualcharacter to be used in the search pattern. The escape character is specified on theSQL_ATTR_ESCAPE_CHAR environment attribute. Use of SQL_ATTR_ESCAPE_CHAR will bedeprecated in a future release. Support for the SQL_ATTR_ESCAPE_CHAR value is only honored if theconnection attribute SQL_ATTR_OLD_MTADTA_BEHAVIOR is set to SQL_TRUE.

Usage

Table information is returned in a result set where each table is represented by one row of the result set.

To support obtaining just a list of schemas, the following special semantics for the szSchemaNameargument can be applied: if szSchemaName is a string containing a single percent (%) character, andcbCatalogName, szTableName, and szTableType are empty strings, then the result set contains a list ofnon-duplicate schemas in the data source.

The result set returned by SQLTables() contains the columns listed in the following table in the ordergiven.

Table 175. Columns returned by SQLTables


1 TABLE_CAT VARCHAR(128) The current server.

2 TABLE_SCHEM VARCHAR(128) The name of the schema containing TABLE_NAME.

3 TABLE_NAME VARCHAR(128) The name of the table, view, alias, or synonym.

4 TABLE_TYPE VARCHAR(128) This identifies the type given by the name in theTABLE_NAME column. It can have the string valuesALIAS, BASE TABLE, MATERIALIZED QUERY TABLE,SYSTEM TABLE, TABLE, or VIEW.

5 REMARKS VARCHAR(254) This contains the descriptive information about the table.

SQLTables



Diagnostics

Table 176. SQLTables SQLSTATEs


24000 Cursor state that is not valid Cursor-related information is requested, but no cursor isopen.




HY009 Argument or buffer lengththat is not valid

The value of one of the name length arguments is lessthan 0, but not equal to SQL_NTS.



HYC00 Driver not capable The catalog part (the first part) of a three-part table nameis not supported by the data source.

SQLTables


SQLTransact - Commit or roll back a transactionSQLTransact() commits or rolls back the current transaction in the connection.

All changes to the database that have been made on the connection since connect time or the previouscall to SQLTransact() (whichever is the most recent) are committed or rolled back.

If a transaction is active on a connection, the application must call SQLTransact() before it can bedisconnected from the database.

SyntaxSQLRETURN SQLTransact (SQLHENV henv,

SQLHDBC hdbc,SQLSMALLINT fType);

Function arguments

Table 177. SQLTransact arguments



If hdbc is a valid connection handle, henv isignored.


If hdbc is set to SQL_NULL_HDBC, then henvmust contain the environment handle thatthe connection is associated with.

SQLSMALLINT fType Input The wanted action for the transaction. Thevalue for this argument must be one of:

v SQL_COMMIT

v SQL_ROLLBACK

v SQL_COMMIT_HOLD

v SQL_ROLLBACK_HOLD

Usage

Completing a transaction with SQL_COMMIT or SQL_ROLLBACK has the following effects:v Statement handles are still valid after a call to SQLTransact().v Cursor names, bound parameters, and column bindings survive transactions.v Open cursors are closed, and any result sets that are pending retrieval are discarded.

Completing the transaction with SQL_COMMIT_HOLD or SQL_ROLLBACK_HOLD still commits or rollsback the database changes, but does not cause cursors to be closed.

If no transaction is currently active on the connection, calling SQLTransact() has no effect on the databaseserver and returns SQL_SUCCESS.

SQLTransact() might fail while executing the COMMIT or ROLLBACK due to a loss of connection. Inthis case the application might be unable to determine whether the COMMIT or ROLLBACK has beenprocessed, and a database administrator's help might be required. Refer to the DBMS product informationfor more information about transaction logs and other transaction management tasks.

SQLTransact



Diagnostics

Table 178. SQLTransact SQLSTATEs


08003 Connection not open The hdbc is not in a connected state.

08007 Connection failure duringtransaction

The connection associated with the hdbc fails during theprocessing of the function during the processing of thefunction and it cannot be determined whether therequested COMMIT or ROLLBACK occurs before thefailure.



HY012 Transaction operation statethat is not valid

The value specified for the argument fType is neitherSQL_COMMIT nor SQL_ROLLBACK.



Example

Refer to the example in “SQLFetch - Fetch next row” on page 108

Db2 for i CLI include fileThe only include file used in Db2 for i call level interface (CLI) is sqlcli.h./*** START HEADER FILE SPECIFICATIONS *****************************//* *//* Header File Name: SQLCLI *//* *//* Product(s): *//* 5716-SS1 *//* 5761-SS1 *//* *//* (C)Copyright IBM Corp. 1995, 2008 *//* *//* All rights reserved. *//* US Government Users Restricted Rights - *//* Use, duplication or disclosure restricted *//* by GSA ADP Schedule Contract with IBM Corp. *//* *//* Licensed Materials-Property of IBM *//* *//* Header File Name: SQLCLI *//* *//* Descriptive Name: Structured Query Language (SQL) Call Level *//* Interface. *//* *//* Description: The SQL Call Level Interface provides access to *//* most SQL functions, without the need for a *//* precompiler. *//* *//* Header Files Included: SQLCLI */

SQLTransact


/* *//* Function Prototype List: SQLAllocConnect *//* SQLAllocEnv *//* SQLAllocHandle *//* SQLAllocStmt *//* SQLBindCol *//* SQLBindFileToCol *//* SQLBindFileToParam *//* SQLBindParam *//* SQLBindParameter *//* SQLCancel *//* SQLCloseCursor *//* SQLColAttribute *//* SQLColAttributeW *//* SQLColAttributes *//* SQLColAttributesW *//* SQLColumnPrivileges *//* SQLColumnPrivilegesW *//* SQLColumns *//* SQLColumnsW *//* SQLConnect *//* SQLConnectW *//* SQLCopyDesc *//* SQLDataSources *//* SQLDataSourcesW *//* SQLDescribeCol *//* SQLDescribeColW *//* SQLDescribeParam *//* SQLDisconnect *//* SQLDriverConnect *//* SQLDriverConnectW *//* SQLEndTran *//* SQLError *//* SQLErrorW *//* SQLExecDirect *//* SQLExecDirectW *//* SQLExecute *//* SQLExtendedFetch *//* SQLFetch *//* SQLFetchScroll *//* SQLForeignKeys *//* SQLForeignKeysW *//* SQLFreeConnect *//* SQLFreeEnv *//* SQLFreeHandle *//* SQLFreeStmt *//* SQLGetCol *//* SQLGetConnectOption *//* SQLGetConnectOptionW *//* SQLGetCursorName *//* SQLGetCursorNameW *//* SQLGetConnectAttr *//* SQLGetConnectAttrW *//* SQLGetData *//* SQLGetDescField *//* SQLGetDescFieldW *//* SQLGetDescRec *//* SQLGetDescRecW *//* SQLGetDiagField *//* SQLGetDiagFieldW *//* SQLGetDiagRec *//* SQLGetDiagRecW *//* SQLGetEnvAttr *//* SQLGetFunctions *//* SQLGetInfo *//* SQLGetInfoW *//* SQLGetLength */

SQL CLI


/* SQLGetPosition *//* SQLGetPositionW *//* SQLGetStmtAttr *//* SQLGetStmtAttrW *//* SQLGetStmtOption *//* SQLGetStmtOptionW *//* SQLGetSubString *//* SQLGetSubStringW *//* SQLGetTypeInfo *//* SQLGetTypeInfoW *//* SQLLanguages *//* SQLMoreResults *//* SQLNativeSql *//* SQLNativeSqlW *//* SQLNextResult *//* SQLNumParams *//* SQLNumResultCols *//* SQLParamData *//* SQLParamOptions *//* SQLPrepare *//* SQLPrepareW *//* SQLPrimaryKeys *//* SQLPrimaryKeysW *//* SQLProcedureColumns *//* SQLProcedureColumnsW *//* SQLProcedures *//* SQLProceduresW *//* SQLPutData *//* SQLReleaseEnv *//* SQLRowCount *//* SQLSetConnectAttr *//* SQLSetConnectAttrW *//* SQLSetConnectOption *//* SQLSetConnectOptionW *//* SQLSetCursorName *//* SQLSetCursorNameW *//* SQLSetDescField *//* SQLSetDescFieldW *//* SQLSetDescRec *//* SQLSetEnvAttr *//* SQLSetParam *//* SQLSetStmtAttr *//* SQLSetStmtAttrW *//* SQLSetStmtOption *//* SQLSetStmtOptionW *//* SQLSpecialColumns *//* SQLSpecialColumnsW *//* SQLStartTran *//* SQLStatistics *//* SQLStatisticsW *//* SQLTablePrivileges *//* SQLTablePrivilegesW *//* SQLTables *//* SQLTablesW *//* SQLTransact *//* *//* Change Activity: *//* *//* CFD List: *//* *//* FLAG REASON LEVEL DATE PGMR CHANGE DESCRIPTION *//* ---- ------------ ----- ------ --------- ----------------------*//* $A0= D91823 3D60 941206 MEGERIAN New Include *//* $A1= D94881 4D20 960816 MEGERIAN V4R2M0 enhancements *//* $A2= D95600 4D30 970910 MEGERIAN V4R3M0 enhancements *//* $A3= P3682850 4D40 981030 MEGERIAN V4R4M0 enhancements *//* $A4= D97596 4D50 990326 LJAMESON V4R5M0 enhancements */

SQL CLI


/* $A5= P9924900 5D10 000512 MEGERIAN V5R1M0 enhancements *//* $C1= D98562 5D20 010107 MBAILEY V5R2M0 enhancements *//* $C2= D9856201 5D20 010506 MBAILEY More enhancements *//* $D1= P9A42663 5D30 031103 AJSLOMA V5R3M0 enhancements *//* $D2= P9A51843 5Q30 040102 ROCH Larger Decimal support*//* $D3= P9A61758 5D40 050517 AJSLOMA V5R4M0 enhancements *//* $D4= P9A72391 5P30 040622 ROCH Formatting *//* $D5= D99859 5D40 041104 HUEBERT XA over DRDA *//* $E1= D93586 5D50 060908 ROCH Wide API support *//* $E2= D93586 5D50 070320 ROCH V6R1m0 enhancements *//* $E3= DXXXXX 6P10 090601 ROCH TINYINT Support *//* $F1= D92300 7D10 090108 ROCH Adding XML data type *//* $F2= D92213 7D10 090202 ROCH Currently committed *//* *//* End CFD List. *//* *//* Additional notes about the Change Activity *//* End Change Activity. *//*** END HEADER FILE SPECIFICATIONS *******************************/

#ifndef SQL_H_SQLCLI#define SQL_H_SQLCLI /* Permit duplicate Includes */

#if (__OS400_TGTVRM__>=510) /* @B1A*/#pragma datamodel(P128) /* @B1A*/#endif /* @B1A*/

#ifdef __ILEC400__#pragma checkout(suspend)#pragma nomargins nosequence

#else#pragma info(none)

#endif

#ifndef __SQL_EXTERN#ifdef __ILEC400__

#define SQL_EXTERN extern#else

#ifdef __cplusplus#ifdef __TOS_OS400__

#define SQL_EXTERN extern "C nowiden"#else

#define SQL_EXTERN extern "C"#endif

#else#define SQL_EXTERN extern#endif /* __cplusplus */

#endif /* __ILEC_400__ */#define __SQL_EXTERN

#endif

#ifdef __ILEC400__#pragma argument (SQLAllocConnect , nowiden)#pragma argument (SQLAllocEnv , nowiden)#pragma argument (SQLAllocHandle , nowiden)#pragma argument (SQLAllocStmt , nowiden)#pragma argument (SQLBindCol , nowiden)#pragma argument (SQLBindFileToCol , nowiden)#pragma argument (SQLBindFileToParam , nowiden)#pragma argument (SQLBindParam , nowiden)#pragma argument (SQLBindParameter , nowiden)#pragma argument (SQLCancel , nowiden)#pragma argument (SQLCloseCursor , nowiden)#pragma argument (SQLColAttribute , nowiden)#pragma argument (SQLColAttributeW , nowiden)#pragma argument (SQLColAttributes , nowiden)#pragma argument (SQLColAttributesW , nowiden)

SQL CLI


#pragma argument (SQLColumnPrivileges , nowiden)#pragma argument (SQLColumnPrivilegesW , nowiden)#pragma argument (SQLColumns , nowiden)#pragma argument (SQLColumnsW , nowiden)#pragma argument (SQLConnect , nowiden)#pragma argument (SQLConnectW , nowiden)#pragma argument (SQLCopyDesc , nowiden)#pragma argument (SQLDataSources , nowiden)#pragma argument (SQLDataSourcesW , nowiden)#pragma argument (SQLDescribeCol , nowiden)#pragma argument (SQLDescribeColW , nowiden)#pragma argument (SQLDescribeParam , nowiden)#pragma argument (SQLDisconnect , nowiden)#pragma argument (SQLDriverConnect , nowiden)#pragma argument (SQLDriverConnectW , nowiden)#pragma argument (SQLEndTran , nowiden)#pragma argument (SQLError , nowiden)#pragma argument (SQLErrorW , nowiden)#pragma argument (SQLExecDirect , nowiden)#pragma argument (SQLExecDirectW , nowiden)#pragma argument (SQLExecute , nowiden)#pragma argument (SQLExecuteW , nowiden)#pragma argument (SQLExtendedFetch , nowiden)#pragma argument (SQLFetch , nowiden)#pragma argument (SQLFetchScroll , nowiden)#pragma argument (SQLForeignKeys , nowiden)#pragma argument (SQLForeignKeysW , nowiden)#pragma argument (SQLFreeConnect , nowiden)#pragma argument (SQLFreeEnv , nowiden)#pragma argument (SQLFreeHandle , nowiden)#pragma argument (SQLFreeStmt , nowiden)#pragma argument (SQLGetCol , nowiden)#pragma argument (SQLGetColW , nowiden)#pragma argument (SQLGetConnectOption , nowiden)#pragma argument (SQLGetConnectOptionW , nowiden)#pragma argument (SQLGetCursorName , nowiden)#pragma argument (SQLGetCursorNameW , nowiden)#pragma argument (SQLGetConnectAttr , nowiden)#pragma argument (SQLGetConnectAttrW , nowiden)#pragma argument (SQLGetData , nowiden)#pragma argument (SQLGetDescField , nowiden)#pragma argument (SQLGetDescFieldW , nowiden)#pragma argument (SQLGetDescRec , nowiden)#pragma argument (SQLGetDescRecW , nowiden)#pragma argument (SQLGetDiagField , nowiden)#pragma argument (SQLGetDiagFieldW , nowiden)#pragma argument (SQLGetDiagRec , nowiden)#pragma argument (SQLGetDiagRecW , nowiden)#pragma argument (SQLGetEnvAttr , nowiden)#pragma argument (SQLGetFunctions , nowiden)#pragma argument (SQLGetInfo , nowiden)#pragma argument (SQLGetInfoW , nowiden)#pragma argument (SQLGetLength , nowiden)#pragma argument (SQLGetPosition , nowiden)#pragma argument (SQLGetPositionW , nowiden)#pragma argument (SQLGetStmtAttr , nowiden)#pragma argument (SQLGetStmtAttrW , nowiden)#pragma argument (SQLGetStmtOption , nowiden)#pragma argument (SQLGetStmtOptionW , nowiden)#pragma argument (SQLGetSubString , nowiden)#pragma argument (SQLGetSubStringW , nowiden)#pragma argument (SQLGetTypeInfo , nowiden)#pragma argument (SQLGetTypeInfoW , nowiden)#pragma argument (SQLLanguages , nowiden)#pragma argument (SQLMoreResults , nowiden)#pragma argument (SQLNativeSql , nowiden)#pragma argument (SQLNativeSqlW , nowiden)

SQL CLI


#pragma argument (SQLNextResult , nowiden)#pragma argument (SQLNumParams , nowiden)#pragma argument (SQLNumResultCols , nowiden)#pragma argument (SQLParamData , nowiden)#pragma argument (SQLParamOptions , nowiden)#pragma argument (SQLPrepare , nowiden)#pragma argument (SQLPrepareW , nowiden)#pragma argument (SQLPrimaryKeys , nowiden)#pragma argument (SQLPrimaryKeysW , nowiden)#pragma argument (SQLProcedureColumns , nowiden)#pragma argument (SQLProcedureColumnsW , nowiden)#pragma argument (SQLProcedures , nowiden)#pragma argument (SQLProceduresW , nowiden)#pragma argument (SQLPutData , nowiden)#pragma argument (SQLReleaseEnv , nowiden)#pragma argument (SQLRowCount , nowiden)#pragma argument (SQLSetConnectAttr , nowiden)#pragma argument (SQLSetConnectAttrW , nowiden)#pragma argument (SQLSetConnectOption , nowiden)#pragma argument (SQLSetConnectOptionW , nowiden)#pragma argument (SQLSetCursorName , nowiden)#pragma argument (SQLSetCursorNameW , nowiden)#pragma argument (SQLSetDescField , nowiden)#pragma argument (SQLSetDescFieldW , nowiden)#pragma argument (SQLSetDescRec , nowiden)#pragma argument (SQLSetEnvAttr , nowiden)#pragma argument (SQLSetParam , nowiden)#pragma argument (SQLSetStmtAttr , nowiden)#pragma argument (SQLSetStmtAttrW , nowiden)#pragma argument (SQLSetStmtOption , nowiden)#pragma argument (SQLSetStmtOptionW , nowiden)#pragma argument (SQLSpecialColumns , nowiden)#pragma argument (SQLSpecialColumnsW , nowiden)#pragma argument (SQLStartTran , nowiden)#pragma argument (SQLStatistics , nowiden)#pragma argument (SQLStatisticsW , nowiden)#pragma argument (SQLTablePrivileges , nowiden)#pragma argument (SQLTablePrivilegesW , nowiden)#pragma argument (SQLTables , nowiden)#pragma argument (SQLTablesW , nowiden)#pragma argument (SQLTransact , nowiden)

#endif

/* generally useful constants */#define SQL_FALSE 0#define SQL_TRUE 1#define SQL_NTS -3 /* NTS = Null Terminated String */#define SQL_SQLSTATE_SIZE 5 /* size of SQLSTATE, not including

null terminating byte */#define SQL_MAX_MESSAGE_LENGTH 512#define SQL_MAX_OPTION_STRING_LENGTH 128

/* RETCODE values *//* Note: The return codes will reflect the XA return code specifications,

when using CLI to execute XA transactions (use of theSQLSetConnectAttr - SQL_ATTR_TXN_INFO attribute).The XA return codes can be found in the XA.h include file. @D3A*/

#define SQL_SUCCESS 0#define SQL_SUCCESS_WITH_INFO 1#define SQL_NO_DATA_FOUND 100#define SQL_NEED_DATA 99#define SQL_NO_DATA SQL_NO_DATA_FOUND#define SQL_ERROR -1#define SQL_INVALID_HANDLE -2#define SQL_STILL_EXECUTING 2

/* SQLFreeStmt option values */

SQL CLI


#define SQL_CLOSE 0#define SQL_DROP 1#define SQL_UNBIND 2#define SQL_RESET_PARAMS 3

/* SQLSetParam defines */#define SQL_C_DEFAULT 99

/* SQLEndTran option values */#define SQL_COMMIT 0#define SQL_ROLLBACK 1#define SQL_COMMIT_HOLD 2#define SQL_ROLLBACK_HOLD 3#define SQL_SAVEPOINT_NAME_RELEASE 4#define SQL_SAVEPOINT_NAME_ROLLBACK 5

/* SQLDriverConnect option values */#define SQL_DRIVER_COMPLETE 1#define SQL_DRIVER_COMPLETE_REQUIRED 1#define SQL_DRIVER_NOPROMPT 1#define SQL_DRIVER_PROMPT 0

/* Valid option codes for GetInfo procedure */#define SQL_ACTIVE_CONNECTIONS 0#define SQL_MAX_DRIVER_CONNECTIONS 0#define SQL_MAX_CONCURRENT_ACTIVITIES 1#define SQL_ACTIVE_STATEMENTS 1#define SQL_PROCEDURES 2#define SQL_DRIVER_NAME 6 /* @C1A*/#define SQL_ODBC_API_CONFORMANCE 9 /* @C1A*/#define SQL_ODBC_SQL_CONFORMANCE 10 /* @C1A*/#define SQL_DBMS_NAME 17#define SQL_DBMS_VER 18#define SQL_DRIVER_VER 18#define SQL_IDENTIFIER_CASE 28 /* @C1A*/#define SQL_IDENTIFIER_QUOTE_CHAR 29 /* @C1A*/#define SQL_MAX_COLUMN_NAME_LEN 30#define SQL_MAX_CURSOR_NAME_LEN 31#define SQL_MAX_OWNER_NAME_LEN 32#define SQL_MAX_SCHEMA_NAME_LEN 33#define SQL_MAX_TABLE_NAME_LEN 35#define SQL_MAX_COLUMNS_IN_GROUP_BY 36#define SQL_MAX_COLUMNS_IN_ORDER_BY 37#define SQL_MAX_COLUMNS_IN_SELECT 38#define SQL_MAX_COLUMNS_IN_TABLE 39#define SQL_MAX_TABLES_IN_SELECT 40#define SQL_COLUMN_ALIAS 41#define SQL_DATA_SOURCE_NAME 42#define SQL_DATASOURCE_NAME 42#define SQL_MAX_COLUMNS_IN_INDEX 43#define SQL_PROCEDURE_TERM 44 /* @C1A*/#define SQL_QUALIFIER_TERM 45 /* @C1A*/#define SQL_TXN_CAPABLE 46 /* @C1A*/#define SQL_OWNER_TERM 47 /* @C1A*/#define SQL_DATA_SOURCE_READ_ONLY 48 /* @C2A*/#define SQL_DEFAULT_TXN_ISOLATION 49 /* @C2A*/#define SQL_MULTIPLE_ACTIVE_TXN 55 /* @C2A*/#define SQL_QUALIFIER_NAME_SEPARATOR 65 /* @C2A*/#define SQL_CORRELATION_NAME 74 /* @C1A*/#define SQL_NON_NULLABLE_COLUMNS 75 /* @C1A*/#define SQL_DRIVER_ODBC_VER 77 /* @C1A*/#define SQL_GROUP_BY 88 /* @C1A*/#define SQL_ORDER_BY_COLUMNS_IN_SELECT 90 /* @C1A*/#define SQL_OWNER_USAGE 91 /* @C1A*/#define SQL_QUALIFIER_USAGE 92 /* @C1A*/#define SQL_QUOTED_IDENTIFIER_CASE 93 /* @C1A*/#define SQL_MAX_ROW_SIZE 104 /* @C1A*/

SQL CLI


#define SQL_QUALIFIER_LOCATION 114 /* @C1A*/#define SQL_MAX_CATALOG_NAME_LEN 115#define SQL_MAX_STATEMENT_LEN 116#define SQL_SEARCH_PATTERN_ESCAPE 117#define SQL_OUTER_JOINS 118#define SQL_LIKE_ESCAPE_CLAUSE 119#define SQL_CATALOG_NAME 120#define SQL_DESCRIBE_PARAMETER 121#define SQL_STRING_FUNCTIONS 50#define SQL_NUMERIC_FUNCTIONS 51#define SQL_CONVERT_FUNCTIONS 52#define SQL_TIMEDATE_FUNCTIONS 53#define SQL_SQL92_PREDICATES 160#define SQL_SQL92_VALUE_EXPRESSIONS 165#define SQL_AGGREGATE_FUNCTIONS 169#define SQL_SQL_CONFORMANCE 170#define SQL_CONVERT_CHAR 171#define SQL_CONVERT_NUMERIC 172#define SQL_CONVERT_DECIMAL 173#define SQL_CONVERT_INTEGER 174#define SQL_CONVERT_SMALLINT 175#define SQL_CONVERT_FLOAT 176#define SQL_CONVERT_REAL 177#define SQL_CONVERT_DOUBLE 178#define SQL_CONVERT_VARCHAR 179#define SQL_CONVERT_LONGVARCHAR 180#define SQL_CONVERT_BINARY 181#define SQL_CONVERT_VARBINARY 182#define SQL_CONVERT_BIT 183#define SQL_CONVERT_TINYINT 184#define SQL_CONVERT_BIGINT 185#define SQL_CONVERT_DATE 186#define SQL_CONVERT_TIME 187#define SQL_CONVERT_TIMESTAMP 188#define SQL_CONVERT_LONGVARBINARY 189#define SQL_CONVERT_INTERVAL_YEAR_MONTH 190#define SQL_CONVERT_INTERVAL_DAY_TIME 191#define SQL_CONVERT_WCHAR 192#define SQL_CONVERT_WLONGVARCHAR 193#define SQL_CONVERT_WVARCHAR 194#define SQL_CONVERT_BLOB 195#define SQL_CONVERT_CLOB 196#define SQL_CONVERT_DBCLOB 197#define SQL_CURSOR_COMMIT_BEHAVIOR 198#define SQL_CURSOR_ROLLBACK_BEHAVIOR 199#define SQL_POSITIONED_STATEMENTS 200#define SQL_KEYWORDS 201#define SQL_CONNECTION_JOB_NAME 202#define SQL_USER_NAME 203 /* @D3A*/#define SQL_DATABASE_NAME 204 /* @D3A*/#define SQL_CONVERT_DECFLOAT7 205 /* @E2A*/#define SQL_CONVERT_DECFLOAT16 206 /* @E2A*/#define SQL_CONVERT_DECFLOAT34 207 /* @E2A*/

/* Unsupported codes for SQLGetInfo */

#define SQL_LOCK_TYPES -1#define SQL_POS_OPERATIONS -1

/* Output values for cursor behavior */

#define SQL_CB_DELETE 1#define SQL_CB_CLOSE 2#define SQL_CB_PRESERVE 3

SQL CLI


/* Aliased option codes (ODBC 3.0) @C1A*/#define SQL_SCHEMA_TERM SQL_OWNER_TERM /* @C1A*/#define SQL_SCHEMA_USAGE SQL_OWNER_USAGE /* @C1A*/#define SQL_CATALOG_LOCATION SQL_QUALIFIER_LOCATION /*@C1A*/#define SQL_CATALOG_TERM SQL_QUALIFIER_TERM /* @C1A*/#define SQL_CATALOG_USAGE SQL_QUALIFIER_USAGE /* @C1A*/#define SQL_CATALOG_NAME_SEPARATOR SQL_QUALIFIER_NAME_SEPARATOR

/* @C2A*/

/** Output values for SQL_ODBC_API_CONFORMANCE* info type in SQLGetInfo*/#define SQL_OAC_NONE 0 /* @C1A*/#define SQL_OAC_LEVEL1 1 /* @C1A*/#define SQL_OAC_LEVEL2 2 /* @C1A*/

/** Output values for SQL_ODBC_SQL_CONFORMANCE* info type in SQLGetInfo*/#define SQL_OSC_MINIMUM 0 /* @C1A*/#define SQL_OSC_CORE 1 /* @C1A*/#define SQL_OSC_EXTENDED 2 /* @C1A*/

/** Output values for SQL_QUALIFIER_USAGE* info type in SQLGetInfo*/#define SQL_QU_NOT_SUPPORTED 0x00000000 /* @C1A*/#define SQL_QU_DML_STATEMENTS 0x00000001 /* @C1A*/#define SQL_QU_PROCEDURE_INVOCATION 0x00000002 /* @C1A*/#define SQL_QU_TABLE_DEFINITION 0x00000004 /* @C1A*/#define SQL_QU_INDEX_DEFINITION 0x00000008 /* @C1A*/#define SQL_QU_PRIVILEGE_DEFINITION 0x00000010 /* @C1A*/

/** Output values for SQL_QUALIFIER_LOCATION* info type in SQLGetInfo*/#define SQL_QL_START 1 /* @C1A*/#define SQL_QL_END 2 /* @C1A*/

/** Output values for SQL_OWNER_USAGE* info type in SQLGetInfo*/#define SQL_OU_DML_STATEMENTS 0x00000001 /* @C1A*/#define SQL_OU_PROCEDURE_INVOCATION 0x00000002 /* @C1A*/#define SQL_OU_TABLE_DEFINITION 0x00000004 /* @C1A*/#define SQL_OU_INDEX_DEFINITION 0x00000008 /* @C1A*/#define SQL_OU_PRIVILEGE_DEFINITION 0x00000010 /* @C1A*/

/** Output values for SQL_TXN_CAPABLE* info type in SQLGetInfo*/#define SQL_TC_NONE 0 /* @C1A*/#define SQL_TC_DML 1 /* @C1A*/#define SQL_TC_ALL 2 /* @C1A*/#define SQL_TC_DDL_COMMIT 3 /* @C1A*/#define SQL_TC_DDL_IGNORE 4 /* @C1A*/

/** Output values for SQL_DEFAULT_TXN_ISOLATION* info type in SQLGetInfo*/

SQL CLI


#define SQL_TXN_READ_UNCOMMITTED_MASK 0x00000001 /* @C2A*/#define SQL_TXN_READ_COMMITTED_MASK 0x00000002 /* @C2A*/#define SQL_TXN_REPEATABLE_READ_MASK 0x00000004 /* @C2A*/#define SQL_TXN_SERIALIZABLE_MASK 0x00000008 /* @C2A*/

/** Output values for SQL_STRING_FUNCTIONS* info type in SQLGetInfo*/

#define SQL_FN_STR_CONCAT 0x00000001#define SQL_FN_STR_UCASE 0x00000002#define SQL_FN_STR_LCASE 0x00000004#define SQL_FN_STR_SUBSTRING 0x00000008#define SQL_FN_STR_LENGTH 0x00000010#define SQL_FN_STR_POSITION 0x00000020#define SQL_FN_STR_LTRIM 0x00000040#define SQL_FN_STR_RTRIM 0x00000080

/** Output values for SQL_POS_OPERATIONS* info type in SQLGetInfo (not currently supported)*/

#define SQL_POS_POSITION 0x00000001#define SQL_POS_REFRESH 0x00000002#define SQL_POS_UPDATE 0x00000004#define SQL_POS_DELETE 0x00000008#define SQL_POS_ADD 0x00000010

/** Output values for SQL_NUMERIC_FUNCTIONS* info type in SQLGetInfo*/

#define SQL_FN_NUM_ABS 0x00000001#define SQL_FN_NUM_ACOS 0x00000002#define SQL_FN_NUM_ASIN 0x00000004#define SQL_FN_NUM_ATAN 0x00000008#define SQL_FN_NUM_ATAN2 0x00000010#define SQL_FN_NUM_CEILING 0x00000020#define SQL_FN_NUM_COS 0x00000040#define SQL_FN_NUM_COT 0x00000080#define SQL_FN_NUM_EXP 0x00000100#define SQL_FN_NUM_FLOOR 0x00000200#define SQL_FN_NUM_LOG 0x00000400#define SQL_FN_NUM_MOD 0x00000800#define SQL_FN_NUM_SIGN 0x00001000#define SQL_FN_NUM_SIN 0x00002000#define SQL_FN_NUM_SQRT 0x00004000#define SQL_FN_NUM_TAN 0x00008000#define SQL_FN_NUM_PI 0x00010000#define SQL_FN_NUM_RAND 0x00020000#define SQL_FN_NUM_DEGREES 0x00040000#define SQL_FN_NUM_LOG10 0x00080000#define SQL_FN_NUM_POWER 0x00100000#define SQL_FN_NUM_RADIANS 0x00200000#define SQL_FN_NUM_ROUND 0x00400000#define SQL_FN_NUM_TRUNCATE 0x00800000

/* SQL_SQL92_VALUE_EXPRESSIONS bitmasks */#define SQL_SVE_CASE 0x00000001#define SQL_SVE_CAST 0x00000002#define SQL_SVE_COALESCE 0x00000004#define SQL_SVE_NULLIF 0x00000008

/* SQL_SQL92_PREDICATES bitmasks */#define SQL_SP_EXISTS 0x00000001

SQL CLI


#define SQL_SP_ISNOTNULL 0x00000002#define SQL_SP_ISNULL 0x00000004#define SQL_SP_MATCH_FULL 0x00000008#define SQL_SP_MATCH_PARTIAL 0x00000010#define SQL_SP_MATCH_UNIQUE_FULL 0x00000020#define SQL_SP_MATCH_UNIQUE_PARTIAL 0x00000040#define SQL_SP_OVERLAPS 0x00000080#define SQL_SP_UNIQUE 0x00000100#define SQL_SP_LIKE 0x00000200#define SQL_SP_IN 0x00000400#define SQL_SP_BETWEEN 0x00000800#define SQL_SP_COMPARISON 0x00001000#define SQL_SP_QUANTIFIED_COMPARISON 0x00002000

/* SQL_AGGREGATE_FUNCTIONS bitmasks */#define SQL_AF_AVG 0x00000001#define SQL_AF_COUNT 0x00000002#define SQL_AF_MAX 0x00000004#define SQL_AF_MIN 0x00000008#define SQL_AF_SUM 0x00000010#define SQL_AF_DISTINCT 0x00000020#define SQL_AF_ALL 0x00000040

/* SQL_SQL_CONFORMANCE bitmasks */#define SQL_SC_SQL92_ENTRY 0x00000001#define SQL_SC_FIPS127_2_TRANSITIONAL 0x00000002#define SQL_SC_SQL92_INTERMEDIATE 0x00000004#define SQL_SC_SQL92_FULL 0x00000008

/* SQL_CONVERT_FUNCTIONS functions */#define SQL_FN_CVT_CONVERT 0x00000001#define SQL_FN_CVT_CAST 0x00000002

/* SQL_POSITIONED_STATEMENTS bitmasks */#define SQL_PS_POSITIONED_DELETE 0x00000001#define SQL_PS_POSITIONED_UPDATE 0x00000002#define SQL_PS_SELECT_FOR_UPDATE 0x00000004

/* SQL supported conversion bitmasks */#define SQL_CVT_CHAR 0x00000001#define SQL_CVT_NUMERIC 0x00000002#define SQL_CVT_DECIMAL 0x00000004#define SQL_CVT_INTEGER 0x00000008#define SQL_CVT_SMALLINT 0x00000010#define SQL_CVT_FLOAT 0x00000020#define SQL_CVT_REAL 0x00000040#define SQL_CVT_DOUBLE 0x00000080#define SQL_CVT_VARCHAR 0x00000100#define SQL_CVT_LONGVARCHAR 0x00000200#define SQL_CVT_BINARY 0x00000400#define SQL_CVT_VARBINARY 0x00000800#define SQL_CVT_BIT 0x00001000#define SQL_CVT_TINYINT 0x00002000#define SQL_CVT_BIGINT 0x00004000#define SQL_CVT_DATE 0x00008000#define SQL_CVT_TIME 0x00010000#define SQL_CVT_TIMESTAMP 0x00020000#define SQL_CVT_LONGVARBINARY 0x00040000#define SQL_CVT_INTERVAL_YEAR_MONTH 0x00080000#define SQL_CVT_INTERVAL_DAY_TIME 0x00100000#define SQL_CVT_WCHAR 0x00200000#define SQL_CVT_WLONGVARCHAR 0x00400000#define SQL_CVT_WVARCHAR 0x00800000#define SQL_CVT_BLOB 0x01000000#define SQL_CVT_CLOB 0x02000000#define SQL_CVT_DBCLOB 0x04000000#define SQL_CVT_DECFLOAT7 0x08000000 /* @E2A*/

SQL CLI


#define SQL_CVT_DECFLOAT16 0x10000000 /* @E2A*/#define SQL_CVT_DECFLOAT34 0x20000000 /* @E2A*/

/* SQL_TIMEDATE_FUNCTIONS bitmasks */#define SQL_FN_TD_NOW 0x00000001#define SQL_FN_TD_CURDATE 0x00000002#define SQL_FN_TD_DAYOFMONTH 0x00000004#define SQL_FN_TD_DAYOFWEEK 0x00000008#define SQL_FN_TD_DAYOFYEAR 0x00000010#define SQL_FN_TD_MONTH 0x00000020#define SQL_FN_TD_QUARTER 0x00000040#define SQL_FN_TD_WEEK 0x00000080#define SQL_FN_TD_YEAR 0x00000100#define SQL_FN_TD_CURTIME 0x00000200#define SQL_FN_TD_HOUR 0x00000400#define SQL_FN_TD_MINUTE 0x00000800#define SQL_FN_TD_SECOND 0x00001000#define SQL_FN_TD_TIMESTAMPADD 0x00002000#define SQL_FN_TD_TIMESTAMPDIFF 0x00004000#define SQL_FN_TD_DAYNAME 0x00008000#define SQL_FN_TD_MONTHNAME 0x00010000#define SQL_FN_TD_CURRENT_DATE 0x00020000#define SQL_FN_TD_CURRENT_TIME 0x00040000#define SQL_FN_TD_CURRENT_TIMESTAMP 0x00080000#define SQL_FN_TD_EXTRACT 0x00100000

/** Output values for SQL_CORRELATION_NAME* info type in SQLGetInfo*/

#define SQL_CN_NONE 0 /* @C1A*/#define SQL_CN_DIFFERENT 1 /* @C1A*/#define SQL_CN_ANY 2 /* @C1A*/

/** Output values for SQL_IDENTIFIER_CASE* info type in SQLGetInfo*/

#define SQL_IC_UPPER 1 /* @C1A*/#define SQL_IC_LOWER 2 /* @C1A*/#define SQL_IC_SENSITIVE 3 /* @C1A*/#define SQL_IC_MIXED 4 /* @C1A*/

/** Output values for SQL_NON_NULLABLE_COLUMNS* info type in SQLGetInfo*/

#define SQL_NNC_NULL 0 /* @C1A*/#define SQL_NNC_NON_NULL 1 /* @C1A*/

/** Output values for SQL_GROUP_BY* info type in SQLGetInfo*/

#define SQL_GB_NO_RELATION 0 /* @C1A*/#define SQL_GB_NOT_SUPPORTED 1 /* @C1A*/#define SQL_GB_GROUP_BY_EQUALS_SELECT 2 /* @C1A*/#define SQL_GB_GROUP_BY_CONTAINS_SELECT 3 /* @C1A*/

/* Standard SQL data types */#define SQL_CHAR 1#define SQL_NUMERIC 2#define SQL_DECIMAL 3#define SQL_INTEGER 4#define SQL_SMALLINT 5#define SQL_FLOAT 6#define SQL_REAL 7

SQL CLI


#define SQL_DOUBLE 8#define SQL_DATETIME 9#define SQL_VARCHAR 12#define SQL_BLOB 13#define SQL_CLOB 14#define SQL_DBCLOB 15#define SQL_DATALINK 16#define SQL_WCHAR 17#define SQL_WVARCHAR 18#define SQL_BIGINT 19#define SQL_BLOB_LOCATOR 20#define SQL_CLOB_LOCATOR 21#define SQL_DBCLOB_LOCATOR 22#define SQL_UTF8_CHAR 23 /* @D1A*/#define SQL_WLONGVARCHAR SQL_WVARCHAR#define SQL_LONGVARCHAR SQL_VARCHAR#define SQL_GRAPHIC 95#define SQL_VARGRAPHIC 96#define SQL_LONGVARGRAPHIC SQL_VARGRAPHIC#define SQL_BINARY -2#define SQL_VARBINARY -3#define SQL_LONGVARBINARY SQL_VARBINARY#define SQL_DATE 91#define SQL_TYPE_DATE 91#define SQL_TIME 92#define SQL_TYPE_TIME 92#define SQL_TIMESTAMP 93#define SQL_TYPE_TIMESTAMP 93#define SQL_CODE_DATE 1#define SQL_CODE_TIME 2#define SQL_CODE_TIMESTAMP 3#define SQL_ALL_TYPES 0#define SQL_DECFLOAT -360 /* @E2A*/#define SQL_XML -370 /* @F1A*//* Handle types */#define SQL_UNUSED 0#define SQL_HANDLE_ENV 1#define SQL_HANDLE_DBC 2#define SQL_HANDLE_STMT 3#define SQL_HANDLE_DESC 4#define SQL_NULL_HANDLE 0

#define SQL_HANDLE_DBC_UNICODE 100

/** NULL status defines; these are used in SQLColAttributes, SQLDescribeCol,* to describe the nullability of a column in a table.*/#define SQL_NO_NULLS 0#define SQL_NULLABLE 1#define SQL_NULLABLE_UNKNOWN 2

/* Special length values */#define SQL_NO_TOTAL 0#define SQL_NULL_DATA -1#define SQL_DATA_AT_EXEC -2#define SQL_BIGINT_PREC 19#define SQL_INTEGER_PREC 10#define SQL_SMALLINT_PREC 5

/* SQLBindParam and SQLBindParameter Extended Indicator values @E2A*/#define SQL_DEFAULT_PARAM -5#define SQL_UNASSIGNED -7

/* SQLColAttributes defines */#define SQL_ATTR_READONLY 0#define SQL_ATTR_WRITE 1

SQL CLI


#define SQL_ATTR_READWRITE_UNKNOWN 2

/* Valid concurrency values */#define SQL_CONCUR_LOCK 0#define SQL_CONCUR_READ_ONLY 1#define SQL_CONCUR_ROWVER 3#define SQL_CONCUR_VALUES 4

/* Valid environment attributes */#define SQL_ATTR_OUTPUT_NTS 10001#define SQL_ATTR_SYS_NAMING 10002#define SQL_ATTR_DEFAULT_LIB 10003#define SQL_ATTR_SERVER_MODE 10004#define SQL_ATTR_JOB_SORT_SEQUENCE 10005#define SQL_ATTR_ENVHNDL_COUNTER 10009#define SQL_ATTR_ESCAPE_CHAR 10010#define SQL_ATTR_INCLUDE_NULL_IN_LEN 10031#define SQL_ATTR_UTF8 10032#define SQL_ATTR_SYSCAP 10033#define SQL_ATTR_REQUIRE_PROFILE 10034#define SQL_ATTR_TRUNCATION_RTNC 10036 /* @D1A*/

/* Valid environment/connection attributes */#define SQL_ATTR_EXTENDED_COL_INFO 10019#define SQL_ATTR_DATE_FMT 10020#define SQL_ATTR_DATE_SEP 10021#define SQL_ATTR_TIME_FMT 10022#define SQL_ATTR_TIME_SEP 10023#define SQL_ATTR_DECIMAL_SEP 10024#define SQL_ATTR_TXN_INFO 10025#define SQL_ATTR_TXN_EXTERNAL 10026#define SQL_ATTR_2ND_LEVEL_TEXT 10027#define SQL_ATTR_SAVEPOINT_NAME 10028#define SQL_ATTR_TRACE 10029#define SQL_ATTR_UCS2 10035#define SQL_ATTR_MAX_PRECISION 10040#define SQL_ATTR_MAX_SCALE 10041#define SQL_ATTR_MIN_DIVIDE_SCALE 10042#define SQL_ATTR_HEX_LITERALS 10043#define SQL_ATTR_CORRELATOR 10044 /* @D1A*/#define SQL_ATTR_QUERY_OPTIMIZE_GOAL 10045 /* @D3A*/#define SQL_ATTR_CONN_SORT_SEQUENCE 10046 /* @EDA*/#define SQL_ATTR_PREFETCH 10100 /* @E1A*/#define SQL_ATTR_CLOSEONEOF 10101 /* @E1A*/#define SQL_ATTR_ANSI_APP 10102 /* @E1A*/#define SQL_ATTR_INFO_USERID 10103 /* @E2A*/#define SQL_ATTR_INFO_WRKSTNNAME 10104 /* @E2A*/#define SQL_ATTR_INFO_APPLNAME 10105 /* @E2A*/#define SQL_ATTR_INFO_ACCTSTR 10106 /* @E2A*/#define SQL_ATTR_INFO_PROGRAMID 10107 /* @E2A*/#define SQL_ATTR_DECFLOAT_ROUNDING_MODE 10112 /* @E2A*/#define SQL_ATTR_OLD_MTADTA_BEHAVIOR 10113 /* @E2A*/#define SQL_ATTR_NULL_REQUIRED 10114 /* @E2A*/#define SQL_ATTR_FREE_LOCATORS 10115 /* @E2A*/#define SQL_ATTR_EXTENDED_INDICATORS 10116 /* @E2A*/#define SQL_ATTR_CONN_OUTPUT_NTS 10200 /* @E3A*/#define SQL_ATTR_CONN_TRUNCATION_RTNC 10202 /* @E3A*/#define SQL_ATTR_SERVERMODE_SUBSYSTEM 10204 /* @E3A*/#define SQL_ATTR_XML_DECLARATION 2552 /* @F1A*/#define SQL_ATTR_CURRENT_IMPLICIT_XMLPARSE_OPTION 2553 /* @F1A*/#define SQL_ATTR_CONCURRENT_ACCESS_RESOLUTION 2595 /*@F2A*/

/* Valid transaction info operations *//* Start Options */#define SQL_TXN_FIND 1 /* TMJOIN */#define SQL_TXN_CREATE 2 /* TMNOFLAGS */#define SQL_TXN_RESUME 7 /* TMRESUME @D5A*/

SQL CLI


/* End Options */#define SQL_TXN_CLEAR 3 /* TMSUSPEND */#define SQL_TXN_END 4 /* TMSUCCESS */

/* w/o HOLD */#define SQL_TXN_HOLD 5 /* TMSUCCESS */

/* w/HOLD @D1A*/#define SQL_TXN_END_FAIL 6 /* TMFAIL @D5A*/

/* Valid environment/connection values */#define SQL_FMT_ISO 1#define SQL_FMT_USA 2#define SQL_FMT_EUR 3#define SQL_FMT_JIS 4#define SQL_FMT_MDY 5#define SQL_FMT_DMY 6#define SQL_FMT_YMD 7#define SQL_FMT_JUL 8#define SQL_FMT_HMS 9#define SQL_FMT_JOB 10#define SQL_SEP_SLASH 1#define SQL_SEP_DASH 2#define SQL_SEP_PERIOD 3#define SQL_SEP_COMMA 4#define SQL_SEP_BLANK 5#define SQL_SEP_COLON 6#define SQL_SEP_JOB 7#define SQL_HEX_IS_CHAR 1#define SQL_HEX_IS_BINARY 2#define SQL_FIRST_IO 1 /* @D3A*/#define SQL_ALL_IO 2 /* @D3A*/

/** Options for Rounding Modes. These numeric values can* be set with SQLSetConnectAttr() API for the attribute* SQL_ATTR_DECFLOAT_ROUNDING_MODE. The SQLGetConnectAttr()* API will return these values for the* SQL_ATTR_DECFLOAT_ROUNDING_MODE attribute. @E2A*/#define ROUND_HALF_EVEN 0 /* @E2A*/#define ROUND_HALF_UP 1 /* @E2A*/#define ROUND_DOWN 2 /* @E2A*/#define ROUND_CEILING 3 /* @E2A*/#define ROUND_FLOOR 4 /* @E2A*/#define ROUND_HALF_DOWN 5 /* @E2A*/#define ROUND_UP 6 /* @E2A*/

/* Valid values for type in GetCol */#define SQL_DEFAULT 99#define SQL_ARD_TYPE -99

/* Valid values for UPDATE_RULE and DELETE_RULE in SQLForeignKeys */#define SQL_CASCADE 1#define SQL_RESTRICT 2#define SQL_NO_ACTION 3#define SQL_SET_NULL 4#define SQL_SET_DEFAULT 5

/* Valid values for result set column DEFERRABILITY inSQLForeignKeys */

#define SQL_INITIALLY_DEFERRED 5 /* @E2A*/#define SQL_INITIALLY_IMMEDIATE 6 /* @E2A*/#define SQL_NOT_DEFERRABLE 7 /* @E2A*/

/* Valid values for result set column PROCEDURE_TYPE inSQLProcedures */

#define SQL_PT_UNKNOWN 0 /* @E2A*/#define SQL_PT_PROCEDURE 1 /* @E2A*/#define SQL_PT_FUNCTION 2 /* @E2A*/

SQL CLI


/* Valid values for COLUMN_TYPE in SQLProcedureColumns */#define SQL_PARAM_INPUT 1#define SQL_PARAM_OUTPUT 2#define SQL_PARAM_INPUT_OUTPUT 3

/* statement attributes */#define SQL_ATTR_APP_ROW_DESC 10010#define SQL_ATTR_APP_PARAM_DESC 10011#define SQL_ATTR_IMP_ROW_DESC 10012#define SQL_ATTR_IMP_PARAM_DESC 10013#define SQL_ATTR_FOR_FETCH_ONLY 10014#define SQL_ATTR_CONCURRENCY 10014#define SQL_CONCURRENCY 10014#define SQL_ATTR_CURSOR_SCROLLABLE 10015#define SQL_ATTR_ROWSET_SIZE 10016#define SQL_ROWSET_SIZE 10016#define SQL_ATTR_ROW_ARRAY_SIZE 10016#define SQL_ATTR_CURSOR_HOLD 10017#define SQL_ATTR_FULL_OPEN 10018#define SQL_ATTR_BIND_TYPE 10049#define SQL_BIND_TYPE 10049#define SQL_ATTR_CURSOR_TYPE 10050#define SQL_CURSOR_TYPE 10050#define SQL_ATTR_CURSOR_SENSITIVITY 10051 /* @D1A*/#define SQL_CURSOR_SENSITIVE 10051 /* @D1A*/#define SQL_ATTR_ROW_STATUS_PTR 10052 /* @D3A*/#define SQL_ATTR_ROWS_FETCHED_PTR 10053 /* @D3A*/#define SQL_ATTR_ROW_BIND_TYPE 10056 /* @E2A*/#define SQL_ATTR_PARAM_BIND_TYPE 10057 /* @E2A*/#define SQL_ATTR_PARAMSET_SIZE 10058 /* @E2A*/#define SQL_ATTR_PARAM_STATUS_PTR 10059 /* @E2A*/#define SQL_ATTR_PARAMS_PROCESSED_PTR 10060 /* @E2A*/#define SQL_ATTR_NUMBER_RESULTSET_ROWS_PTR 10061 /* @E2A*/

/* values for setting statement attributes */#define SQL_BIND_BY_ROW 0#define SQL_BIND_BY_COLUMN 1#define SQL_CURSOR_FORWARD_ONLY 0#define SQL_CURSOR_STATIC 1#define SQL_CURSOR_DYNAMIC 2#define SQL_CURSOR_KEYSET_DRIVEN 3#define SQL_UNSPECIFIED 0 /* @D1A*/#define SQL_INSENSITIVE 1 /* @D1A*/#define SQL_SENSITIVE 2 /* @D1A*/

/* Codes used in FetchScroll */#define SQL_FETCH_NEXT 1#define SQL_FETCH_FIRST 2#define SQL_FETCH_LAST 3#define SQL_FETCH_PRIOR 4#define SQL_FETCH_ABSOLUTE 5#define SQL_FETCH_RELATIVE 6

/* SQLColAttributes defines */#define SQL_DESC_COUNT 1#define SQL_DESC_TYPE 2#define SQL_DESC_LENGTH 3#define SQL_DESC_LENGTH_PTR 4#define SQL_DESC_PRECISION 5#define SQL_DESC_SCALE 6#define SQL_DESC_DATETIME_INTERVAL_CODE 7#define SQL_DESC_NULLABLE 8#define SQL_DESC_INDICATOR_PTR 9#define SQL_DESC_DATA_PTR 10#define SQL_DESC_NAME 11#define SQL_DESC_UNNAMED 12

SQL CLI


#define SQL_DESC_DISPLAY_SIZE 13#define SQL_DESC_AUTO_INCREMENT 14#define SQL_DESC_SEARCHABLE 15#define SQL_DESC_UPDATABLE 16#define SQL_DESC_BASE_COLUMN 17#define SQL_DESC_BASE_TABLE 18#define SQL_DESC_BASE_SCHEMA 19#define SQL_DESC_LABEL 20#define SQL_DESC_MONEY 21#define SQL_DESC_TYPE_NAME 23 /* @D3A*/#define SQL_DESC_ALLOC_TYPE 99#define SQL_DESC_ALLOC_AUTO 1#define SQL_DESC_ALLOC_USER 2

#define SQL_COLUMN_COUNT 1#define SQL_COLUMN_TYPE 2#define SQL_COLUMN_LENGTH 3#define SQL_COLUMN_LENGTH_PTR 4#define SQL_COLUMN_PRECISION 5#define SQL_COLUMN_SCALE 6#define SQL_COLUMN_DATETIME_INTERVAL_CODE 7#define SQL_COLUMN_NULLABLE 8#define SQL_COLUMN_INDICATOR_PTR 9#define SQL_COLUMN_DATA_PTR 10#define SQL_COLUMN_NAME 11#define SQL_COLUMN_UNNAMED 12#define SQL_COLUMN_DISPLAY_SIZE 13#define SQL_COLUMN_AUTO_INCREMENT 14#define SQL_COLUMN_SEARCHABLE 15#define SQL_COLUMN_UPDATABLE 16#define SQL_COLUMN_BASE_COLUMN 17#define SQL_COLUMN_BASE_TABLE 18#define SQL_COLUMN_BASE_SCHEMA 19#define SQL_COLUMN_LABEL 20#define SQL_COLUMN_MONEY 21#define SQL_COLUMN_ALLOC_TYPE 99#define SQL_COLUMN_ALLOC_AUTO 1#define SQL_COLUMN_ALLOC_USER 2

/* Valid codes for SpecialColumns procedure */#define SQL_SCOPE_CURROW 0#define SQL_SCOPE_TRANSACTION 1#define SQL_SCOPE_SESSION 2#define SQL_PC_UNKNOWN 0#define SQL_PC_NOT_PSEUDO 1#define SQL_PC_PSEUDO 2

/* Valid values for connect attribute */#define SQL_ATTR_AUTO_IPD 10001#define SQL_ATTR_ACCESS_MODE 10002#define SQL_ACCESS_MODE 10002#define SQL_ATTR_AUTOCOMMIT 10003#define SQL_AUTOCOMMIT 10003#define SQL_ATTR_DBC_SYS_NAMING 10004#define SQL_ATTR_DBC_DEFAULT_LIB 10005#define SQL_ATTR_ADOPT_OWNER_AUTH 10006#define SQL_ATTR_SYSBAS_CMT 10007#define SQL_ATTR_SET_SSA 10008 /* @D3A*/#define SQL_ATTR_COMMIT 0#define SQL_MODE_READ_ONLY 0#define SQL_MODE_READ_WRITE 1#define SQL_MODE_DEFAULT 1#define SQL_AUTOCOMMIT_OFF 0#define SQL_AUTOCOMMIT_ON 1#define SQL_TXN_ISOLATION 0#define SQL_ATTR_TXN_ISOLATION 0#define SQL_COMMIT_NONE 1

SQL CLI


#define SQL_TXN_NO_COMMIT 1#define SQL_TXN_NOCOMMIT 1#define SQL_COMMIT_CHG 2#define SQL_COMMIT_UR 2#define SQL_TXN_READ_UNCOMMITTED 2#define SQL_COMMIT_CS 3#define SQL_TXN_READ_COMMITTED 3#define SQL_COMMIT_ALL 4#define SQL_COMMIT_RS 4#define SQL_TXN_REPEATABLE_READ 4#define SQL_COMMIT_RR 5#define SQL_TXN_SERIALIZABLE 5

/* Valid index flags */#define SQL_INDEX_UNIQUE 0#define SQL_INDEX_ALL 1#define SQL_INDEX_OTHER 3#define SQL_TABLE_STAT 0#define SQL_ENSURE 1#define SQL_QUICK 0

/* Valid trace values */#define SQL_ATTR_TRACE_CLI 1#define SQL_ATTR_TRACE_DBMON 2#define SQL_ATTR_TRACE_DEBUG 4#define SQL_ATTR_TRACE_JOBLOG 8#define SQL_ATTR_TRACE_STRTRC 16

/* Valid File Options */#define SQL_FILE_READ 2#define SQL_FILE_CREATE 8#define SQL_FILE_OVERWRITE 16#define SQL_FILE_APPEND 32

/* Valid types for GetDiagField */#define SQL_DIAG_RETURNCODE 1#define SQL_DIAG_NUMBER 2#define SQL_DIAG_ROW_COUNT 3#define SQL_DIAG_SQLSTATE 4#define SQL_DIAG_NATIVE 5#define SQL_DIAG_MESSAGE_TEXT 6#define SQL_DIAG_DYNAMIC_FUNCTION 7#define SQL_DIAG_CLASS_ORIGIN 8#define SQL_DIAG_SUBCLASS_ORIGIN 9#define SQL_DIAG_CONNECTION_NAME 10#define SQL_DIAG_SERVER_NAME 11#define SQL_DIAG_MESSAGE_TOKENS 12#define SQL_DIAG_AUTOGEN_KEY 14

/** SQLColAttributes defines* These are also used by SQLGetInfo*/

#define SQL_UNSEARCHABLE 0#define SQL_LIKE_ONLY 1#define SQL_ALL_EXCEPT_LIKE 2#define SQL_SEARCHABLE 3

/* GetFunctions() values to identify CLI functions */#define SQL_API_SQLALLOCCONNECT 1#define SQL_API_SQLALLOCENV 2#define SQL_API_SQLALLOCHANDLE 1001#define SQL_API_SQLALLOCSTMT 3#define SQL_API_SQLBINDCOL 4#define SQL_API_SQLBINDFILETOCOL 2002#define SQL_API_SQLBINDFILETOPARAM 2003#define SQL_API_SQLBINDPARAM 1002

SQL CLI


#define SQL_API_SQLBINDPARAMETER 1023#define SQL_API_SQLCANCEL 5#define SQL_API_SQLCLOSECURSOR 1003#define SQL_API_SQLCOLATTRIBUTE 6#define SQL_API_SQLCOLATTRIBUTEW 3001#define SQL_API_SQLCOLATTRIBUTES 11006#define SQL_API_SQLCOLATTRIBUTESW 3002#define SQL_API_SQLCOLUMNPRIVILEGES 2010#define SQL_API_SQLCOLUMNPRIVILEGESW 3003#define SQL_API_SQLCOLUMNS 40#define SQL_API_SQLCOLUMNSW 3004#define SQL_API_SQLCONNECT 7#define SQL_API_SQLCONNECTW 3005#define SQL_API_SQLCOPYDESC 1004#define SQL_API_SQLDATASOURCES 57#define SQL_API_SQLDATASOURCESW 3006#define SQL_API_SQLDESCRIBECOL 8#define SQL_API_SQLDESCRIBECOLW 3007#define SQL_API_SQLDESCRIBEPARAM 58#define SQL_API_SQLDISCONNECT 9#define SQL_API_SQLDRIVERCONNECT 68#define SQL_API_SQLENDTRAN 1005#define SQL_API_SQLERROR 10#define SQL_API_SQLERRORW 10010#define SQL_API_SQLEXECDIRECT 11#define SQL_API_SQLEXECDIRECTW 3008#define SQL_API_SQLEXECUTE 12 /* Add back in. @E1A*/#define SQL_API_SQLEXTENDEDFETCH 1022#define SQL_API_SQLFETCH 13#define SQL_API_SQLFETCHSCROLL 1021#define SQL_API_SQLFOREIGNKEYS 60#define SQL_API_SQLFOREIGNKEYSW 3009#define SQL_API_SQLFREECONNECT 14#define SQL_API_SQLFREEENV 15#define SQL_API_SQLFREEHANDLE 1006#define SQL_API_SQLFREESTMT 16#define SQL_API_SQLGETCOL 43#define SQL_API_SQLGETCONNECTATTR 1007#define SQL_API_SQLGETCONNECTATTRW 3010#define SQL_API_SQLGETCONNECTOPTION 42#define SQL_API_SQLGETCONNECTOPTIONW 3011#define SQL_API_SQLGETCURSORNAME 17#define SQL_API_SQLGETCURSORNAMEW 3012#define SQL_API_SQLGETDATA 43#define SQL_API_SQLGETDESCFIELD 1008#define SQL_API_SQLGETDESCFIELDW 3013#define SQL_API_SQLGETDESCREC 1009#define SQL_API_SQLGETDESCRECW 3014#define SQL_API_SQLGETDIAGFIELD 1010#define SQL_API_SQLGETDIAGFIELDW 3015#define SQL_API_SQLGETDIAGREC 1011#define SQL_API_SQLGETDIAGRECW 3016#define SQL_API_SQLGETENVATTR 1012#define SQL_API_SQLGETFUNCTIONS 44#define SQL_API_SQLGETINFO 45#define SQL_API_SQLGETINFOW 3017#define SQL_API_SQLGETLENGTH 2004#define SQL_API_SQLGETPOSITION 2005#define SQL_API_SQLGETPOSITIONW 3018#define SQL_API_SQLGETSTMTATTR 1014#define SQL_API_SQLGETSTMTATTRW 3019#define SQL_API_SQLGETSTMTOPTION 46#define SQL_API_SQLGETSTMTOPTIONW 3020#define SQL_API_SQLGETSUBSTRING 2006#define SQL_API_SQLGETSUBSTRINGW 3021#define SQL_API_SQLGETTYPEINFO 47#define SQL_API_SQLGETTYPEINFOW 3022

SQL CLI


#define SQL_API_SQLLANGUAGES 2001#define SQL_API_SQLMORERESULTS 61#define SQL_API_SQLNATIVESQL 62#define SQL_API_SQLNATIVESQLW 3023#define SQL_API_SQLNEXTRESULT 2009#define SQL_API_SQLNUMPARAMS 63#define SQL_API_SQLNUMRESULTCOLS 18#define SQL_API_SQLPARAMDATA 48#define SQL_API_SQLPARAMOPTIONS 2007#define SQL_API_SQLPREPARE 19#define SQL_API_SQLPREPAREW 3024#define SQL_API_SQLPRIMARYKEYS 65#define SQL_API_SQLPRIMARYKEYSW 3025#define SQL_API_SQLPROCEDURECOLUMNS 66#define SQL_API_SQLPROCEDURECOLUMNSW 3026#define SQL_API_SQLPROCEDURES 67#define SQL_API_SQLPROCEDURESW 3027#define SQL_API_SQLPUTDATA 49#define SQL_API_SQLRELEASEENV 1015#define SQL_API_SQLROWCOUNT 20#define SQL_API_SQLSETCONNECTATTR 1016#define SQL_API_SQLSETCONNECTATTRW 3028#define SQL_API_SQLSETCONNECTOPTION 50#define SQL_API_SQLSETCONNECTOPTIONW 3029#define SQL_API_SQLSETCURSORNAME 21#define SQL_API_SQLSETCURSORNAMEW 3030#define SQL_API_SQLSETDESCFIELD 1017#define SQL_API_SQLSETDESCFIELDW 3031#define SQL_API_SQLSETDESCREC 1018#define SQL_API_SQLSETENVATTR 1019#define SQL_API_SQLSETPARAM 22#define SQL_API_SQLSETSTMTATTR 1020#define SQL_API_SQLSETSTMTATTRW 3032#define SQL_API_SQLSETSTMTOPTION 51#define SQL_API_SQLSETSTMTOPTIONW 3033#define SQL_API_SQLSPECIALCOLUMNS 52#define SQL_API_SQLSPECIALCOLUMNSW 3034#define SQL_API_SQLSTARTTRAN 2008#define SQL_API_SQLSTATISTICS 53#define SQL_API_SQLSTATISTICSW 3035#define SQL_API_SQLTABLEPRIVILEGES 2011#define SQL_API_SQLTABLEPRIVILEGESW 3036#define SQL_API_SQLTABLES 54#define SQL_API_SQLTABLESW 3037#define SQL_API_SQLTRANSACT 23

/* unsupported APIs */#define SQL_API_SQLSETPOS -1

/* NULL handle defines */#ifdef __64BIT__#define SQL_NULL_HENV 0#define SQL_NULL_HDBC 0#define SQL_NULL_HSTMT 0#else#define SQL_NULL_HENV 0L#define SQL_NULL_HDBC 0L#define SQL_NULL_HSTMT 0L#endif

#ifdef __64BIT__#if !defined(SDWORD)typedef int SDWORD;#endif#if !defined(UDWORD)typedef unsigned int UDWORD;#endif

SQL CLI


#else#if !defined(SDWORD)typedef long int SDWORD;#endif#if !defined(UDWORD)typedef unsigned long int UDWORD;#endif#endif#if !defined(UWORD)typedef unsigned short int UWORD;#endif#if !defined(SWORD)typedef signed short int SWORD;#endif

#include "sql.h" /* SQL definitions @E1M*/

/* This should be temporary until math.h makes the typedef’s below permanent,without the need of STDC_WANT_DEC_FP or IBM_DFP declaration. Without thisfix QCPIMPRT.c fails b/c it includes math.h w/out these declaresset. @E2A*/

#include "math.h" /* Decimal floating point types @E2A*/

typedef char SQLCHAR;typedef wchar_t SQLWCHAR; /* W-API constant. @E1A*/typedef short int SQLSMALLINT;typedef UWORD SQLUSMALLINT;typedef UDWORD SQLUINTEGER;typedef double SQLDOUBLE;typedef float SQLREAL;

typedef void * PTR;typedef PTR SQLPOINTER;

#ifdef __64BIT__typedef int SQLINTEGER;typedef int HENV;typedef int HDBC;typedef int HSTMT;typedef int HDESC;typedef int SQLHANDLE;#elsetypedef long int SQLINTEGER;typedef long HENV;typedef long HDBC;typedef long HSTMT;typedef long HDESC;typedef long SQLHANDLE;#endif

typedef HENV SQLHENV;typedef HDBC SQLHDBC;typedef HSTMT SQLHSTMT;typedef HDESC SQLHDESC;

typedef SQLINTEGER RETCODE;typedef RETCODE SQLRETURN;

typedef float SFLOAT;

typedef SQLPOINTER SQLHWND;

/** DATE, TIME, and TIMESTAMP structures. These are for compatibility

SQL CLI


* purposes only. When actually specifying or retrieving DATE, TIME,* and TIMESTAMP values, character strings must be used.*/

typedef struct DATE_STRUCT{

SQLSMALLINT year;SQLSMALLINT month;SQLSMALLINT day;

} DATE_STRUCT;

typedef struct TIME_STRUCT{

SQLSMALLINT hour;SQLSMALLINT minute;SQLSMALLINT second;

} TIME_STRUCT;

typedef struct TIMESTAMP_STRUCT{

SQLSMALLINT year;SQLSMALLINT month;SQLSMALLINT day;SQLSMALLINT hour;SQLSMALLINT minute;SQLSMALLINT second;SQLINTEGER fraction; /* fraction of a second */

} TIMESTAMP_STRUCT;

/* Transaction info structure */typedef struct TXN_STRUCT {

SQLINTEGER operation;SQLCHAR tminfo[10];SQLCHAR reserved1[2];void *XID;SQLINTEGER timeoutval;SQLINTEGER locktimeout;SQLCHAR reserved2[8];

} TXN_STRUCT;

SQL_EXTERN SQLRETURN SQLAllocConnect (SQLHENV henv,SQLHDBC *phdbc);

SQL_EXTERN SQLRETURN SQLAllocEnv (SQLHENV *phenv);

SQL_EXTERN SQLRETURN SQLAllocHandle (SQLSMALLINT htype,SQLINTEGER ihnd,SQLINTEGER *ohnd);

SQL_EXTERN SQLRETURN SQLAllocStmt (SQLHDBC hdbc,SQLHSTMT *phstmt);

SQL_EXTERN SQLRETURN SQLBindCol (SQLHSTMT hstmt,SQLSMALLINT icol,SQLSMALLINT iType,SQLPOINTER rgbValue,SQLINTEGER cbValueMax,SQLINTEGER *pcbValue);

SQL_EXTERN SQLRETURN SQLBindFileToCol (SQLHSTMT hstmt,

SQL CLI


SQLSMALLINT icol,SQLCHAR *fName,SQLSMALLINT *fNameLen,SQLINTEGER *fOptions,SQLSMALLINT fValueMax,SQLINTEGER *sLen,SQLINTEGER *pcbValue);

SQL_EXTERN SQLRETURN SQLBindFileToParam (SQLHSTMT hstmt,SQLSMALLINT ipar,SQLSMALLINT iType,SQLCHAR *fName,SQLSMALLINT *fNameLen,SQLINTEGER *fOptions,SQLSMALLINT fValueMax,SQLINTEGER *pcbValue);

SQL_EXTERN SQLRETURN SQLBindParam (SQLHSTMT hstmt,SQLSMALLINT iparm,SQLSMALLINT iType,SQLSMALLINT pType,SQLINTEGER pLen,SQLSMALLINT pScale,SQLPOINTER pData,SQLINTEGER *pcbValue);

SQL_EXTERN SQLRETURN SQLBindParameter (SQLHSTMT hstmt,SQLSMALLINT ipar,SQLSMALLINT fParamType,SQLSMALLINT fCType,SQLSMALLINT fSQLType,SQLINTEGER pLen,SQLSMALLINT pScale,SQLPOINTER pData,SQLINTEGER cbValueMax,SQLINTEGER *pcbValue);

SQL_EXTERN SQLRETURN SQLCancel (SQLHSTMT hstmt);

SQL_EXTERN SQLRETURN SQLCloseCursor (SQLHSTMT hstmt);

SQL_EXTERN SQLRETURN SQLColAttribute (SQLHSTMT hstmt,SQLSMALLINT icol,SQLSMALLINT fDescType,SQLPOINTER rgbDesc,SQLSMALLINT cbDescMax,SQLSMALLINT *pcbDesc,SQLPOINTER pfDesc);

/* @E1C*/

SQL_EXTERN SQLRETURN SQLColAttributeW (SQLHSTMT hstmt,SQLSMALLINT icol,SQLSMALLINT fDescType,SQLPOINTER rgbDesc,SQLSMALLINT cbDescMax,SQLSMALLINT *pcbDesc,SQLPOINTER pfDesc);

/* @E1C*/

SQL_EXTERN SQLRETURN SQLColAttributes (SQLHSTMT hstmt,SQLSMALLINT icol,SQLSMALLINT fDescType,SQLCHAR *rgbDesc,SQLINTEGER cbDescMax,SQLINTEGER *pcbDesc,SQLINTEGER *pfDesc);

SQL CLI


SQL_EXTERN SQLRETURN SQLColAttributesW (SQLHSTMT hstmt,SQLSMALLINT icol,SQLSMALLINT fDescType,SQLWCHAR *rgbDesc,SQLINTEGER cbDescMax,SQLINTEGER *pcbDesc,SQLINTEGER *pfDesc);

SQL_EXTERN SQLRETURN SQLColumnPrivileges (SQLHSTMT hstmt,SQLCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLCHAR *szTableName,SQLSMALLINT cbTableName,SQLCHAR *szColumnName,SQLSMALLINT cbColumnName);

SQL_EXTERN SQLRETURN SQLColumnPrivilegesW (SQLHSTMT hstmt,SQLWCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLWCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLWCHAR *szTableName,SQLSMALLINT cbTableName,SQLWCHAR *szColumnName,SQLSMALLINT cbColumnName);

SQL_EXTERN SQLRETURN SQLColumns (SQLHSTMT hstmt,SQLCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLCHAR *szTableName,SQLSMALLINT cbTableName,SQLCHAR *szColumnName,SQLSMALLINT cbColumnName);

SQL_EXTERN SQLRETURN SQLColumnsW (SQLHSTMT hstmt,SQLWCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLWCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLWCHAR *szTableName,SQLSMALLINT cbTableName,SQLWCHAR *szColumnName,SQLSMALLINT cbColumnName);

SQL_EXTERN SQLRETURN SQLConnect (SQLHDBC hdbc,SQLCHAR *szDSN,SQLSMALLINT cbDSN,SQLCHAR *szUID,SQLSMALLINT cbUID,SQLCHAR *szAuthStr,SQLSMALLINT cbAuthStr);

SQL_EXTERN SQLRETURN SQLConnectW (SQLHDBC hdbc,SQLWCHAR *szDSN,SQLSMALLINT cbDSN,SQLWCHAR *szUID,SQLSMALLINT cbUID,SQLWCHAR *szAuthStr,SQLSMALLINT cbAuthStr);

SQL_EXTERN SQLRETURN SQLCopyDesc (SQLHDESC sDesc,SQLHDESC tDesc);

SQL CLI


SQL_EXTERN SQLRETURN SQLDataSources (SQLHENV henv,SQLSMALLINT fDirection,SQLCHAR *szDSN,SQLSMALLINT cbDSNMax,SQLSMALLINT *pcbDSN,SQLCHAR *szDescription,SQLSMALLINT cbDescriptionMax,SQLSMALLINT *pcbDescription);

SQL_EXTERN SQLRETURN SQLDataSourcesW (SQLHENV henv,SQLSMALLINT fDirection,SQLWCHAR *szDSN,SQLSMALLINT cbDSNMax,SQLSMALLINT *pcbDSN,SQLWCHAR *szDescription,SQLSMALLINT cbDescriptionMax,SQLSMALLINT *pcbDescription);

SQL_EXTERN SQLRETURN SQLDescribeCol (SQLHSTMT hstmt,SQLSMALLINT icol,SQLCHAR *szColName,SQLSMALLINT cbColNameMax,SQLSMALLINT *pcbColName,SQLSMALLINT *pfSqlType,SQLINTEGER *pcbColDef,SQLSMALLINT *pibScale,SQLSMALLINT *pfNullable);

SQL_EXTERN SQLRETURN SQLDescribeColW (SQLHSTMT hstmt,SQLSMALLINT icol,SQLWCHAR *szColName,SQLSMALLINT cbColNameMax,SQLSMALLINT *pcbColName,SQLSMALLINT *pfSqlType,SQLINTEGER *pcbColDef,SQLSMALLINT *pibScale,SQLSMALLINT *pfNullable);

SQL_EXTERN SQLRETURN SQLDescribeParam (SQLHSTMT hstmt,SQLSMALLINT ipar,SQLSMALLINT *pfSqlType,SQLINTEGER *pcbColDef,SQLSMALLINT *pibScale,SQLSMALLINT *pfNullable);

SQL_EXTERN SQLRETURN SQLDisconnect (SQLHDBC hdbc);

SQL_EXTERN SQLRETURN SQLDriverConnect (SQLHDBC hdbc,SQLPOINTER hwnd,SQLCHAR *szConnStrIn,SQLSMALLINT cbConnStrin,SQLCHAR *szConnStrOut,SQLSMALLINT cbConnStrOutMax,SQLSMALLINT *pcbConnStrOut,

SQLSMALLINT fDriverCompletion);

SQL_EXTERN SQLRETURN SQLDriverConnectW (SQLHDBC hdbc,SQLPOINTER hwnd,SQLWCHAR *szConnStrIn,SQLSMALLINT cbConnStrin,SQLWCHAR *szConnStrOut,SQLSMALLINT cbConnStrOutMax,SQLSMALLINT *pcbConnStrOut,SQLSMALLINT fDriverCompletion);

SQL_EXTERN SQLRETURN SQLEndTran (SQLSMALLINT htype,

SQL CLI


SQLHENV henv,SQLSMALLINT ctype);

SQL_EXTERN SQLRETURN SQLError (SQLHENV henv,SQLHDBC hdbc,SQLHSTMT hstmt,SQLCHAR *szSqlState,SQLINTEGER *pfNativeError,SQLCHAR *szErrorMsg,SQLSMALLINT cbErrorMsgMax,SQLSMALLINT *pcbErrorMsg);

SQL_EXTERN SQLRETURN SQLErrorW (SQLHENV henv,SQLHDBC hdbc,SQLHSTMT hstmt,SQLWCHAR *szSqlState,SQLINTEGER *pfNativeError,SQLWCHAR *szErrorMsg,SQLSMALLINT cbErrorMsgMax,SQLSMALLINT *pcbErrorMsg);

SQL_EXTERN SQLRETURN SQLExecDirect (SQLHSTMT hstmt,SQLCHAR *szSqlStr,SQLINTEGER cbSqlStr);

SQL_EXTERN SQLRETURN SQLExecDirectW (SQLHSTMT hstmt,SQLWCHAR *szSqlStr,SQLINTEGER cbSqlStr);

SQL_EXTERN SQLRETURN SQLExecute (SQLHSTMT hstmt);

SQL_EXTERN SQLRETURN SQLExtendedFetch (SQLHSTMT hstmt,SQLSMALLINT fOrient,SQLINTEGER fOffset,SQLINTEGER *pcrow,SQLSMALLINT *rgfRowStatus);

SQL_EXTERN SQLRETURN SQLFetch (SQLHSTMT hstmt);

SQL_EXTERN SQLRETURN SQLFetchScroll (SQLHSTMT hstmt,SQLSMALLINT fOrient,SQLINTEGER fOffset);

SQL_EXTERN SQLRETURN SQLForeignKeys (SQLHSTMT hstmt,SQLCHAR *szPkTableQualifier,SQLSMALLINT cbPkTableQualifier,SQLCHAR *szPkTableOwner,SQLSMALLINT cbPkTableOwner,SQLCHAR *szPkTableName,SQLSMALLINT cbPkTableName,SQLCHAR *szFkTableQualifier,SQLSMALLINT cbFkTableQualifier,SQLCHAR *szFkTableOwner,SQLSMALLINT cbFkTableOwner,SQLCHAR *szFkTableName,SQLSMALLINT cbFkTableName);

SQL_EXTERN SQLRETURN SQLForeignKeysW (SQLHSTMT hstmt,SQLWCHAR *szPkTableQualifier,SQLSMALLINT cbPkTableQualifier,SQLWCHAR *szPkTableOwner,SQLSMALLINT cbPkTableOwner,SQLWCHAR *szPkTableName,SQLSMALLINT cbPkTableName,SQLWCHAR *szFkTableQualifier,SQLSMALLINT cbFkTableQualifier,

SQL CLI


SQLWCHAR *szFkTableOwner,SQLSMALLINT cbFkTableOwner,SQLWCHAR *szFkTableName,SQLSMALLINT cbFkTableName);

SQL_EXTERN SQLRETURN SQLFreeConnect (SQLHDBC hdbc);

SQL_EXTERN SQLRETURN SQLFreeEnv (SQLHENV henv);

SQL_EXTERN SQLRETURN SQLFreeStmt (SQLHSTMT hstmt,SQLSMALLINT fOption);

SQL_EXTERN SQLRETURN SQLFreeHandle (SQLSMALLINT htype,SQLINTEGER hndl);

SQL_EXTERN SQLRETURN SQLGetCol (SQLHSTMT hstmt,SQLSMALLINT icol,SQLSMALLINT itype,SQLPOINTER tval,SQLINTEGER blen,SQLINTEGER *olen);

SQL_EXTERN SQLRETURN SQLGetColW (SQLHSTMT hstmt,SQLSMALLINT icol,SQLSMALLINT itype,SQLPOINTER tval,SQLINTEGER blen,SQLINTEGER *olen);

SQL_EXTERN SQLRETURN SQLGetConnectAttr (SQLHDBC hdbc,SQLINTEGER attr,SQLPOINTER oval,SQLINTEGER ilen,SQLINTEGER *olen);

SQL_EXTERN SQLRETURN SQLGetConnectAttrW (SQLHDBC hdbc,SQLINTEGER attr,SQLPOINTER oval,SQLINTEGER ilen,SQLINTEGER *olen);

SQL_EXTERN SQLRETURN SQLGetConnectOption (SQLHDBC hdbc,SQLSMALLINT iopt,SQLPOINTER oval);

SQL_EXTERN SQLRETURN SQLGetConnectOptionW (SQLHDBC hdbc,SQLSMALLINT iopt,SQLPOINTER oval);

SQL_EXTERN SQLRETURN SQLGetCursorName (SQLHSTMT hstmt,SQLCHAR *szCursor,SQLSMALLINT cbCursorMax,SQLSMALLINT *pcbCursor);

SQL_EXTERN SQLRETURN SQLGetCursorNameW (SQLHSTMT hstmt,SQLWCHAR *szCursor,SQLSMALLINT cbCursorMax,SQLSMALLINT *pcbCursor);

SQL_EXTERN SQLRETURN SQLGetData (SQLHSTMT hstmt,SQLSMALLINT icol,SQLSMALLINT fCType,SQLPOINTER rgbValue,SQLINTEGER cbValueMax,SQLINTEGER *pcbValue);

SQL_EXTERN SQLRETURN SQLGetDescField (SQLHDESC hdesc,

SQL CLI


SQLSMALLINT rcdNum,SQLSMALLINT fieldID,SQLPOINTER fValue,SQLINTEGER fLength,SQLINTEGER *stLength);

SQL_EXTERN SQLRETURN SQLGetDescFieldW (SQLHDESC hdesc,SQLSMALLINT rcdNum,SQLSMALLINT fieldID,SQLPOINTER fValue,SQLINTEGER fLength,SQLINTEGER *stLength);

SQL_EXTERN SQLRETURN SQLGetDescRec (SQLHDESC hdesc,SQLSMALLINT rcdNum,SQLCHAR *fname,SQLSMALLINT bufLen,SQLSMALLINT *sLength,SQLSMALLINT *sType,SQLSMALLINT *sbType,SQLINTEGER *fLength,SQLSMALLINT *fprec,SQLSMALLINT *fscale,SQLSMALLINT *fnull);

SQL_EXTERN SQLRETURN SQLGetDescRecW (SQLHDESC hdesc,SQLSMALLINT rcdNum,SQLWCHAR *fname,SQLSMALLINT bufLen,SQLSMALLINT *sLength,SQLSMALLINT *sType,SQLSMALLINT *sbType,SQLINTEGER *fLength,SQLSMALLINT *fprec,SQLSMALLINT *fscale,SQLSMALLINT *fnull);

SQL_EXTERN SQLRETURN SQLGetDiagField (SQLSMALLINT hType,SQLINTEGER hndl,SQLSMALLINT rcdNum,SQLSMALLINT diagID,SQLPOINTER dValue,SQLSMALLINT bLength,SQLSMALLINT *sLength);

SQL_EXTERN SQLRETURN SQLGetDiagFieldW (SQLSMALLINT hType,SQLINTEGER hndl,SQLSMALLINT rcdNum,SQLSMALLINT diagID,SQLPOINTER dValue,SQLSMALLINT bLength,SQLSMALLINT *sLength);

SQL_EXTERN SQLRETURN SQLGetDiagRec (SQLSMALLINT hType,SQLINTEGER hndl,SQLSMALLINT rcdNum,SQLCHAR *SQLstate,SQLINTEGER *SQLcode,SQLCHAR *msgText,SQLSMALLINT bLength,SQLSMALLINT *SLength);

SQL_EXTERN SQLRETURN SQLGetDiagRecW (SQLSMALLINT hType,SQLINTEGER hndl,SQLSMALLINT rcdNum,SQLWCHAR *SQLstate,SQLINTEGER *SQLcode,

SQL CLI


SQLWCHAR *msgText,SQLSMALLINT bLength,SQLSMALLINT *SLength);

SQL_EXTERN SQLRETURN SQLGetEnvAttr (SQLHENV hEnv,SQLINTEGER fAttribute,SQLPOINTER pParam,SQLINTEGER cbParamMax,SQLINTEGER * pcbParam);

SQL_EXTERN SQLRETURN SQLGetFunctions (SQLHDBC hdbc,SQLSMALLINT fFunction,SQLSMALLINT *pfExists);

SQL_EXTERN SQLRETURN SQLGetInfo (SQLHDBC hdbc,SQLSMALLINT fInfoType,SQLPOINTER rgbInfoValue,SQLSMALLINT cbInfoValueMax,SQLSMALLINT *pcbInfoValue);

SQL_EXTERN SQLRETURN SQLGetInfoW (SQLHDBC hdbc,SQLSMALLINT fInfoType,SQLPOINTER rgbInfoValue,SQLSMALLINT cbInfoValueMax,SQLSMALLINT *pcbInfoValue);

SQL_EXTERN SQLRETURN SQLGetLength (SQLHSTMT hstmt,SQLSMALLINT locType,SQLINTEGER locator,SQLINTEGER *sLength,SQLINTEGER *ind);

SQL_EXTERN SQLRETURN SQLGetPosition (SQLHSTMT hstmt,SQLSMALLINT locType,SQLINTEGER srceLocator,SQLINTEGER srchLocator,SQLCHAR *srchLiteral,SQLINTEGER srchLiteralLen,SQLINTEGER fPosition,SQLINTEGER *located,SQLINTEGER *ind);

SQL_EXTERN SQLRETURN SQLGetPositionW (SQLHSTMT hstmt,SQLSMALLINT locType,SQLINTEGER srceLocator,SQLINTEGER srchLocator,SQLWCHAR *srchLiteral,SQLINTEGER srchLiteralLen,SQLINTEGER fPosition,SQLINTEGER *located,SQLINTEGER *ind);

SQL_EXTERN SQLRETURN SQLGetStmtAttr (SQLHSTMT hstmt,SQLINTEGER fAttr,SQLPOINTER pvParam,SQLINTEGER bLength,SQLINTEGER *SLength);

SQL_EXTERN SQLRETURN SQLGetStmtAttrW (SQLHSTMT hstmt,SQLINTEGER fAttr,SQLPOINTER pvParam,SQLINTEGER bLength,SQLINTEGER *SLength);

SQL_EXTERN SQLRETURN SQLGetStmtOption (SQLHSTMT hstmt,SQLSMALLINT fOption,SQLPOINTER pvParam);

SQL CLI


SQL_EXTERN SQLRETURN SQLGetStmtOptionW (SQLHSTMT hstmt,SQLSMALLINT fOption,SQLPOINTER pvParam);

SQL_EXTERN SQLRETURN SQLGetSubString (SQLHSTMT hstmt,SQLSMALLINT locType,SQLINTEGER srceLocator,SQLINTEGER fPosition,SQLINTEGER length,SQLSMALLINT tType,SQLPOINTER rgbValue,SQLINTEGER cbValueMax,SQLINTEGER *StringLength,SQLINTEGER *ind);

SQL_EXTERN SQLRETURN SQLGetSubStringW (SQLHSTMT hstmt,SQLSMALLINT locType,SQLINTEGER srceLocator,SQLINTEGER fPosition,SQLINTEGER length,SQLSMALLINT tType,SQLPOINTER rgbValue,SQLINTEGER cbValueMax,SQLINTEGER *StringLength,SQLINTEGER *ind);

SQL_EXTERN SQLRETURN SQLGetTypeInfo (SQLHSTMT hstmt,SQLSMALLINT fSqlType);

SQL_EXTERN SQLRETURN SQLGetTypeInfoW (SQLHSTMT hstmt,SQLSMALLINT fSqlType);

SQL_EXTERN SQLRETURN SQLLanguages (SQLHSTMT hstmt);

SQL_EXTERN SQLRETURN SQLMoreResults (SQLHSTMT hstmt);

SQL_EXTERN SQLRETURN SQLNativeSql (SQLHDBC hdbc,SQLCHAR *szSqlStrIn,SQLINTEGER cbSqlStrIn,SQLCHAR *szSqlStr,SQLINTEGER cbSqlStrMax,SQLINTEGER *pcbSqlStr);

SQL_EXTERN SQLRETURN SQLNativeSqlW (SQLHDBC hdbc,SQLWCHAR *szSqlStrIn,SQLINTEGER cbSqlStrIn,SQLWCHAR *szSqlStr,SQLINTEGER cbSqlStrMax,SQLINTEGER *pcbSqlStr);

SQL_EXTERN SQLRETURN SQLNextResult (SQLHSTMT hstmt,SQLHSTMT hstmt2);

SQL_EXTERN SQLRETURN SQLNumParams (SQLHSTMT hstmt,SQLSMALLINT *pcpar);

SQL_EXTERN SQLRETURN SQLNumResultCols (SQLHSTMT hstmt,SQLSMALLINT *pccol);

SQL_EXTERN SQLRETURN SQLParamData (SQLHSTMT hstmt,SQLPOINTER *Value);

SQL_EXTERN SQLRETURN SQLParamOptions (SQLHSTMT hstmt,SQLINTEGER crow,SQLINTEGER *pirow);

SQL CLI


SQL_EXTERN SQLRETURN SQLPrepare (SQLHSTMT hstmt,SQLCHAR *szSqlStr,SQLSMALLINT cbSqlStr);

SQL_EXTERN SQLRETURN SQLPrepareW (SQLHSTMT hstmt,SQLWCHAR *szSqlStr,SQLSMALLINT cbSqlStr);

SQL_EXTERN SQLRETURN SQLPrimaryKeys (SQLHSTMT hstmt,SQLCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLCHAR *szTableName,SQLSMALLINT cbTableName);

SQL_EXTERN SQLRETURN SQLPrimaryKeysW (SQLHSTMT hstmt,SQLWCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLWCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLWCHAR *szTableName,SQLSMALLINT cbTableName);

SQL_EXTERN SQLRETURN SQLProcedureColumns (SQLHSTMT hstmt,SQLCHAR *szProcQualifier,SQLSMALLINT cbProcQualifier,SQLCHAR *szProcOwner,SQLSMALLINT cbProcOwner,SQLCHAR *szProcName,SQLSMALLINT cbProcName,SQLCHAR *szColumnName,SQLSMALLINT cbColumnName);

SQL_EXTERN SQLRETURN SQLProcedureColumnsW (SQLHSTMT hstmt,SQLWCHAR *szProcQualifier,SQLSMALLINT cbProcQualifier,SQLWCHAR *szProcOwner,SQLSMALLINT cbProcOwner,SQLWCHAR *szProcName,SQLSMALLINT cbProcName,SQLWCHAR *szColumnName,SQLSMALLINT cbColumnName);

SQL_EXTERN SQLRETURN SQLProcedures (SQLHSTMT hstmt,SQLCHAR *szProcQualifier,SQLSMALLINT cbProcQualifier,SQLCHAR *szProcOwner,SQLSMALLINT cbProcOwner,SQLCHAR *szProcName,SQLSMALLINT cbProcName);

SQL_EXTERN SQLRETURN SQLProceduresW (SQLHSTMT hstmt,SQLWCHAR *szProcQualifier,SQLSMALLINT cbProcQualifier,SQLWCHAR *szProcOwner,SQLSMALLINT cbProcOwner,SQLWCHAR *szProcName,SQLSMALLINT cbProcName);

SQL_EXTERN SQLRETURN SQLPutData (SQLHSTMT hstmt,SQLPOINTER Data,SQLINTEGER SLen);

SQL_EXTERN SQLRETURN SQLReleaseEnv (SQLHENV henv);

SQL_EXTERN SQLRETURN SQLRowCount (SQLHSTMT hstmt,

SQL CLI


SQLINTEGER *pcrow);

SQL_EXTERN SQLRETURN SQLSetConnectAttr (SQLHDBC hdbc,SQLINTEGER attrib,SQLPOINTER vParam,SQLINTEGER inlen);

SQL_EXTERN SQLRETURN SQLSetConnectAttrW (SQLHDBC hdbc,SQLINTEGER attrib,SQLPOINTER vParam,SQLINTEGER inlen);

SQL_EXTERN SQLRETURN SQLSetConnectOption (SQLHDBC hdbc,SQLSMALLINT fOption,SQLPOINTER vParam);

SQL_EXTERN SQLRETURN SQLSetConnectOptionW (SQLHDBC hdbc,SQLSMALLINT fOption,SQLPOINTER vParam);

SQL_EXTERN SQLRETURN SQLSetCursorName (SQLHSTMT hstmt,SQLCHAR *szCursor,SQLSMALLINT cbCursor);

SQL_EXTERN SQLRETURN SQLSetCursorNameW (SQLHSTMT hstmt,SQLWCHAR *szCursor,SQLSMALLINT cbCursor);

SQL_EXTERN SQLRETURN SQLSetDescField (SQLHDESC hdesc,SQLSMALLINT rcdNum,SQLSMALLINT fID,SQLPOINTER Value,SQLINTEGER buffLen);

SQL_EXTERN SQLRETURN SQLSetDescFieldW (SQLHDESC hdesc,SQLSMALLINT rcdNum,SQLSMALLINT fID,SQLPOINTER Value,SQLINTEGER buffLen);

SQL_EXTERN SQLRETURN SQLSetDescRec (SQLHDESC hdesc,SQLSMALLINT rcdNum,SQLSMALLINT Type,SQLSMALLINT subType,SQLINTEGER fLength,SQLSMALLINT fPrec,SQLSMALLINT fScale,SQLPOINTER Value,SQLINTEGER *sLength,SQLINTEGER *indic);

SQL_EXTERN SQLRETURN SQLSetEnvAttr( SQLHENV hEnv,SQLINTEGER fAttribute,SQLPOINTER pParam,SQLINTEGER cbParam);

SQL_EXTERN SQLRETURN SQLSetParam (SQLHSTMT hstmt,SQLSMALLINT ipar,SQLSMALLINT fCType,SQLSMALLINT fSqlType,SQLINTEGER cbColDef,SQLSMALLINT ibScale,SQLPOINTER rgbValue,SQLINTEGER *pcbValue);

SQL_EXTERN SQLRETURN SQLSetStmtAttr (SQLHSTMT hstmt,SQLINTEGER fAttr,

SQL CLI


SQLPOINTER pParam,SQLINTEGER vParam);

SQL_EXTERN SQLRETURN SQLSetStmtAttrW (SQLHSTMT hstmt,SQLINTEGER fAttr,SQLPOINTER pParam,SQLINTEGER vParam);

SQL_EXTERN SQLRETURN SQLSetStmtOption (SQLHSTMT hstmt,SQLSMALLINT fOption,SQLPOINTER vParam);

SQL_EXTERN SQLRETURN SQLSetStmtOptionW (SQLHSTMT hstmt,SQLSMALLINT fOption,SQLPOINTER vParam);

SQL_EXTERN SQLRETURN SQLSpecialColumns (SQLHSTMT hstmt,SQLSMALLINT fColType,SQLCHAR *szTableQual,SQLSMALLINT cbTableQual,SQLCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLCHAR *szTableName,SQLSMALLINT cbTableName,SQLSMALLINT fScope,SQLSMALLINT fNullable);

SQL_EXTERN SQLRETURN SQLSpecialColumnsW (SQLHSTMT hstmt,SQLSMALLINT fColType,SQLWCHAR *szTableQual,SQLSMALLINT cbTableQual,SQLWCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLWCHAR *szTableName,SQLSMALLINT cbTableName,SQLSMALLINT fScope,SQLSMALLINT fNullable);

SQL_EXTERN SQLRETURN SQLStartTran (SQLSMALLINT htype,SQLHENV henv,SQLINTEGER mode,SQLINTEGER clevel);

SQL_EXTERN SQLRETURN SQLStatistics (SQLHSTMT hstmt,SQLCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLCHAR *szTableName,SQLSMALLINT cbTableName,SQLSMALLINT fUnique,

SQLSMALLINT fres);

SQL_EXTERN SQLRETURN SQLStatisticsW (SQLHSTMT hstmt,SQLWCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLWCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLWCHAR *szTableName,SQLSMALLINT cbTableName,SQLSMALLINT fUnique,SQLSMALLINT fres);

SQL_EXTERN SQLRETURN SQLTablePrivileges (SQLHSTMT hstmt,SQLCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLCHAR *szTableOwner,

SQL CLI


SQLSMALLINT cbTableOwner,SQLCHAR *szTableName,SQLSMALLINT cbTableName);

SQL_EXTERN SQLRETURN SQLTablePrivilegesW (SQLHSTMT hstmt,SQLWCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLWCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLWCHAR *szTableName,SQLSMALLINT cbTableName);

SQL_EXTERN SQLRETURN SQLTables (SQLHSTMT hstmt,SQLCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLCHAR *szTableName,SQLSMALLINT cbTableName,SQLCHAR *szTableType,SQLSMALLINT cbTableType);

SQL_EXTERN SQLRETURN SQLTablesW (SQLHSTMT hstmt,SQLWCHAR *szTableQualifier,SQLSMALLINT cbTableQualifier,SQLWCHAR *szTableOwner,SQLSMALLINT cbTableOwner,SQLWCHAR *szTableName,SQLSMALLINT cbTableName,SQLWCHAR *szTableType,SQLSMALLINT cbTableType);

SQL_EXTERN SQLRETURN SQLTransact (SQLHENV henv,SQLHDBC hdbc,SQLSMALLINT fType);

#define FAR#define SQL_SQLSTATE_SIZE 5 /* size of SQLSTATE, not including

null terminating byte */#define SQL_MAX_DSN_LENGTH 18 /* maximum data source name size */#define SQL_MAX_ID_LENGTH 18 /* maximum identifier name size,

e.g. cursor names */#define SQL_MAXLSTR 255 /* Maximum length of an LSTRING */#define SQL_LVCHAROH 26 /* Overhead for LONG VARCHAR in */

/* record */#define SQL_LOBCHAROH 312 /* Overhead for LOB in record */

/* Moved SQLWCHAR constant @E1M*/

/* SQL extended data types (negative means unsupported) */#define SQL_TINYINT -6#define SQL_BIT -7#define SQL_UNSIGNED_OFFSET -22 /* @E3A*/#define SQL_SIGNED_OFFSET -20 /* @E3A*/

/* C data type to SQL data type mapping */#define SQL_C_CHAR SQL_CHAR /* CHAR, VARCHAR, DECIMAL, NUMERIC */#define SQL_C_LONG SQL_INTEGER /* INTEGER */#define SQL_C_SLONG SQL_INTEGER /* INTEGER */#define SQL_C_SHORT SQL_SMALLINT /* SMALLINT */#define SQL_C_FLOAT SQL_REAL /* REAL */#define SQL_C_DOUBLE SQL_DOUBLE /* FLOAT, DOUBLE */#define SQL_C_DATE SQL_DATE /* DATE */#define SQL_C_TIME SQL_TIME /* TIME */#define SQL_C_TIMESTAMP SQL_TIMESTAMP /* TIMESTAMP */#define SQL_C_BINARY SQL_BINARY /* BINARY, VARBINARY */

SQL CLI


#define SQL_C_BIT SQL_BIT#define SQL_C_TINYINT SQL_TINYINT#define SQL_C_BIGINT SQL_BIGINT#define SQL_C_DBCHAR SQL_DBCLOB#define SQL_C_WCHAR SQL_WCHAR /* UNICODE */#define SQL_C_DATETIME SQL_DATETIME /* DATETIME */#define SQL_C_BLOB SQL_BLOB#define SQL_C_CLOB SQL_CLOB#define SQL_C_DBCLOB SQL_DBCLOB#define SQL_C_BLOB_LOCATOR SQL_BLOB_LOCATOR#define SQL_C_CLOB_LOCATOR SQL_CLOB_LOCATOR#define SQL_C_DBCLOB_LOCATOR SQL_DBCLOB_LOCATOR#define SQL_C_DECIMAL128 -361 /* 128 byte decimal floating point @E2A*/#define SQL_C_DECIMAL64 SQL_DECFLOAT /* 64 byte decimal floating point @E2A*/#define SQL_C_DECIMAL32 -362 /* 32 byte decimal floating point @E2A*/#define SQL_C_UTINYINT (SQL_TINYINT + SQL_UNSIGNED_OFFSET)

/* Unsigned TINYINT type (-28) @E3A*/#define SQL_C_STINYINT (SQL_TINYINT + SQL_SIGNED_OFFSET)

/* Signed TINYINT type (-26) @E3A*/

/* Additional decimal floating point constants and structures @E2A*/#define SQL_DECIMAL64_COEFFICIENT_LEN 8 /* @E2A*/#define SQL_DECIMAL128_COEFFICIENT_LEN 16 /* @E2A*/

typedef struct tagSQLDECIMAL64 {union {SQLDOUBLE dummy; /* Dummy member for alignment @E2A*/SQLCHAR dec64[SQL_DECIMAL64_COEFFICIENT_LEN];

#if defined(__STDC_WANT_DEC_FP__) && \(__OS400_TGTVRM__ >= 550) && defined(__IBM_DFP__)

_Decimal64 decfloat64; /* Native DECFLOAT(16) type @E2A*/#endif} udec64;} SQLDECIMAL64; /* @E2A*/

typedef struct tagSQLDECIMAL128 {union {SQLDOUBLE dummy; /* Dummy member for alignment @E2A*/SQLCHAR dec128[SQL_DECIMAL128_COEFFICIENT_LEN];

#if defined(__STDC_WANT_DEC_FP__) && \(__OS400_TGTVRM__ >= 550) && defined(__IBM_DFP__)

_Decimal128 decfloat128; /* Native DECFLOAT(16) type @E2A*/#endif} udec128;} SQLDECIMAL128; /* @E2A*/

/* miscellaneous constants and unsupported functions */#define SQL_ADD -1#define SQL_DELETE -1#define SQL_KEYSET_SIZE -1#define SQL_LCK_NO_CHANGE -1#define SQL_LOCK_NO_CHANGE -1#define SQL_LOCK_EXCLUSIVE -1#define SQL_LOCK_UNLOCK -1#define SQL_METH_D -1#define SQL_POSITION -1#define SQL_QUERY_TIMEOUT -1#define SQL_ROW_ADDED -1#define SQL_ROW_NOROW 1 /* @D3C*/#define SQL_ROW_ERROR -1#define SQL_ROW_SUCCESS 0#define SQL_ROW_SUCCESS_WITH_INFO -1#define SQL_SC_TRY_UNIQUE -1#define SQL_SIMULATE_CURSOR -1#define SQL_UNKNOWN_TYPE -1#define SQL_UPDATE -1#define SQL_UNIC_DATA 99 /* @D3A*/

SQL CLI


/* Constants used for block array insert support */#define SQL_PARAM_SUCCESS 0 /* @E2A*/#define SQL_PARAM_DIAG_UNAVAILABLE 1 /* @E2A*/#define SQL_PARAM_ERROR 5 /* @E2A*/#define SQL_PARAM_SUCCESS_WITH_INFO 6 /* @E2A*/#define SQL_PARAM_UNUSED 7 /* @E2A*/

#define SQL_WARN_VAL_TRUNC "01004"

#if (__OS400_TGTVRM__>=510) /* @B1A*/#pragma datamodel(pop) /* @B1A*/#endif /* @B1A*/

#ifndef __ILEC400__#pragma info(restore)#endif

#endif /* SQL_H_SQLCLI */

Running Db2 for i CLI in server modeThe reason for running in SQL server mode is that many applications need to act as database servers.This means that a single job performs SQL requests on behalf of multiple users.

Without using SQL server mode, applications might encounter one or more of the following limitations:v A single job can have only one commit transaction per activation group.v A single job can be connected to a relational database (RDB) only once.v All SQL statements run under the user profile of the job, regardless of the user ID passed on the

connection.

SQL server mode circumvents these limitations by routing all SQL statements to separate jobs. Eachconnection runs in its own job. The system uses prestart jobs named QSQSRVR in the QSYSWRKsubsystem or a selected subsystem to minimize the startup time for each connection. Because each call toSQLConnect() can accept a different user profile, each job also has its own commit transaction. As soon asthe SQLDisconnect() has been performed, the job is reset and put back in the pool of available jobs.

Starting Db2 for i CLI in SQL server modeThere are two ways to place a job into SQL server mode.v The most used method is using the call level interface (CLI) function, SQLSetEnvAttr(). The SQL server

mode is best suited to CLI applications because they already use the concept of multiple connectionshandles. Set this mode immediately after allocating the CLI environment. If server mode is not setimmediately following the allocation of the CLI environment then the mode will not be changed toserver mode, and SQL continues to run inline.

EXAMPLE..SQLAllocEnv(&henv);long attr;attr = SQL_TRUESQLSetEnvAttr(henv,SQL_ATTR_SERVER_MODE,&attr,0);SQLAllocConnect(henv,&hdbc);..

v The second way to set the server mode is using the Change Job (QWTCHGJB) API.

SQL CLI


As soon as SQL server mode has been set, all SQL connections and SQL statements run in server mode.There is no switching back and forth. The job, when in server mode, cannot start commitment control,and cannot use Interactive SQL.Related information:Application programming interfaces

Restrictions for running Db2 for i CLI in server modeHere are the restrictions when you run Db2 for i CLI in server mode.v A job must set the server mode at the very beginning of processing before doing anything else. For

jobs that are strictly CLI users, they must use the SQLSetEnvAttr call to turn on server mode.Remember to do this right after SQLAllocEnv but before any other calls. As soon as the server mode ison, it cannot be turned off.

v All the SQL functions run in the prestart jobs and commitment control. Do not start commitmentcontrol in the originating job either before or after entering server mode.

v Because the SQL is processed in the prestart job, there is no sensitivity to certain changes in theoriginating job. This includes changes to library list, job priority, message logging, and so forth. Theprestart is sensitive to a change of the coded character set identifier (CCSID) value in the originatingjob, because this can affect the way data is mapped back to the program of the user.

v When running server mode, the application must use SQL commits and rollbacks, either embedded orby the SQL CLI. They cannot use the CL commands, because there is no commitment control that isrunning in the originating job. The job must issue a COMMIT statement before disconnecting;otherwise an implicit ROLLBACK occurs.

v It is not possible to use interactive SQL from a job in server mode. Use of STRSQL when in servermode results in an SQL6141 message.

v It is also not possible to perform SQL compilation in server mode. Server mode can be used whenrunning compiled SQL programs, but must not be on for the compiles. The compiles fail if the job is inserver mode.

v Function SQLDataSources() is unique in that it does not require a connection handle to run. When inserver mode, the program must already have done a connection to the local database before usingSQLDataSources(). Because SQLDataSources() is used to find the name of the RDB for connection, IBMsupports passing a NULL pointer for the RDB name on SQLConnect() to obtain a local connection. Thismakes it possible to write a generic program, when there is no prior knowledge of the system names.

v When doing commits and rollbacks through the CLI, the calls to SQLEndTran() and SQLTransact()must include a connection handle. When not running in server mode, one can omit the connectionhandle to commit everything. However, this is not supported in server mode, because each connection(or thread) has its own transaction scoping.

v It is not recommended to share connection handles across threads, when running in SQL server mode.This is because one thread can overwrite return data or error information that another thread has yetto process.

v Before V6R1, running CLI applications and Native JDBC applications in the same job will lead tounpredictable behavior. In most cases it will lead to errors. In V6R1 it is possible to run Native JDBCand CLI applications in the same job provided each interface runs in server mode and the CLIapplications do not set any CLI environment attributes. CLI attributes can be specified at theconnection and statement levels instead.

v Within a single job, CLI allows for a one time switch from non-server mode to server mode. Asdiscussed earlier, it does not allow an application to switch from running in server mode to non-servermode.

Related reference:“SQLDataSources - Get list of data sources” on page 81SQLDataSources() returns a list of target databases available, one at a time. A database must be catalogedto be available.

SQL CLI


Unicode in Db2 for i CLIDb2 for i CLI provides several ways for applications to take advantage of Unicode in their applications.

This support is available for two different Unicode encodings, UTF-8 and UTF-16. Additional supportexists for specifying a UCS-2 encoded character string only when preparing an SQL statement.

UTF-16 encoding support

Support for UTF-16 encoded character data is provided through a set of API's called the "Wide" API's.These API's accept as input and return as output UTF-16 data. This allows applications to run with aUnicode coded character set identifier (CCSID) of 1200, instead of being dependent upon the defaultCCSID of the job running the Db2 for i CLI work. In most cases the default CCSID of the job is anEBCDIC CCSID. Since the UTF-16 encoded character set is a superset of the UCS-2 encoded character set(CCSID 13488), applications can encode their character data in UCS-2 as well. CLI API functions havesuffixes to indicate the format of their string arguments: those that accept Unicode end in W, and thosethat accept EBCDIC have no suffix. The following is a list of functions that are available in Db2 for i CLIwhich have both EBCDIC and Unicode versions:

Table 179. List of functions with both EBCIDIC and Unicode versions

Functions Functions (continued) Functions (continued)

SQLColAttributeW SQLColAttributesW SQLColumnPrivilegesW

SQLColumnsW SQLConnectW SQLDataSourcesW

SQLDescribeColW SQLDriverConnectW SQLErrorW

SQLExecDirectW SQLForeignKeysW SQLGetConnectAttrW

SQLGetConnectOptionW SQLGetCursorNameW SQLGetDescFieldW

SQLGetDescRecW SQLGetDiagFieldW SQLGetDiagRecW

SQLGetInfoW SQLGetPositionW SQLGetStmtAttrW

SQLGetStmtOptionW SQLGetSubStringW SQLGetTypeInfoW

SQLNativeSQLW SQLPrepareW SQLPrimaryKeysW

SQLProcedureColumnsW SQLProceduresW SQLSetConnectAttrW

SQLSetConnectOptionW SQLSetCursorNameW SQLSetDescFieldW

SQLSetStmtAttrW SQLSetStmtOptionW SQLSpecialColumnsW

SQLStatisticsW SQLTablePrivilegesW SQLTablesW

The syntax for a Db2 for i CLI Wide function is the same as the syntax for its corresponding EBCDICfunction, except that SQLCHAR parameters are defined as SQLWCHAR. Character buffers defined asSQLPOINTER in the EBCDIC syntax can be defined as either SQLCHAR or SQLWCHAR in the Unicodefunction. Refer to the EBCDIC version of the CLI Unicode functions for EBCDIC syntax details.

The SQL types SQL_WCHAR and SQL_WVARCHAR can be used to specify a buffer that containsUnicode data. So, to specify a particular column or parameter marker containing Unicode data theapplication can bind as SQL_WCHAR for fixed length character data or bind as SQL_WVARCHAR forvarying length character data. Since UTF-16 data is double byte character data the input and outputlengths must take this into account. Unicode functions that have arguments which are always characterstrings interpret these arguments as the number of double byte characters. When the length might referto string or non-string data, the length will be interpreted as the number of bytes needed to store thedata. For example, the SQLGetInfoW()SQLGetInfoW() API accepts the input length as the number of bytes,while SQLPrepareW() accepts the number of double byte character's.

SQL CLI


Db2 for i CLI allows for the mixing of the Wide character API's and non-Wide character API's.Applications must take into account that Unicode data can only be specified for the Wide API calls, andnot the non-Wide API calls. Most applications will probably want to commit to either running withUnicode encoding or will choose to run with a non-Unicode character encoding since most data will be ina consistent encoding. However, support does exist for mixing Unicode and non-Unicode calls in thesame CLI environment. Db2 for i CLI does restrict the mixing of Wide character API's and anenvironment with UTF-8 support enabled. Enabling UTF-8 support is discussed in the next section.

UTF-8 encoding support

Support for UTF-8 encoded character data is provided through the setting of an environment orconnection attribute, SQL_ATTR_UTF8. Setting the attribute to SQL_TRUE will indicate that all input andoutput data is to be treated as Unicode character data. This support allows applications to run with aUnicode coded character set identifier (CCSID) of 1208, instead of being dependent upon the defaultCCSID of the job running the Db2 for i CLI work. The UTF-8 support does not require any new data typebindings by the application. When binding, applications can continue to use SQL_CHAR for fixed lengthcharacter data and SQL_VARCHAR can be used for varying length character data. When an applicationbinds as any character SQL type, Db2 for i CLI will take care of tagging the data with the UTF-8 CCSID,so Db2 for i will translate the data properly. UTF-8 data is handled on every Db2 for i CLI API that takescharacter data as input and returns character data as output. Each of the API's which has a matchingwide character version also supports UTF-8 character data. See the list of API's in the previous section toidentify which functions support both UTF-16 and UTF-8 Unicode character data. Functions that acceptboth a UTF-8 string and a length expect the length to be in bytes, not in characters. This is in contrast tothe Wide API's which expect the length to be in the number of double byte characters in most cases. Aswas discussed in the previous section, mixing a UTF-8 environment with calls to the Wide character API'sis restricted. Additionally, unlike the Wide character API's, which allow alternating calls between Unicodeand non-Unicode supported API's, once the UTF-8 environment is setup, all input and output characterdata is expected to be in the UTF-8 encoding by Db2 for i CLI.

UCS-2 encoding support

Db2 for i CLI provides some specific support for UCS-2 encoded character strings. This support wasadded before the Wide API support, and therefore is not a complete solution for applications wanting toenable full Unicode support in Db2 for i CLI. Since the UTF-16 encoded character set is a superset of theUCS-2 character set, applications can get full UCS-2 support through the use of the Wide API's discussedearlier in the "Unicode in Db2 for i CLI" section. To enable this limited UCS-2 support, set the connectionattribute SQL_ATTR_UCS2 to SQL_TRUE. This will tell Db2 for i CLI to treat input strings as UCS-2character data at prepare time. SQL statements can be prepared using either the SQLPrepare() orSQLExecDirect() API's. This support does not allow for UCS-2 character strings on input or output forany other Db2 for i CLI API's.

Examples: Db2 for i CLI applicationsThese examples have been drawn from the applications provided in the SQL call level interface topiccollection. Detailed error checking has not been implemented in the examples.

Example: Embedded SQL and the equivalent Db2 for i CLI functioncallsThis example shows embedded statements in comments and the equivalent Db2 for i CLI function calls.

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./*************************************************************************** file = embedded.c**

SQL CLI


** Example of executing an SQL statement using CLI.** The equivalent embedded SQL statements are shown in comments.**** Functions used:**** SQLAllocConnect SQLFreeConnect** SQLAllocEnv SQLFreeEnv** SQLAllocStmt SQLFreeStmt** SQLConnect SQLDisconnect**** SQLBindCol SQLFetch** SQLSetParam SQLTransact** SQLError SQLExecDirect****************************************************************************/#include <stdio.h>#include <string.h>#include "sqlcli.h"

#ifndef NULL#define NULL 0#endif

int print_err (SQLHDBC hdbc,SQLHSTMT hstmt);

int main (){

SQLHENV henv;SQLHDBC hdbc;SQLHSTMT hstmt;

SQLCHAR server[] = "sample";SQLCHAR uid[30];SQLCHAR pwd[30];

SQLINTEGER id;SQLCHAR name[51];SQLINTEGER namelen, intlen;SQLSMALLINT scale;

scale = 0;

/* EXEC SQL CONNECT TO :server USER :uid USING :authentication_string; */SQLAllocEnv (&henv); /* allocate an environment handle */

SQLAllocConnect (henv, &hdbc); /* allocate a connection handle */

/* Connect to database indicated by "server" variable with *//* authorization-name given in "uid", authentication-string given *//* in "pwd". Note server, uid, and pwd contain null-terminated *//* strings, as indicated by the 3 input lengths set to SQL_NTS */if (SQLConnect (hdbc, server, SQL_NTS, NULL, SQL_NTS, NULL, SQL_NTS)

!= SQL_SUCCESS)return (print_err (hdbc, SQL_NULL_HSTMT));

SQLAllocStmt (hdbc, &hstmt); /* allocate a statement handle */

/* EXEC SQL CREATE TABLE NAMEID (ID integer, NAME varchar(50)); */{

SQLCHAR create[] = "CREATE TABLE NAMEID (ID integer, NAME varchar(50))";

/* execute the sql statement */if (SQLExecDirect (hstmt, create, SQL_NTS) != SQL_SUCCESS)

SQL CLI


return (print_err (hdbc, hstmt));}

/* EXEC SQL COMMIT WORK; */SQLTransact (henv, hdbc, SQL_COMMIT); /* commit create table */

/* EXEC SQL INSERT INTO NAMEID VALUES ( :id, :name */{

SQLCHAR insert[] = "INSERT INTO NAMEID VALUES (?, ?)";

/* show the use of SQLPrepare/SQLExecute method *//* prepare the insert */

if (SQLPrepare (hstmt, insert, SQL_NTS) != SQL_SUCCESS)return (print_err (hdbc, hstmt));

/* Set up the first input parameter "id" */intlen = sizeof (SQLINTEGER);SQLSetParam (hstmt, 1,

SQL_C_LONG, SQL_INTEGER,(SQLINTEGER) sizeof (SQLINTEGER),scale, (SQLPOINTER) &id,

(SQLINTEGER *) &intlen);

namelen = SQL_NTS;/* Set up the second input parameter "name" */

SQLSetParam (hstmt, 2,SQL_C_CHAR, SQL_VARCHAR,50,scale, (SQLPOINTER) name,(SQLINTEGER *) &namelen);

/* now assign parameter values and execute the insert */id=500;strcpy (name, "Babbage");

if (SQLExecute (hstmt) != SQL_SUCCESS)return (print_err (hdbc, hstmt));

}

/* EXEC SQL COMMIT WORK; */SQLTransact (henv, hdbc, SQL_COMMIT); /* commit inserts */

/* EXEC SQL DECLARE c1 CURSOR FOR SELECT ID, NAME FROM NAMEID; *//* EXEC SQL OPEN c1; *//* The application doesn’t specify "declare c1 cursor for" */{

SQLCHAR select[] = "select ID, NAME from NAMEID";if (SQLExecDirect (hstmt, select, SQL_NTS) != SQL_SUCCESS)

return (print_err (hdbc, hstmt));}

/* EXEC SQL FETCH c1 INTO :id, :name; *//* Binding first column to output variable "id" */SQLBindCol (hstmt, 1,

SQL_C_LONG, (SQLPOINTER) &id,(SQLINTEGER) sizeof (SQLINTEGER),(SQLINTEGER *) &intlen);

/* Binding second column to output variable "name" */SQLBindCol (hstmt, 2,

SQL CLI


SQL_C_CHAR, (SQLPOINTER) name,(SQLINTEGER) sizeof (name),&namelen);

SQLFetch (hstmt); /* now execute the fetch */printf("Result of Select: id = %ld name = %s\n", id, name);

/* finally, we should commit, discard hstmt, disconnect *//* EXEC SQL COMMIT WORK; */SQLTransact (henv, hdbc, SQL_COMMIT); /* commit the transaction */

/* EXEC SQL CLOSE c1; */SQLFreeStmt (hstmt, SQL_DROP); /* free the statement handle */

/* EXEC SQL DISCONNECT; */SQLDisconnect (hdbc); /* disconnect from the database */

SQLFreeConnect (hdbc); /* free the connection handle */SQLFreeEnv (henv); /* free the environment handle */

return (0);}

int print_err (SQLHDBC hdbc,SQLHSTMT hstmt)


while ( SQLError(SQL_NULL_HENV, hdbc, hstmt,sqlstate,&sqlcode,buffer,SQL_MAX_MESSAGE_LENGTH + 1,&length) == SQL_SUCCESS )

{printf("SQLSTATE: %s Native Error Code: %ld\n",

sqlstate, sqlcode);printf("%s \n", buffer);printf("----------------------------- \n");

};

return(SQL_ERROR);

}

Example: Using the CLI XA transaction connection attributesThis example shows how to use the call level interface (CLI) XA transaction connection attributes.

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321./*************************************************************************** file = CLIXAEXMP1.c**** Example of a typical flow of work in an XA transaction using the CLI.**** XA Functions used:**** xa_open() -- Open an XA resource for use in a transaction** xa_prepare() -- Prepare for commitment of work in the transaction** xa_commit() -- Commit work done in the transaction**

SQL CLI


** CLI Functions used:**** SQLAllocHanle SQLBindParameter SQLDisconnect** SQLError SQLExecute SQLFreeHandle** SQLPrepare SQLSetConnectAttr SQLSetEnvAttr**** This example will:** - Open the XA transaction manager** - Open a CLI connection and start a transaction for it using SQL_TXN_CREATE** - Do some commitable CLI work under this transaction** - End the transaction on the first connection using SQL_TXN_END** - Close the first CLI connection and open a second connection** - Use the SQL_TXN_FIND option to find the previous transaction** - Do more commitable work on this transaction and end the transaction** - Use the XA APIs to prepare and commit the work************************************************************************************/#define _XA_PROTOTYPES#define _MULTI_THREADED#include <xa.h>#include <stdio.h>#include <string.h>#include <sqlcli.h>#include <time.h>#include <stdlib.h>

void genXid(XID *xid) {time_t t;memset(xid, 0, sizeof(xid));xid->formatID = 69;xid->gtrid_length = 4;xid->bqual_length = 4;/* xid->data must be a globally unique naming identifier

when taking gtrid and bqual together - the example belowis most likely not unique */

/* gtrid contents */xid->data[0] = 0xFA;xid->data[1] = 0xED;xid->data[2] = 0xFA;xid->data[3] = 0xED;time(&t);/* bqual contents */xid->data[4] = (((int)t) >> 24) & 0xFF;xid->data[5] = (((int)t) >> 16) & 0xFF;xid->data[6] = (((int)t) >> 8) & 0xFF;xid->data[7] = (((int)t) >> 0) & 0xFF;

}

int main(int argc, char **argv){/***************************************************//* Declarations Section *//***************************************************/

SQLHENV henv;SQLHDBC hdbc;SQLHSTMT hstmt;SQLRETURN rtnc;SQLINTEGER attr;SQLINTEGER int_buffer;SQLINTEGER rlength;SQLINTEGER buffint;SQLINTEGER ilen;SQLCHAR s[80];SQLCHAR state[10];SQLCHAR buffer[600];SQLCHAR sqlstr[600];SQLINTEGER natErr;SQLSMALLINT len;

SQL CLI


/* Declare local XA variables */struct TXN_STRUCT new;XID xid;char xaOpenFormat[128];int mainRmid = 1;int xaRc;

/* Initialize the XA structure variable’s (defined in sqlcli.h) */strcpy(new.tminfo,"MYPRODUCT");strcpy(new.reserved1,"");new.timeoutval = 0;new.locktimeout = 0;strcpy(new.reserved2,"");genXid(&xid);new.XID = &xid;

/* Use the XA APIs to start the transaction manager *//* The xa_info argument for xa_open MUST include the THDCTL=C keyword

and value when using using CLI with XA transactions */sprintf(xaOpenFormat, "RDBNAME=*LOCAL THDCTL=C");xaRc = xa_open(xaOpenFormat, mainRmid, TMNOFLAGS);printf("xa_open(%s, %d, TMNOFLAGS) = %d\n",

xaOpenFormat, mainRmid, xaRc);

/* Setup the CLI resources */attr=SQL_TRUE;rtnc=SQLAllocHandle(SQL_HANDLE_ENV,SQL_NULL_HANDLE,&henv);rtnc=SQLSetEnvAttr(henv,SQL_ATTR_SERVER_MODE,&attr,0); /* set server mode */rtnc=SQLAllocHandle(SQL_HANDLE_DBC,henv,&hdbc);

/* Mark the connection as an external transaction and connect */rtnc=SQLSetConnectAttr(hdbc,SQL_ATTR_TXN_EXTERNAL,&attr,0);rtnc=SQLConnect(hdbc,NULL,0,NULL,0,NULL,0);

/* Start the transaction */new.operation = SQL_TXN_CREATE;rtnc=SQLSetConnectAttr(hdbc,SQL_ATTR_TXN_INFO,&new,0);

/* Do some CLI work */rtnc=SQLAllocHandle(SQL_HANDLE_STMT,hdbc,&hstmt);strcpy(sqlstr,"insert into tab values(?)");rtnc=SQLPrepare(hstmt,sqlstr,SQL_NTS);rtnc=SQLBindParameter(hstmt,1,1,SQL_INTEGER,SQL_INTEGER,10,2,&buffint,0,&ilen);buffint=10; /* set the integer value to insert */rtnc=SQLExecute(hstmt);if (rtnc!=SQL_SUCCESS){

printf("SQLExecute failed with return code: %i \n", rtnc);rtnc=SQLError(0, 0,hstmt, state, &natErr, buffer, 600, &len);printf("%i is the SQLCODE\n",natErr);printf("%i is the length of error text\n",len);printf("%s is the state\n",state );printf("%s \n",buffer);

}else

printf("SQLExecute succeeded, value %i inserted \n", buffint);

/* End the transaction */new.operation = SQL_TXN_END;rtnc=SQLSetConnectAttr(hdbc,SQL_ATTR_TXN_INFO,&new,0);

/* Cleanup and disconnect from the first connection */rtnc=SQLFreeHandle(SQL_HANDLE_STMT,hstmt);

rtnc=SQLDisconnect(hdbc);

SQL CLI


/* Mark the second connection as an external transaction and connect */attr=SQL_TRUE;rtnc=SQLSetConnectAttr(hdbc,SQL_ATTR_TXN_EXTERNAL,&attr,0);rtnc=SQLConnect(hdbc,NULL,0,NULL,0,NULL,0);

/* Find the open transaction from the first connection */new.operation = SQL_TXN_FIND;rtnc=SQLSetConnectAttr(hdbc,SQL_ATTR_TXN_INFO,&new,0);

/* Do some CLI work on the second connection */rtnc=SQLAllocHandle(SQL_HANDLE_STMT,hdbc,&hstmt);strcpy(sqlstr,"insert into tab values(?)");rtnc=SQLPrepare(hstmt,sqlstr,SQL_NTS);rtnc=SQLBindParameter(hstmt,1,1,SQL_INTEGER,SQL_INTEGER,10,2,&buffint,0,&ilen);buffint=15; /* set the integer value to insert */rtnc=SQLExecute(hstmt);if (rtnc!=SQL_SUCCESS){

printf("SQLExecute failed with return code: %i \n", rtnc);rtnc=SQLError(0, 0,hstmt, state, &natErr, buffer, 600, &len);printf("%i is the SQLCODE\n",natErr);printf("%i is the length of error text\n",len);printf("%s is the state\n",state );printf("%s \n",buffer);

}else

printf("Second SQLExecute succeeded, value %i inserted \n", buffint);

/* End the transaction */new.operation = SQL_TXN_END;rtnc=SQLSetConnectAttr(hdbc,SQL_ATTR_TXN_INFO,&new,0);

/* Now, use XA to prepare/commit transaction *//* Prepare to commit */xaRc = xa_prepare(&xid, mainRmid, TMNOFLAGS);printf("xa_prepare(xid, %d, TMNOFLAGS) = %d\n",mainRmid, xaRc);

/* Commit */if (xaRc != XA_RDONLY) {

xaRc = xa_commit(&xid, mainRmid, TMNOFLAGS);printf("xa_commit(xid, %d, TMNOFLAGS) = %d\n", mainRmid, xaRc);

}else {

printf("xa_commit() skipped for read only TX\n");}

/* Cleanup the CLI resources */rtnc=SQLFreeHandle(SQL_HANDLE_STMT,hstmt);

rtnc=SQLDisconnect(hdbc);rtnc=SQLFreeHandle(SQL_HANDLE_DBC,hdbc);rtnc=SQLFreeHandle(SQL_HANDLE_ENV,henv);

return 0;}

Example: Interactive SQL and the equivalent Db2 for i CLI functioncallsThis example shows the processing of interactive SQL statements.

This example follows the flow described in “Writing a Db2 for i CLI application” on page 6.

Note: By using the code examples, you agree to the terms of the “Code license and disclaimerinformation” on page 321.

SQL CLI


/*************************************************************************** file = typical.c**** Example of executing interactive SQL statements, displaying result sets** and simple transaction management.**** Functions used:**** SQLAllocConnect SQLFreeConnect** SQLAllocEnv SQLFreeEnv** SQLAllocStmt SQLFreeStmt** SQLConnect SQLDisconnect**** SQLBindCol SQLFetch** SQLDescribeCol SQLNumResultCols** SQLError SQLRowCount** SQLExecDirect SQLTransact****************************************************************************/

#include <stdlib.h>#include <stdio.h>#include <string.h>#include "sqlcli.h"

#define MAX_STMT_LEN 255#define MAXCOLS 100

#define max(a,b) (a > b ? a : b)


int process_stmt(SQLHENV henv,SQLHDBC hdbc,SQLCHAR *sqlstr);


int print_error(SQLHENV henv,SQLHDBC hdbc,SQLHSTMT hstmt);

int check_error(SQLHENV henv,SQLHDBC hdbc,SQLHSTMT hstmt,SQLRETURN frc);

void display_results(SQLHSTMT hstmt,SQLSMALLINT nresultcols);

/********************************************************************* main** - initialize** - start a transaction** - get statement** - another statement?** - COMMIT or ROLLBACK** - another transaction?** - terminate*******************************************************************/int main(){

SQLHENV henv;SQLHDBC hdbc;SQLCHAR sqlstmt[MAX_STMT_LEN + 1]="";

SQL CLI


SQLCHAR sqltrans[sizeof("ROLLBACK")];SQLRETURN rc;


printf("Enter an SQL statement to start a transaction(or ’q’ to Quit):\n");gets(sqlstmt);

while (sqlstmt[0] !=’q’){

while (sqlstmt[0] != ’q’){ rc = process_stmt(henv, hdbc, sqlstmt);

if (rc == SQL_ERROR) return(SQL_ERROR);printf("Enter an SQL statement(or ’q’ to Quit):\n");gets(sqlstmt);

}

printf("Enter ’c’ to COMMIT or ’r’ to ROLLBACK the transaction\n");fgets(sqltrans, sizeof("ROLLBACK"), stdin);

if (sqltrans[0] == ’c’){

rc = SQLTransact (henv, hdbc, SQL_COMMIT);if (rc == SQL_SUCCESS)

printf ("Transaction commit was successful\n");else


if (sqltrans[0] == ’r’){

rc = SQLTransact (henv, hdbc, SQL_ROLLBACK);if (rc == SQL_SUCCESS)

printf ("Transaction roll back was successful\n");else


printf("Enter an SQL statement to start a transaction or ’q’ to quit\n");gets(sqlstmt);

}

terminate(henv, hdbc);

return (SQL_SUCCESS);}/* end main */

/********************************************************************* process_stmt** - allocates a statement handle** - executes the statement** - determines the type of statement** - if there are no result columns, therefore non-select statement** - if rowcount > 0, assume statement was UPDATE, INSERT, DELETE** else** - assume a DDL, or Grant/Revoke statement** else** - must be a select statement.** - display results** - frees the statement handle*******************************************************************/

int process_stmt (SQLHENV henv,SQLHDBC hdbc,SQLCHAR *sqlstr)

{

SQL CLI


SQLHSTMT hstmt;SQLSMALLINT nresultcols;SQLINTEGER rowcount;SQLRETURN rc;

SQLAllocStmt (hdbc, &hstmt); /* allocate a statement handle */

/* execute the SQL statement in "sqlstr" */

rc = SQLExecDirect (hstmt, sqlstr, SQL_NTS);if (rc != SQL_SUCCESS)

if (rc == SQL_NO_DATA_FOUND) {printf("\nStatement executed without error, however,\n");printf("no data was found or modified\n");return (SQL_SUCCESS);

}else


SQLRowCount (hstmt, &rowcount);rc = SQLNumResultCols (hstmt, &nresultcols);if (rc != SQL_SUCCESS)


/* determine statement type */if (nresultcols == 0) /* statement is not a select statement */{

if (rowcount > 0 ) /* assume statement is UPDATE, INSERT, DELETE */{

printf ("Statement executed, %ld rows affected\n", rowcount);}

else /* assume statement is GRANT, REVOKE or a DLL statement */{

printf ("Statement completed successful\n");}

}else /* display the result set */{

display_results(hstmt, nresultcols);} /* end determine statement type */

SQLFreeStmt (hstmt, SQL_DROP ); /* free statement handle */

return (0);}/* end process_stmt */

/********************************************************************* initialize** - allocate environment handle** - allocate connection handle** - prompt for server, user id, & password** - connect to server*******************************************************************/


{SQLCHAR server[18],

uid[10],pwd[10];

SQLRETURN rc;

rc = SQLAllocEnv (henv); /* allocate an environment handle */if (rc != SQL_SUCCESS )


SQL CLI


rc = SQLAllocConnect (*henv, hdbc); /* allocate a connection handle */if (rc != SQL_SUCCESS )







}}/* end initialize */

/********************************************************************* terminate** - disconnect** - free connection handle** - free environment handle*******************************************************************/int terminate(SQLHENV henv,

SQLHDBC hdbc){SQLRETURN rc;

rc = SQLDisconnect (hdbc); /* disconnect from database */if (rc != SQL_SUCCESS )

print_error (henv, hdbc, SQL_NULL_HSTMT);rc = SQLFreeConnect (hdbc); /* free connection handle */if (rc != SQL_SUCCESS )

print_error (henv, hdbc, SQL_NULL_HSTMT);rc = SQLFreeEnv (henv); /* free environment handle */if (rc != SQL_SUCCESS )

print_error (henv, SQL_NULL_HDBC, SQL_NULL_HSTMT);

}/* end terminate */

/********************************************************************* display_results - displays the selected character fields**** - for each column** - get column name** - bind column** - display column headings** - fetch each row** - if value truncated, build error message** - if column null, set value to "NULL"** - display row** - print truncation message** - free local storage*********************************************************************/void display_results(SQLHSTMT hstmt,

SQLSMALLINT nresultcols){SQLCHAR colname[32];SQLSMALLINT coltype[MAXCOLS];SQLSMALLINT colnamelen;

SQL CLI


SQLSMALLINT nullable;SQLINTEGER collen[MAXCOLS];SQLSMALLINT scale;SQLINTEGER outlen[MAXCOLS];SQLCHAR * data[MAXCOLS];SQLCHAR errmsg[256];SQLRETURN rc;SQLINTEGER i;SQLINTEGER displaysize;

for (i = 0; i < nresultcols; i++){

SQLDescribeCol (hstmt, i+1, colname, sizeof (colname),&colnamelen, &coltype[i], &collen[i], &scale, &nullable);

/* get display length for column */SQLColAttributes (hstmt, i+1, SQL_DESC_PRECISION, NULL, 0 ,

NULL, &displaysize);

/* set column length to max of display length, and column namelength. Plus one byte for null terminator */

collen[i] = max(displaysize, collen[i]);collen[i] = max(collen[i], strlen((char *) colname) ) + 1;

printf ("%-*.*s", collen[i], collen[i], colname);

/* allocate memory to bind column */data[i] = (SQLCHAR *) malloc (collen[i]);

/* bind columns to program vars, converting all types to CHAR */SQLBindCol (hstmt, i+1, SQL_C_CHAR, data[i], collen[i], &outlen[i]);

}printf("\n");

/* display result rows */while ((rc = SQLFetch (hstmt)) != SQL_NO_DATA_FOUND){

errmsg[0] = ’\0’;for (i = 0; i < nresultcols; i++){

/* Build a truncation message for any columns truncated */if (outlen[i] >= collen[i]){ sprintf ((char *) errmsg + strlen ((char *) errmsg),

"%d chars truncated, col %d\n",outlen[i]-collen[i]+1, i+1);

}if (outlen[i] == SQL_NULL_DATA)

printf ("%-*.*s", collen[i], collen[i], "NULL");else

printf ("%-*.*s", collen[i], collen[i], data[i]);} /* for all columns in this row */

printf ("\n%s", errmsg); /* print any truncation messages */} /* while rows to fetch */

/* free data buffers */for (i = 0; i < nresultcols; i++){

free (data[i]);}

}/* end display_results

/********************************************************************* SUPPORT FUNCTIONS** - print_error - call SQLError(), display SQLSTATE and message** - check_error - call print_error

SQL CLI


** - check severity of Return Code** - rollback & exit if error, continue if warning*******************************************************************/

/*******************************************************************/int print_error (SQLHENV henv,

SQLHDBC hdbc,SQLHSTMT hstmt)




};return;

}

/*******************************************************************/int check_error (SQLHENV henv,


{SQLRETURN rc;





printf("Rollback Successful, Exiting application\n");terminate(henv, hdbc);exit(frc);break;


case SQL_NO_DATA_FOUND :printf("\n ** No Data Found ** \n");break;

default :printf("\n ** Invalid Return Code ** \n");printf(" ** Attempting to rollback transaction **\n");SQLTransact(henv, hdbc, SQL_ROLLBACK);terminate(henv, hdbc);exit(frc);break;


}

SQL CLI


Code license and disclaimer informationIBM grants you a nonexclusive copyright license to use all programming code examples from which youcan generate similar function tailored to your own specific needs.

SUBJECT TO ANY STATUTORY WARRANTIES WHICH CANNOT BE EXCLUDED, IBM, ITSPROGRAM DEVELOPERS AND SUPPLIERS MAKE NO WARRANTIES OR CONDITIONS EITHEREXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES ORCONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, ANDNON-INFRINGEMENT, REGARDING THE PROGRAM OR TECHNICAL SUPPORT, IF ANY.

UNDER NO CIRCUMSTANCES IS IBM, ITS PROGRAM DEVELOPERS OR SUPPLIERS LIABLE FORANY OF THE FOLLOWING, EVEN IF INFORMED OF THEIR POSSIBILITY:1. LOSS OF, OR DAMAGE TO, DATA;2. DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES, OR FOR ANY ECONOMIC

CONSEQUENTIAL DAMAGES; OR3. LOST PROFITS, BUSINESS, REVENUE, GOODWILL, OR ANTICIPATED SAVINGS.

SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF DIRECT,INCIDENTAL, OR CONSEQUENTIAL DAMAGES, SO SOME OR ALL OF THE ABOVE LIMITATIONSOR EXCLUSIONS MAY NOT APPLY TO YOU.

SQL CLI


Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries.Consult your local IBM representative for information on the products and services currently available inyour area. Any reference to an IBM product, program, or service is not intended to state or imply thatonly that IBM product, program, or service may be used. Any functionally equivalent product, program,or service that does not infringe any IBM intellectual property right may be used instead. However, it isthe user's responsibility to evaluate and verify the operation of any non-IBM product, program, orservice.

IBM may have patents or pending patent applications covering subject matter described in thisdocument. The furnishing of this document does not grant you any license to these patents. You can sendlicense inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual PropertyDepartment in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.1623-14, Shimotsuruma, Yamato-shiKanagawa 242-8502 Japan

The following paragraph does not apply to the United Kingdom or any other country where suchprovisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATIONPROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Somestates do not allow disclaimer of express or implied warranties in certain transactions, therefore, thisstatement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodicallymade to the information herein; these changes will be incorporated in new editions of the publication.IBM may make improvements and/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not inany manner serve as an endorsement of those Web sites. The materials at those Web sites are not part ofthe materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate withoutincurring any obligation to you.


Licensees of this program who wish to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including thisone) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM CorporationSoftware Interoperability Coordinator, Department YBWA3605 Highway 52 NRochester, MN 55901U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases,payment of a fee.

The licensed program described in this document and all licensed material available for it are providedby IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement orany equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, theresults obtained in other operating environments may vary significantly. Some measurements may havebeen made on development-level systems and there is no guarantee that these measurements will be thesame on generally available systems. Furthermore, some measurements may have been estimated throughextrapolation. Actual results may vary. Users of this document should verify the applicable data for theirspecific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, theirpublished announcements or other publicly available sources. IBM has not tested those products andcannot confirm the accuracy of performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers ofthose products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal withoutnotice, and represent goals and objectives only.

This information is for planning purposes only. The information herein is subject to change before theproducts described become available.

This information contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands, andproducts. All of these names are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programsin any form without payment to IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughly tested under allconditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of theseprograms. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not beliable for any damages arising out of your use of the sample programs.

Each copy or any portion of these sample programs or any derivative work, must include a copyrightnotice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs.


© Copyright IBM Corp. _enter the year or years_.

Programming interface informationThis SQL call level interface publication documents intended Programming Interfaces that allow thecustomer to write programs to obtain the services of IBM i.

TrademarksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International BusinessMachines Corp., registered in many jurisdictions worldwide. Other product and service names might betrademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at“Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml.

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarksof Adobe Systems Incorporated in the United States, and/or other countries.

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in theUnited States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other product and service names might be trademarks of IBM or other companies.

Terms and conditionsPermissions for the use of these publications is granted subject to the following terms and conditions.

Personal Use: You may reproduce these publications for your personal, noncommercial use provided thatall proprietary notices are preserved. You may not distribute, display or make derivative works of thesepublications, or any portion thereof, without the express consent of IBM.

Commercial Use: You may reproduce, distribute and display these publications solely within yourenterprise provided that all proprietary notices are preserved. You may not make derivative works ofthese publications, or reproduce, distribute or display these publications or any portion thereof outsideyour enterprise, without the express consent of IBM.

Except as expressly granted in this permission, no other permissions, licenses or rights are granted, eitherexpress or implied, to the publications or any information, data, software or other intellectual propertycontained therein.

IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use ofthe publications is detrimental to its interest or, as determined by IBM, the above instructions are notbeing properly followed.

You may not download, export or re-export this information except in full compliance with all applicablelaws and regulations, including all United States export laws and regulations.

IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THEPUBLICATIONS ARE PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OFMERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.

Notices 325

http://www.ibm.com/legal/copytrade.shtml

Index

Aallocate

allocate handle, function 33allocated handle, function 33connection handle, function 27, 29environment handle, function 30, 32statement handle, function 34, 35

allocate handleallocate, function 33

applicationexample 308sample 308tasks 6

Assign File Reference, function 44

BBind A Buffer To A Parameter Marker,

function 51, 52, 60Bind Column, function 36, 40Bind File Reference, function 41BindFileToParam, function 46binding

columns 14parameter markers 13

Binds A Buffer To A Parameter Marker,function 47

CCancel statement, function 61case sensitivity 23character strings 22, 23CLI

writing a Db2 for i CLI application 6CLI function

SQLSetEnvAttr 305CLI XA transaction 311CloseCursor statement, function 62Column Attribute, function 63, 68Column Attributes, function 69, 265Column Information, function 73Column Privileges, function 51ColumnPrivileges, function 72commit 15Connect, function 77, 79, 96connection handle 3

allocate, function 27allocating 9freeing 9

Connection handleFree, function 121

CopyDesc statement, function 80cursor 3, 15

Ddata conversion

C data types 17

data conversion (continued)data types 17default data types 17description 19SQL data types 17

data typesC 17, 18generic 18ODBC 18SQL 17

deferred arguments 13definition

restricted handle 30Describe Column Attributes,

function 85, 88Diagnostic Field Information, return 147Diagnostic Information, return 145, 148Diagnostic Record Information,

return 150diagnostics 16Disconnect, function 91, 92DriverConnect, function 93dynamic SQL 6

Eembedded SQL 308End Transaction Management,

function 97environment handle 3

allocate, function 30allocating 8Free, function 122, 123, 217freeing 8

Error Information, retrieval 99, 101example application 308execute direct 12execute statement 12Execute statement Directly, function 102,

103Execute statement, function 104, 105Extended Fetch, function 106

FFetch, function 108, 113FetchScroll, function 114, 115Foreign key column names, function 120Foreign Keys Columns, function 116Free

Connection handle, function 121environment handle, function 122,

123, 217handle, function 123release environment, function 217statement handle, function 124, 125

GGet Col, function 131Get Column Names for a Table,

function 72, 76Get Connection Attribute, function 132Get Connection Option, function 133,

134Get cursor name, function 135, 138Get Data Sources, function 81, 84Get Data, function 139Get Description Field, function 140, 142Get descriptor record, function 143Get Descriptor Record, function 144Get Dialect or Conformance Information,

function 185Get Environment Attribute, function 151Get Functions, function 152, 154Get Index and Statistics Information for a

Table, function 259, 262Get Info, function 155, 166Get List of Procedure Names 212Get List of Procedure Names,

function 214Get Number of Result Columns 194Get Parameters for a Procedure,

function 211Get privileges associated with a

table 263Get privileges associated with the

columns of a table, function 70Get row count, function 219Get Row Count, function 218Get special (Row identifier) columns,

function 258Get Special Column Names,

function 255Get Statement Attribute, function 172,

173Get Statement Option, function 174, 175Get Table Information, function 266, 268Get Type Information, function 179GetCol, function 126

Hhandle

connection handle 3, 8environment handle 3, 8Free, function 123statement handle 3

header files 270

Iinclude files 270initialization 6, 7INVALID_HANDLE 16ISO standard 9075–3:1999 2


LLanguage Information, function 184

MMore Result Sets, function 186, 187

NNative SQL Text, function 188, 189Next Result Set, function 190Next Result Sets, function 191null-terminated strings 22Number of Parameters, function 192,

193Number of Result Columns,

function 194, 195

OODBC

cursor names 135precision 74SQLSTATES 17

PParameter Data, function 196, 197parameter markers 3parameter markers, binding 13Parameter Options, function 198portability 5prepare statement 12Prepare statement, function 200, 203Primary Key Columns, function 204, 206Procedure Parameter Information,

function 206Put Data for a Parameter, function 215,

216

Rrelease environment

ReleaseEnv, function 217restricted handle, definition 30Retrieve Length of String Value,

function 167Retrieve Portion of A String Value,

function 176return codes 16Return Starting Position of String,

function 169rollback 15

Ssample application 308SELECT 14server mode

restrictions 306starting 305

Set a connection attribute, function 232Set a Connection Attribute, function 220Set a Statement Attribute, function 247

Set connection option, function 234Set Connection Option, function 233Set cursor name, function 236Set Cursor Name, function 235Set Descriptor Field, function 237, 238Set Descriptor Record, function 239, 240Set Environment Attribute, function 241,

245Set Parameter, function 246Set Statement Option, function 253, 254SQL

dynamic 6dynamically prepared 3parameter markers 13preparing and executing

statements 12statements

DELETE 15SELECT 14UPDATE 15

static 6SQL_ERROR 16SQL_NO_DATA_FOUND 16SQL_NTS 22SQL_SUCCESS 16SQL_SUCCESS_WITH_INFO 16SQLAllocConnect, function

description 27, 29overview 7

SQLAllocEnv, functiondescription 30, 32, 33overview 7

SQLAllocHandle, functiondescription 33

SQLAllocStmt, functiondescription 34, 35overview 11

SQLBindCol, functiondescription 36, 40overview 11, 14

SQLBindFileToCol, functiondescription 41

SQLBindFileToParam, functiondescription 44, 46

SQLBindParam, functiondescription 47, 51

SQLBindParameter, functiondescription 52, 60overview 12

SQLCancel, functiondescription 61

SQLCloseCursor, functiondescription 62

SQLColAttribute, functiondescription 63, 68overview 14

SQLColAttributes, functiondescription 69, 265overview 11

SQLColumnPrivileges, functiondescription 51, 70, 72

SQLColumns, functiondescription 72, 73, 76

SQLConnect, functiondescription 77, 79, 96overview 7

SQLCopyDesc, functiondescription 80

SQLDataSources, functiondescription 81, 84overview 11, 14

SQLDescribeCol, functiondescription 85, 88overview 11, 14

SQLDescribeParam, functiondescription 89

SQLDisconnect, functiondescription 91, 92overview 7

SQLDriverConnect, functiondescription 93

SQLEndTran, functiondescription 97

SQLError, functiondescription 99, 101

SQLExecDirect, functiondescription 102, 103overview 11, 12

SQLExecute, functiondescription 104, 105overview 11, 12

SQLExtendedFetch, functiondescription 106

SQLFetch, functiondescription 108, 113overview 11, 14

SQLFetchScroll, functiondescription 114, 115

SQLForeignKeys, functiondescription 116, 120

SQLFreeConnect, functiondescription 121Description 121overview 7

SQLFreeEnv, functiondescription 122overview 7

SQLFreeHandle, functiondescription 123

SQLFreeStmt, functiondescription 124, 125overview 11

SQLGetCol, functiondescription 126, 131

SQLGetConnectAttr, functiondescription 132

SQLGetConnectOption, functiondescription 133, 134

SQLGetCursorName, functiondescription 135, 138

SQLGetData, functiondescription 139overview 11, 14

SQLGetDescField, functiondescription 140, 142

SQLGetDescRec, functiondescription 143, 144

SQLGetDiagField, functiondescription 145, 147

SQLGetDiagRec, functiondescription 148, 150

SQLGetEnvAttr, functiondescription 151


SQLGetFunctions, functiondescription 152, 154

SQLGetInfo, functiondescription 155, 166

SQLGetLength, functiondescription 167

SQLGetPosition, functiondescription 169

SQLGetStmtAttr, functiondescription 172, 173

SQLGetStmtOption, functiondescription 174, 175

SQLGetSubString, functiondescription 176

SQLGetTypeInfo, functiondescription 179, 183

SQLLanguages, functiondescription 184, 185

SQLMoreResults, functiondescription 186, 187

SQLNativeSql, functiondescription 188, 189

SQLNextResult, functiondescription 190, 191

SQLNumParams, functiondescription 192, 193

SQLNumResultCols, functiondescription 194, 195overview 11, 14

SQLParamData, functiondescription 196, 197

SQLParamOptions, functiondescription 198

SQLPrepare, functiondescription 200, 203overview 11, 12, 14

SQLPrimaryKeys, functiondescription 204, 206

SQLProcedureColumns, functiondescription 206, 211

SQLProcedures, functiondescription 212, 214

SQLPutData, functiondescription 215, 216

SQLReleaseEnv, functiondescription 217

SQLRowCount, functiondescription 218, 219overview 11

SQLSetConnectAttr, functiondescription 220, 232

SQLSetConnectOption, functiondescription 233, 234

SQLSetCursorName, functiondescription 235, 236

SQLSetDescField, functiondescription 237, 238

SQLSetDescRec, functiondescription 239, 240

SQLSetEnvAttr, functiondescription 241, 245

SQLSetParam, functiondescription 246overview 11, 14

SQLSetStmtAttr, functiondescription 247, 252Set Statement Attribute, function 252

SQLSetStmtOption, functiondescription 253, 254

SQLSpecialColumns, functiondescription 255, 258

SQLSTATE 3SQLSTATE, format of 17SQLSTATEs 17SQLStatistics, function

description 259, 262SQLTablePrivileges, function

description 263SQLTables, function

description 266, 268SQLTransact, function

description 269overview 11, 14, 15

statement handle 3allocate, function 34allocating 12Free, function 124, 125freeing 15maximum number of 12

static SQL 6string arguments 22, 23

Ttermination 6, 7transaction management 15Transaction Management, function 269transaction processing 6truncation 23

UUCS-2 307unicode 307UTF-16 307UTF-8 307

Wwriting 6

Index 329

IBM®

Product Number: 5770-SS1

Printed in USA

ibm i: sql call level interface

Documents