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® UDB CLI in SQL server mode, some restrictions apply when you use SQLDataSources().
SQLRETURN SQLDataSources (SQLHENV EnvironmentHandle,
SQLSMALLINT Direction,
SQLCHAR *ServerName,
SQLSMALLINT BufferLength1,
SQLSMALLINT *NameLength1Ptr,
SQLCHAR *Description,
SQLSMALLINT BufferLength2,
SQLSMALLINT *NameLength2Ptr);
| Data type | Argument | Use | Description |
|---|---|---|---|
| SQLCHAR * | Description | Output | Pointer to buffer where the description of the data source is returned. DB2 UDB CLI returns the Comment field associated with the database catalogued to the Database Management System (DBMS). |
| SQLCHAR * | ServerName | Output | Pointer to buffer to hold the data source name retrieved. |
| SQLHENV | EnvironmentHandle | Input | Environment handle. |
| SQLSMALLINT | 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:
|
| SQLSMALLINT * | NameLength1Ptr | Output | Pointer to location where the maximum number of bytes available to return in the ServerName is stored. |
| SQLSMALLINT * | NameLength2Ptr | Output | Pointer to location where this function returns the actual number of bytes available to return for the description of the data source. |
| 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 | BufferLength2 | Input | Maximum length of the Description buffer. |
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.
| 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 UDB 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 UDB 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. |
None.
/* 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 ) ;
}
None.