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:
|
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:
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
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. |
Authorization
None.
See the CLI sample datasour.c
References