IBM Books

Call Level Interface Guide and Reference

SQLDataSources - Get List of Data Sources

Purpose


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:
  • SQL_FETCH_FIRST
  • SQL_FETCH_NEXT
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.

Example

See the CLI sample datasour.c

References

None.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]