16.4.1 SQLDataSources, SQLDataSourcesW

Organization of this subsection

(1) Function
(2) Format
(3) Arguments
(4) Return value
(5) SQLSTATE

(1) Function

This ODBC function returns the following information:

Data source name
Description of the driver associated with the data source

This function is implemented by the driver manager. The HADB ODBC driver provides SQLDataSources or SQLDataSourcesW as a function that always returns SQL_SUCCESS.

To Page Top

(2) Format

For SQLDataSources

SQLRETURN SQLDataSources
(
  SQLHENV           EnvironmentHandle,  /* In */
  SQLUSMALLINT      Direction,          /* In */
  SQLCHAR         * ServerName,         /* Out */
  SQLSMALLINT       BufferLength1,      /* In */
  SQLSMALLINT     * NameLength1Ptr,     /* Out */
  SQLCHAR         * Description,        /* Out */
  SQLSMALLINT       BufferLength2,      /* In */
  SQLSMALLINT     * NameLength2Ptr      /* Out */
)

For SQLDataSourcesW

SQLRETURN SQLDataSourcesW
(
  SQLHENV           EnvironmentHandle,  /* In */
  SQLUSMALLINT      Direction,          /* In */
  SQLWCHAR        * ServerName,         /* Out */
  SQLSMALLINT       BufferLength1,      /* In */
  SQLSMALLINT     * NameLength1Ptr,     /* Out */
  SQLWCHAR        * Description,        /* Out */
  SQLSMALLINT       BufferLength2,      /* In */
  SQLSMALLINT     * NameLength2Ptr      /* Out */
)

To Page Top

(3) Arguments

EnvironmentHandle

Specifies an environment handle.

Direction

Specifies how the driver manager is to read the data source information. The permitted values are as follows:

SQL_FETCH_FIRST: Fetch the data source name (hereafter called DSN) at the top of the list (both user and system DSNs).
SQL_FETCH_FIRST_USER: Fetch the first user DSN.
SQL_FETCH_FIRST_SYSTEM: Fetch the first system DSN.
SQL_FETCH_NEXT: Fetch the next DSN in the list. The target is the same type as the DSN that was fetched by FIRST (both user and system DSN, or only user DSN, or only system DSN).

ServerName

Specifies a pointer to the buffer in which the data source name is to be returned.

BufferLength1

Specifies the length^# of the *ServerName buffer. The maximum value is SQL_MAX_DSN_LENGTH plus the null terminating character. If a larger value is specified, this maximum value is assumed. This length includes the null terminating character.

NameLength1Ptr

Specifies a pointer to the buffer that stores the total valid length^# of *ServerName. This length does not include the null terminating character.

Important: If the length^# of the data source name stored here is greater than the value of BufferLength1 without the length^# of the null terminating character, the character string stored in *ServerName is truncated to the length^# equivalent to BufferLength1 without the null terminating character, and then the null terminating character is added at the end.

Description

Specifies a pointer to the buffer in which the description of the driver associated with the data source (such as an HADB server) is to be returned.

BufferLength2

Specifies the length^# of the *Description buffer.

This length includes the null terminating character.

NameLength2Ptr

Specifies a pointer to the buffer that stores the total valid length^# to be returned to *Description. This length does not include the null terminating character.

Important: If the length^# of the driver description stored here is greater than the value of BufferLength2 without the length^# of the null terminating character, the character string stored in *Description is truncated to the length^# equivalent to BufferLength2 without the null terminating character, and then the null terminating character is added at the end.

#

The length must be in bytes for SQLDataSources and in characters for SQLDataSourcesW.

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS.

To Page Top

(5) SQLSTATE

This ODBC function returns one of the following SQLSTATE values:

SQLSTATE	Description	Remarks	Returned
`01000`	General warning	--	N
`01004`	Character string data was right-truncated		N
`HY000`	General error		N
`HY001`	Memory allocation error		N
`HY013`	Memory management error		N
`HY090`	Invalid string or buffer length		N
`HY103`	Invalid retrieval code		N

Legend:

N: This SQLSTATE is not returned by the HADB ODBC driver.

--: None

To Page Top