SQLDataSources function (CLI) - Get list of data sources

Returns a list of target data source names available, one at a time. The SQLDataSources() function returns data source names (DSN) from the db2dsdriver.cfg file and cataloged database directory. If same DSN name is present in both cataloged database directory and in the db2dsdriver.cfg file in an instance-based client such as IBM Data Server Client or IBM Data Server Runtime Client, only single merged DSN entry is returned.

Specification:

  • CLI 1.1
  • ODBC 1.0
  • ISO CLI

SQLDataSources() is called before a connection is made, to determine the databases that are available to connect to.

Unicode equivalent: This function can also be used with the Unicode character set. The corresponding Unicode function is SQLDataSourcesW(). See Unicode functions (CLI) for information about ANSI to Unicode function mappings.

Syntax

SQLRETURN   SQLDataSources (
               SQLHENV           EnvironmentHandle,  /* henv */
               SQLUSMALLINT      Direction,          /* fDirection */
               SQLCHAR           *ServerName,        /* *szDSN */
               SQLSMALLINT       BufferLength1,      /* cbDSNMax */
               SQLSMALLINT       *NameLength1Ptr,    /* *pcbDSN */
               SQLCHAR           *Description,       /* *szDescription */
               SQLSMALLINT       BufferLength2,      /* cbDescriptionMax */
               SQLSMALLINT       *NameLength2Ptr);   /* *pcbDescription */

Function arguments

Table 1. 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 in which to return the data source name.
SQLSMALLINT BufferLength1 input Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store the ServerName buffer. This number must be less than or equal to SQL_MAX_DSN_LENGTH + 1.
SQLSMALLINT * NameLength1Ptr output Pointer to a buffer in which to return the total number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function), excluding the null-termination character, available to return in *ServerName. If the number of SQLCHAR or SQLWCHAR elements available to return is greater than or equal to BufferLength1, the data source name in *ServerName is truncated to BufferLength1 minus the length of a null-termination character.
SQLCHAR * Description output Pointer to buffer where the description of the data source is returned. CLI returns the Comment field associated with the database cataloged to the DBMS.
SQLSMALLINT BufferLength2 input Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store the Description buffer.
SQLSMALLINT * NameLength2Ptr output Pointer to a buffer in which to return the total number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function), excluding the null-termination character, available to return in *Description. If the number of SQLCHAR or SQLWCHAR elements available to return is greater than or equal to BufferLength2, the driver description in *Description is truncated to BufferLength2 minus the length of a null-termination character.

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

In an ODBC environment, the ODBC Driver Manager will perform this function.

Since the IBM RDBMSs always returns the description of the data source blank padded to 30 bytes, CLI will do the same.

Return codes

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • SQL_NO_DATA_FOUND

Diagnostics

Table 2. 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 implementation-specific SQLSTATE was defined. The error message returned by SQLGetDiagRec() in the MessageText argument 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. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
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

  /* get list of data sources */
  cliRC = SQLDataSources(henv,
                         SQL_FETCH_FIRST,
                         dbAliasBuf,
                         SQL_MAX_DSN_LENGTH + 1,
                         &aliasLen,
                         dbCommentBuf,
                         255,
                         &commentLen);