16.3.4 SQLBrowseConnect, SQLBrowseConnectW

Organization of this subsection

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

(1) Function

This ODBC function supports a method of referencing attributes and attribute values one at time that are required to establish a connection with the data source (HADB server). Each call to SQLBrowseConnect or SQLBrowseConnectW returns successive levels of attributes and attribute values. When all levels of attributes are specified, a connection to the data source is completed and a complete connection character string is returned by SQLBrowseConnect or SQLBrowseConnectW.

Note that you must have the CONNECT privilege to execute SQLBrowseConnect and SQLBrowseConnectW.

To Page Top

(2) Format

For SQLBrowseConnect

SQLRETURN SQLBrowseConnect
(
  SQLHDBC         ConnectionHandle,        /* In */
  SQLCHAR       * InConnectionString,      /* In */
  SQLSMALLINT     StringLength1,           /* In */
  SQLCHAR       * OutConnectionString,     /* Out */
  SQLSMALLINT     BufferLength,            /* In */
  SQLSMALLINT   * StringLength2Ptr         /* Out */
)

For SQLBrowseConnectW

SQLRETURN SQLBrowseConnectW
(
  SQLHDBC         ConnectionHandle,        /* In */
  SQLWCHAR      * InConnectionString,      /* In */
  SQLSMALLINT     StringLength1,           /* In */
  SQLWCHAR      * OutConnectionString,     /* Out */
  SQLSMALLINT     BufferLength,            /* In */
  SQLSMALLINT   * StringLength2Ptr         /* Out */
)

To Page Top

(3) Arguments

ConnectionHandle

Specifies a connection handle.

InConnectionString

Specifies a browse request connection character string.

The following table lists and describes the connection attributes that can be specified in the browse request connection character string.

Connection attribute	Description
`DSN`	Data source name
`DRIVER`	ODBC driver name: `Hitachi` `Advanced` `Data` `Binder` `ODBC` `Driver`
`UID`	Authorization identifier
`PWD`	Password
`CLTPATH`	Absolute path of a client definition file

StringLength1

Specifies the length^# of the browse request connection character string specified for InConnectionString.

If the browse request connection character string specified for InConnectionString ends with the null terminating character, specify SQL_NTS.

If zero or a negative value is specified, an error results.

OutConnectionString

Specifies a pointer to the buffer that stores the browse result connection character string.

If the connection to the HADB server is successful, the function returns the complete connection character string.

If the function returns SQL_NEED_DATA, it returns the connection attributes that were lacking when connection with the HADB server was attempted.

BufferLength

Specifies the length^# of the buffer that stores OutConnectionString.

This length includes the null terminating character. SQL_NTS cannot be specified.

StringLength2Ptr

Specifies a pointer to the buffer that stores the valid length^# of the browse result connection character string. This length does not include the null terminating character.

This is the valid length^# of the character string that is returned to OutConnectionString.

Important: If the length^# of the connection character string stored here is greater than the value of BufferLength without the length^# of the null terminating character, the character string stored in OutConnectionString is truncated to the length^# equivalent to BufferLength without the null terminating character, and then the null terminating character is added at the end.

#

