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 i CLI 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
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:
|
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.
- 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
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
/* 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 ) ;
}