Call Level Interface Guide and Reference

SQLDataSources - Get List of Data Sources

Purpose

Specification: DB2 CLI 1.1 ODBC 1.0 ISO CLI

SQLDataSources() returns a list of target databases available, one at a time. A database must be cataloged to be available. For more information on cataloging, refer to Chapter 4, Configuring CLI/ODBC and Running Sample Applications.

SQLDataSources() is usually called before a connection is made, to determine the databases that are available to connect to.

Syntax

SQLRETURN   SQLDataSources   (SQLHENV           EnvironmentHandle,
                              SQLUSMALLINT      Direction,
                              SQLCHAR      FAR  *ServerName,
                              SQLSMALLINT       BufferLength1,
                              SQLSMALLINT  FAR  *NameLength1Ptr,
                              SQLCHAR      FAR  *Description,
                              SQLSMALLINT       BufferLength2,
                              SQLSMALLINT  FAR  *NameLength2Ptr);

Function Arguments

Table 44. SQLDataSources Arguments

Data Type Argument Use Description
SQLHENV EnvironmentHandle input Environment handle.
SQLUSMALLINT Direction input Used by application to request the first data source name in the list or the next one in the list. Direction can take on only the following values:

SQL_FETCH_FIRST
SQL_FETCH_NEXT

SQLCHAR * ServerName output Pointer to buffer to hold the data source name retrieved.
SQLSMALLINT BufferLength1 input Maximum length of the buffer pointed to by ServerName. This should be less than or equal to SQL_MAX_DSN_LENGTH + 1.
SQLSMALLINT * NameLength1Ptr output Pointer to location where the maximum number of bytes available to return in the ServerName will be stored.
SQLCHAR * Description output Pointer to buffer where the description of the data source is returned. DB2 CLI will return the Comment field associated with the database catalogued to the DBMS.
SQLSMALLINT BufferLength2 input Maximum length of the Description buffer.
SQLSMALLINT * NameLength2Ptr output Pointer to location where this function will return the actual number of bytes available to return for the description of the data source.

Data Type	Argument	Use	Description
SQLHENV	`EnvironmentHandle`	input	Environment handle.
SQLUSMALLINT	`Direction`	input	Used by application to request the first data source name in the list or the next one in the list. `Direction` can take on only the following values: SQL_FETCH_FIRST SQL_FETCH_NEXT
SQLCHAR *	`ServerName`	output	Pointer to buffer to hold the data source name retrieved.
SQLSMALLINT	`BufferLength1`	input	Maximum length of the buffer pointed to by `ServerName`. This should be less than or equal to SQL_MAX_DSN_LENGTH + 1.
SQLSMALLINT *	`NameLength1Ptr`	output	Pointer to location where the maximum number of bytes available to return in the `ServerName` will be stored.
SQLCHAR *	`Description`	output	Pointer to buffer where the description of the data source is returned. DB2 CLI will return the *Comment* field associated with the database catalogued to the DBMS.
SQLSMALLINT	`BufferLength2`	input	Maximum length of the `Description` buffer.
SQLSMALLINT *	`NameLength2Ptr`	output	Pointer to location where this function will return the actual number of bytes available to return for the description of the data source.

Usage

The application can call this function any time with Direction set to either SQL_FETCH_FIRST or SQL_FETCH_NEXT.

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

If SQL_FETCH_NEXT is specified:

Directly following a SQL_FETCH_FIRST call, the second database in the list is returned
Before any other SQLDataSources() call, the first database in the list is returned
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.
Any other time, the next database in the list is returned.

In an ODBC environment, the ODBC Driver Manager will perform this function. For more information refer to Appendix C, DB2 CLI and ODBC.

Since the IBM RDBMSs always returns the description of the data source blank padded to 30 bytes, DB2 CLI will do the same.

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND

Diagnostics

Table 45. SQLDataSources SQLSTATEs

SQLSTATE Description Explanation
01004 Data truncated. The data source name returned in the argument ServerName was longer than the value specified in the argument BufferLength1. The argument NameLength1Ptr contains the length of the full data source name. (Function returns SQL_SUCCESS_WITH_INFO.)
The data source name returned in the argument Description was longer than the value specified in the argument BufferLength2. The argument NameLength2Ptr contains the length of the full data source description. (Function returns SQL_SUCCESS_WITH_INFO.)
58004 Unexpected system failure. Unrecoverable system error.
HY000 General error. An error occurred for which there was no specific SQLSTATE and for which no specific SQLSTATE was defined. The error message returned by SQLError() in the argument ErrorMsg describes the error and its cause.
HY001 Memory allocation failure. DB2 CLI is unable to allocate memory required to support execution or completion of the function.
HY013 Unexpected memory handling error. DB2 CLI was unable to access memory required to support execution or completion of the function.
HY090 Invalid string or buffer length. The value specified for argument BufferLength1 was less than 0.
The value specified for argument BufferLength2 was less than 0.
HY103 Direction option out of range. The value specified for the argument Direction was not equal to SQL_FETCH_FIRST or SQL_FETCH_NEXT.

SQLSTATE	Description	Explanation
01004	Data truncated.	The data source name returned in the argument `ServerName` was longer than the value specified in the argument `BufferLength1`. The argument `NameLength1Ptr` contains the length of the full data source name. (Function returns SQL_SUCCESS_WITH_INFO.) The data source name returned in the argument `Description` was longer than the value specified in the argument `BufferLength2`. The argument `NameLength2Ptr` contains the length of the full data source description. (Function returns SQL_SUCCESS_WITH_INFO.)
58004	Unexpected system failure.	Unrecoverable system error.
HY000	General error.	An error occurred for which there was no specific SQLSTATE and for which no specific SQLSTATE was defined. The error message returned by `SQLError()` in the argument `ErrorMsg` describes the error and its cause.
HY001	Memory allocation failure.	DB2 CLI is unable to allocate memory required to support execution or completion of the function.
HY013	Unexpected memory handling error.	DB2 CLI was unable to access memory required to support execution or completion of the function.
HY090	Invalid string or buffer length.	The value specified for argument `BufferLength1` was less than 0. The value specified for argument `BufferLength2` was less than 0.
HY103	Direction option out of range.	The value specified for the argument `Direction` was not equal to SQL_FETCH_FIRST or SQL_FETCH_NEXT.

Authorization

None.

CLI Sample ininfo.c

(The complete sample ininfo.c is also available here .)

 
/* From the CLI sample ININFO.C */
/* ... */
 
    sqlrc = SQLDataSources( henv,
                            SQL_FETCH_NEXT,
                            dbAliasBuf,
                            SQL_MAX_DSN_LENGTH + 1,
                            &aliasLen,
                            dbCommentBuf,
                            255,
                            &commentLen );

References

None.

[ Top of Page | Previous Page | Next Page ]