16.3.3 SQLDriverConnect, SQLDriverConnectW

Organization of this subsection

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

(1) Function

This ODBC function establishes a connection with the data source (HADB server) by using one of the following connection attributes:

The ODBC function establishes a connection by using a connection character string containing the data source name, at least one authorization identifier, at least one password, and other information required for establishing a connection with the data source.
The ODBC function establishes a connection without using a partial connection character string or additional information. In this case, the driver manager and the HADB ODBC driver will request connection information from the application program.
The ODBC function establishes a connection with a data source that is not defined in the system definition. If an application provides a partial connection character string, the HADB ODBC driver will request connection information from the user.
The ODBC function establishes a connection with the data source by using the connection character string created from the information in a .dsn file.

When a connection is established, SQLDriverConnect or SQLDriverConnectW returns a complete connection character string.

Note that you must have the CONNECT privilege to execute SQLDriverConnect and SQLDriverConnectW.

To Page Top

(2) Format

For SQLDriverConnect

SQLRETURN SQLDriverConnect
(
  SQLHDBC         ConnectionHandle,        /* In */
  SQLHWND         WindowHandle,            /* In */
  SQLCHAR       * InConnectionString,      /* In */
  SQLSMALLINT     StringLength1,           /* In */
  SQLCHAR       * OutConnectionString,     /* Out */
  SQLSMALLINT     BufferLength,            /* In */
  SQLSMALLINT   * StringLength2Ptr,        /* Out */
  SQLUSMALLINT    DriverCompletion         /* In */
)

For SQLDriverConnectW

SQLRETURN SQLDriverConnectW
(
  SQLHDBC         ConnectionHandle,        /* In */
  SQLHWND         WindowHandle,            /* In */
  SQLWCHAR      * InConnectionString,      /* In */
  SQLSMALLINT     StringLength1,           /* In */
  SQLWCHAR      * OutConnectionString,     /* Out */
  SQLSMALLINT     BufferLength,            /* In */
  SQLSMALLINT   * StringLength2Ptr,        /* Out */
  SQLUSMALLINT    DriverCompletion         /* In */
)

To Page Top

(3) Arguments

ConnectionHandle

Specifies a connection handle.

WindowHandle

Specifies the handle of the parent window.

If windows cannot be applied or dialog boxes will not be displayed, specify a null pointer.

InConnectionString

Specifies a connection character string.

The connection attributes permitted in the connection character string are as follows:

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 connection character string specified for InConnectionString.

If the 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 complete connection character string.

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

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 complete connection character string. This length does not include the null terminating character.

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.

DriverCompletion

Specifies a flag indicating whether the driver manager or the HADB ODBC driver requires more connection information. You can specify the following flags:

SQL_DRIVER_PROMPT
SQL_DRIVER_COMPLETE
SQL_DRIVER_COMPLETE_REQUIRED
SQL_DRIVER_NOPROMPT

#

The length must be in bytes for SQLDriverConnect and in characters for SQLDriverConnectW.

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_NO_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 complete connection character string could not be stored because the `OutConnectionString` buffer was too small (the information was truncated). The length of the untruncated complete connection character string is stored in the `StringLength2Ptr` buffer. The function returns `SQL_SUCCESS_WITH_INFO`.	Y
`01S00`	Invalid connection string attribute	The connection character string (`InConnectionString`) contains an invalid attribute keyword. The function returns `SQL_SUCCESS_WITH_INFO`.	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
`01S08`	Error saving file DSN	The connection character string for `*InConnectionString` contains the `FILEDSN` keyword, but the `.dsn` file was not saved. The function returns `SQL_SUCCESS_WITH_INFO`.	N
`01S09`	Invalid keyword	--	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. `SQL_DRIVER_NOPROMPT` is specified in `DriverCompletion`, but the attribute character string required for the connection was not specified in `InConnectionString`.	Y
`08002`	Connection name in use	--	N
`08004`	Server rejected the connection	The data source rejected the connection for the reason defined during implementation.	N
`08S01`	Communication link failure	--	N
`28000`	Invalid authorization specification	The authorization identifier or password specified in the connection character string violates the limitations on data source definitions.	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
`HY092`	Invalid attribute or option identifier	--	N
`HY110`	Option identifier whose `DriverCompletion` is invalid	--	N
`HYC00`	Optional feature not implemented	The HADB ODBC driver does not support the ODBC processing requested by the application.	N
`HYT00`	Timeout expired	A login timeout occurred before a 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 Driver's `SQLSetConnectAttrW` failed		N
`IM007`	Data source or driver is not specified and Dialog prohibited	Neither a data source name nor a driver name is specified in the connection character string, but `SQL_DRIVER_NOPROMPT` is specified in `DriverCompletion`.	N
`IM008`	Dialog failed	The driver's attempt to display the login dialog box failed. A null pointer is specified in `WindowHandle`, but `SQL_DRIVER_NOPROMPT` is not specified in `DriverCompletion`.	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
`IM014`	Invalid name of file DSN		N
`IM015`	Corrupt file data source		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 connection character string.

Table 16‒2: Connection attributes that are specified in the 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 definition 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 examples of connection character string specifications:
- "DSN=XXXXX;UID=YYYYY;PWD=ZZZZZ"
- "DRIVER=Hitachi Advanced Data BinderODBC Driver;CLTPATH=XXXXX;UID=YYYYY;PWD=ZZZZZ"
If the DSN and DRIVER connection attributes are both specified in the connection character string, the first connection attribute specified takes effect.
If the same connection attribute is specified more than once in the connection character string, the value of the last connection attribute specified takes effect.
The connection attributes can be specified in any order in the 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. This does not apply to the FILEDSN specification.
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 included in a password character string in the connection attributes. Because of 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.

To Page Top