DB2 Version 10.1 for Linux, UNIX, and Windows

SQLDataSources function (CLI) - Get list of data sources

Returns a list of target data source names available, one at a time. The SQLDataSources() function returns data source names (DSN) from the db2dsdriver.cfg file and cataloged database directory. If same DSN name is present in both cataloged database directory and in the db2dsdriver.cfg file in an instance-based client such as IBM® Data Server Client or IBM Data Server Runtime Client, only single merged DSN entry is returned.

Specification:

CLI 1.1
ODBC 1.0
ISO CLI

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

Unicode equivalent: This function can also be used with the Unicode character set. The corresponding Unicode function is SQLDataSourcesW(). See Unicode functions (CLI) for information about ANSI to Unicode function mappings.

Syntax

SQLRETURN   SQLDataSources (
               SQLHENV           EnvironmentHandle,  /* henv */
               SQLUSMALLINT      Direction,          /* fDirection */
               SQLCHAR           *ServerName,        /* *szDSN */
               SQLSMALLINT       BufferLength1,      /* cbDSNMax */
               SQLSMALLINT       *NameLength1Ptr,    /* *pcbDSN */
               SQLCHAR           *Description,       /* *szDescription */
               SQLSMALLINT       BufferLength2,      /* cbDescriptionMax */
               SQLSMALLINT       *NameLength2Ptr);   /* *pcbDescription */

Function arguments

Table 1. 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 in which to return the data source name.
SQLSMALLINT	BufferLength1	input	Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store the ServerName buffer. This number must be less than or equal to SQL_MAX_DSN_LENGTH + 1.
SQLSMALLINT *	NameLength1Ptr	output	Pointer to a buffer in which to return the total number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function), excluding the null-termination character, available to return in ServerName. If the number of SQLCHAR or SQLWCHAR elements available to return is greater than or equal to BufferLength1, the data source name in ServerName is truncated to BufferLength1 minus the length of a null-termination character.
SQLCHAR *	Description	output	Pointer to buffer where the description of the data source is returned. CLI returns the *Comment* field associated with the database cataloged to the DBMS.
SQLSMALLINT	BufferLength2	input	Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store the Description buffer.
SQLSMALLINT *	NameLength2Ptr	output	Pointer to a buffer in which to return the total number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function), excluding the null-termination character, available to return in Description. If the number of SQLCHAR or SQLWCHAR elements available to return is greater than or equal to BufferLength2, the driver description in Description is truncated to BufferLength2 minus the length of a null-termination character.

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.

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

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND

Diagnostics

Table 2. 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 implementation-specific SQLSTATE was defined. The error message returned by `SQLGetDiagRec()` in the MessageText argument 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. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
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.

Example

  /* get list of data sources */
  cliRC = SQLDataSources(henv,
                         SQL_FETCH_FIRST,
                         dbAliasBuf,
                         SQL_MAX_DSN_LENGTH + 1,
                         &aliasLen,
                         dbCommentBuf,
                         255,
                         &commentLen);