SQLDataSources() returns a list of available
target databases, one at a time. Before you make a connection, you
can call SQLDataSources() to determine which databases
are available.
ODBC specifications for SQLDataSources()
Table 1. SQLDataSources() specifications
ODBC specification level
In X/Open CLI CAE specification?
In ISO CLI specification?
1.0
Yes
Yes
Syntax
SQLRETURN SQLDataSources (SQLHENV henv,
SQLUSMALLINT fDirection,
SQLCHAR FAR *szDSN,
SQLSMALLINT cbDSNMax,
SQLSMALLINT FAR *pcbDSN,
SQLCHAR FAR *szDescription,
SQLSMALLINT cbDescriptionMax,
SQLSMALLINT FAR *pcbDescription);
Function arguments
The following table
lists the data type, use, and description for each argument in this
function.
Table 2. SQLDataSources() arguments
Data type
Argument
Use
Description
SQLHENV
henv
input
Specifies the environment
handle.
SQLUSMALLINT
fDirection
input
Requests either the first
data source name in the list or the next data source name in the list. fDirection can
contain only the following values:
SQL_FETCH_FIRST
SQL_FETCH_NEXT
SQLCHAR *
szDSN
output
Specifies the pointer
to the buffer that holds the retrieved data source name.
SQLSMALLINT
cbDSNMax
input
Specifies the maximum
length, in bytes, of the buffer to which the szDSN argument
points. This should be less than or equal to SQL_MAX_DSN_LENGTH +
1.
SQLSMALLINT *
pcbDSN
output
Specifies the pointer
to the location where the value of the maximum number of bytes that
are available to return in the szDSN is
stored.
SQLCHAR *
szDescription
output
Specifies the pointer
to the buffer where the description of the data source is returned. Db2 ODBC returns the comment field
that is associated with the database cataloged to the database management
system.
IBM® specific: IBM relational database management
systems always return a blank description that is padded to 30 bytes.
SQLSMALLINT
cbDescriptionMax
input
Specifies the maximum
length, in bytes, of the szDescription buffer.
IBM specific:Db2 for z/OS® ODBC
always returns NULL.
SQLSMALLINT *
pcbDescription
output
Specifies the pointer
to the location where this function returns the actual number of bytes
that the full description of the data source requires.
IBM specific:Db2 for z/OS always
returns zero.
Usage
You can call this function any time
with the fDirection argument set to either
SQL_FETCH_FIRST or SQL_FETCH_NEXT.
If you specify SQL_FETCH_FIRST,
the first database in the list is always returned.
If you specify
SQL_FETCH_NEXT, the database that is returned depends on when you
call SQLDataSources(). At the following points in
your application, SQLDataSources() returns a different
database name:
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 no more databases are 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
After you call SQLDataSources(),
it returns one of the following values:
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND
Diagnostics
The following table lists each
SQLSTATE that this function generates, with a description and explanation
for each value.
Table 3. SQLDataSources() SQLSTATEs
SQLSTATE
Description
Explanation
01004
Data truncated.
This SQLSTATE is returned for one or more of the
following reasons:
The data source name that is returned in the argument szDSN is
longer than the specified value in the cbDSNMax argument.
The pcbDSN argument contains the length,
in bytes, of the full data source name.
The data source name that is returned in the argument szDescription is
longer than the value specified in the cbDescriptionMax argument.
The pcbDescription argument contains the
length, in bytes, of the full data source description.
(SQLDataSources() returns SQL_SUCCESS_WITH_INFO
for this SQLSTATE.)
58004
Unexpected system failure.
Unrecoverable system error.
HY000
General error.
An error occurred for which no specific SQLSTATE
is defined. The error message that is returned by SQLGetDiagRec() in
the MessageText argument describes the error
and its cause.
HY001
Memory allocation failure.
Db2 ODBC is not able to allocate the required memory to support the execution or the completion of the function.
HY013
Unexpected memory handling error.
Db2 ODBC is not able to access the memory that is required to support execution or completion of the function.
HY090
Invalid string or buffer length.
The specified value for either the cbDSNMaxargument
or the cbDescriptionMax argument is less
than 0.
HY103
Direction option out of range.
The fDirection argument
is not set to SQL_FETCH_FIRST or SQL_FETCH_NEXT.
Example
The following
example shows an application that prints a list of available data
sources with SQLDataSources(). Figure 1. An application that lists available data
sources
/* ... */
/*******************************************************
** - Demonstrate SQLDataSource function
** - List available servers
** (error checking has been ignored for simplicity)
**
** Functions used:
**
** SQLAllocHandle SQLFreeHandle
** SQLDataSources
********************************************************/
#include <stdio.h>
#include <stdlib.h>
#include "sqlcli1.h"
int
main()
{
SQLRETURN rc;
SQLHENV henv;
SQLCHAR source[SQL_MAX_DSN_LENGTH + 1], description[255];
SQLSMALLINT buffl, desl;
/* Allocate an environment handle */
SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
/* 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);
}
SQLFreeHandle(SQL_HANDLE_ENV, henv);
return (SQL_SUCCESS);
}
/* ... */