The length must be in bytes for SQLBrowseConnect and in characters for SQLBrowseConnectW.

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.

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	The browse result connection character string could not be stored because the `OutConnectionString` buffer was too small (the information was truncated). The length of the untruncated browse result connection character string is stored in the `StringLength2Ptr` buffer. The function returns `SQL_NEED_DATA`.	Y
`01S00`	Invalid connection string attribute	The browse request connection character string (`InConnectionString`) contains an invalid attribute keyword. The function returns `SQL_NEED_DATA`. The attribute keyword specified in the browse request connection character string (`InConnectionString`) does not apply to the current connection level. The function returns `SQL_NEED_DATA`.	Y
`01S02`	Option value changed	The option value was replaced with a similar value because the HADB ODBC driver does not support the value specified for `ValuePtr` in `SQLSetConnectAttr` or `SQLSetConnectAttrW`. The function returns `SQL_SUCCESS_WITH_INFO`.	N
`01S51`	Code replacement occurred during conversion of character encoding	A character code that cannot be converted was detected and then replaced with the specified character. The function returns `SQL_SUCCESS_WITH_INFO`.	Y
`08001`	Client unable to establish a connection	The HADB ODBC driver cannot connect to the data source.	N
`08002`	Connection name in use	--	N
`08S01`	Communication link failure	--	N
`28000`	Invalid authorization specification	The authorization identifier or password specified in the browse request connection character string violates the data source limitations.	Y
`5C002`	Character encoding conversion error	A character code that cannot be converted was detected.	Y
`5C052`	Version mismatch error	The versions of the ODBC driver and HADB client are different.	Y
`5D001`	HADB-specific error	An error occurred on HADB, but a specific `SQLSTATE` or error message cannot be obtained.	Y
`HY000`	General error	--	N
`HY001`	Memory allocation error	--	N
`HY013`	Memory management error	The function call could not be processed because the memory object could not be accessed.	N
`HY090`	Invalid string or buffer length	The length of a connection attribute value specified in `InConnectionString` is invalid. An invalid value (`SQL_NTS`) was specified in `BufferLength`.	Y
`HYT00`	Timeout expired	A login timeout occurred before connection with the data source was completed. The login timeout value can be specified by using `SQL_ATTR_LOGIN_TIMEOUT` in `SQLSetConnectAttr` or `SQLSetConnectAttrW`.	N
`HYT01`	Connection timeout expired	A connection timeout occurred before the data source responded to the request. The connection timeout value can be specified by using `SQL_ATTR_CONNECTION_TIMEOUT` in `SQLSetConnectAttr` or `SQLSetConnectAttrW`.	N
`IM001`	Driver does not support this function	--	N
`IM002`	No data source is found and Default driver is not specified		N
`IM003`	Specified driver could not be loaded		N
`IM004`	Driver's `SQLAllocHandle` on `SQL_HANDLE_ENV` failed		N
`IM005`	Driver's `SQLAllocHandle` on `SQL_HANDLE_DBC` failed		N
`IM006`	Driver's `SQLSetConnectAttr` or `SQLSetConnectAttrW` failed		N
`IM009`	Unable to load translation DLL		N
`IM010`	Data source name too long		N
`IM011`	Driver name too long		N
`IM012`	`DRIVER` keyword syntax error		N

Legend:

Y: This SQLSTATE might be returned by the HADB ODBC driver.

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

--: None

To Page Top

(6) Notes

The following table lists and describes the connection attributes that are specified in the browse request connection character string.

Table 16‒3: Connection attributes that are specified in the browse request connection character string
No.	Connection attribute	Connection attribute value	Whether specification is required
No.	Connection attribute	Connection attribute value	DSN connection	DRIVER connection
1	`DSN`	Specify a data source name.	Y	--
2	`DRIVER`	Specify an ODBC driver name. The ODBC driver name is `Hitachi` `Advanced` `Data` `Binder` `ODBC` `Driver`.	--	Y
3	`UID`	Specify an authorization identifier.	Y	Y
4	`PWD`	Specify a password. Specify a character string consisting of 255 bytes or less.	Y	Y
5	`CLTPATH`	Specify the absolute path of the client definition file. Express the absolute path of the client property file as a maximum of 255 bytes of character string. If this attribute is omitted, the file under the folder specified in the `ADBCLTDIR` environment definition is used.	--	O

Legend:

Y: Mandatory connection attribute

O: Optional connection attribute

--: Connection attribute whose specification is not needed

The following shows an example specification of the browse request connection character string:
- "DSN=XXXXX;UID=YYYYY;PWD=ZZZZZ"
- "DRIVER=Hitachi Advanced Data Binder ODBC Driver;CLTPATH=XXXXX;UID=YYYYY;PWD=ZZZZZ"
If the DSN and DRIVER connection attributes are both specified in the browse request connection character string, the last connection attribute specified takes effect.
If the same connection attribute is specified more than once in the browse request connection character string, the value of the first connection attribute specified takes effect.
The connection attributes can be specified in any order in the browse request connection character string. However, if neither DSN=XXXXX nor DRIVER=Hitachi Advanced Data Binder ODBC Driver is specified in the first request, the ODBC driver manager detects an error.
The connection attributes are not case-sensitive.
The connection attribute values are case sensitive.
A semicolon (;) is treated as a delimiter. For this reason, the semicolon must not be used in a password character string in the connection attributes. Due to ODBC implementation conventions, we recommend that you do not use any of the following 12 characters in passwords: [, ], {, }, (, ), ,, ?, *, =, !, and @. For details about the passwords supported by HADB, see Password specification rules in the HADB Setup and Operation Guide.
If SQL_NEED_DATA is returned because an invalid parameter value was specified in this function's argument, then re-execution of the function results in SQL_ERROR due to an error such as an invalid password character string, and then SQLFreeHandle is executed as is, the ODBC driver manager might return SQL_ERROR (SQLSTATE: HY010) and the handle might not be freed. In such a case, re-execute the function with the correct parameter specified, and then execute SQLFreeHandle. Alternatively, terminate the application forcibly.

To Page Top