SQLDataSources - Get list of data sources

SQLDataSources() returns a list of target databases available, one at a time. A database must be cataloged to be available.

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

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

If you are running DB2® for i CLI in SQL server mode, some restrictions apply when you use SQLDataSources().

For more information about running in server mode refer to the Restrictions for running DB2 for i CLI in server mode.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. The corresponding Unicode function is SQLDataSourcesW(). Refer to Unicode in DB2 for iCLI for more information about Unicode support for DB2 CLI.

Syntax

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

Function arguments

Table 1. SQLDataSources arguments
Data type	Argument	Use	Description
SQLHENV	EnvironmentHandle	Input	Environment handle.
SQLSMALLINT	Direction	Input	This is 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 in characters 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 characters available to return in the ServerName is stored.
SQLCHAR *	Description	Output	Pointer to buffer where the description of the data source is returned. DB2 for i CLI returns the *Comment* field associated with the database catalogued to the Database Management System (DBMS).
SQLSMALLINT	BufferLength2	Input	Maximum length in characters of the Description buffer.
SQLSMALLINT *	NameLength2Ptr	Output	Pointer to location where the function returns the actual number of characters available to return for the description of the data source.

Usage

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

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

If SQL_FETCH_NEXT is specified:

Directly following the 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.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND

Error conditions

Table 2. SQLDataSources SQLSTATEs
SQLSTATE	Description	Explanation
01004	Data truncated	The data source name returned in the argument ServerName is 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 is 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 is no specific SQLSTATE and for which no specific SQLSTATE is defined. The error message returned by `SQLError()` in the argument ErrorMsg describes the error and its cause.
HY001	Memory allocation failure	DB2 for i CLI is unable to allocate memory required to support the processing or completion of the function.
HY009	Argument value that is not valid	The argument ServerName, NameLength1Ptr, Description, or NameLength2Ptr is a null pointer. Value for the direction that is not valid.
HY013	Unexpected memory handling error	DB2 for i CLI is unable to access memory required to support the processing or completion of the function.
HY103	Direction option out of range	The value specified for the argument Direction is not equal to SQL_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 disclaimer information.

/* 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
                                 )
            ) != 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 ) ;
 
 
}