Call Level Interface Guide and Reference

SQLBrowseConnect - Get Required Attributes to Connect to Data source

Purpose

Specification: DB2 CLI 5.0 ODBC 1

SQLBrowseConnect() supports an iterative method of discovering and enumerating the attributes and attribute values required to connect to a data source. Each call to SQLBrowseConnect() returns successive levels of attributes and attribute values. When all levels have been enumerated, a connection to the data source is completed and a complete connection string is returned by SQLBrowseConnect(). A return code of SQL_SUCCESS or SQL_SUCCESS_WITH_INFO indicates that all connection information has been specified and the application is now connected to the data source.

Syntax

SQLRETURN   SQLBrowseConnect (SQLHDBC           ConnectionHandle,           
                              SQLCHAR           *InConnectionString,
                              SQLSMALLINT       StringLength1,
                              SQLCHAR           *OutConnectionString,
                              SQLSMALLINT       BufferLength,
                              SQLSMALLINT       *StringLength2Ptr);

Function Arguments

Table 23. SQLBrowseConnect Arguments

Data Type Argument Use Description
SQLHDBC ConnectionHandle input Connection handle.
SQLCHAR *szConnStrIn input Browse request connection string (see InConnectionString Argument).
SQLSMALLINT cbConnStrIn input Length of *InConnectionString.
SQLCHAR *OutConnectionString output Pointer to a buffer in which to return the browse result connection string (see OutConnectionString Argument).
SQLINTEGER BufferLength input Length of the *OutConnectionString buffer.
SQLSMALLINT *StringLength2Ptr output The total number of bytes (excluding the null termination byte) available to return in *OutConnectionString. If the number of bytes available to return is greater than or equal to BufferLength, the connection string in *OutConnectionString is truncated to BufferLength minus the length of a null termination character.

Data Type	Argument	Use	Description
SQLHDBC	ConnectionHandle	input	Connection handle.
SQLCHAR	*szConnStrIn	input	Browse request connection string (see InConnectionString Argument).
SQLSMALLINT	cbConnStrIn	input	Length of *InConnectionString.
SQLCHAR	*OutConnectionString	output	Pointer to a buffer in which to return the browse result connection string (see OutConnectionString Argument).
SQLINTEGER	BufferLength	input	Length of the *OutConnectionString buffer.
SQLSMALLINT	*StringLength2Ptr	output	The total number of bytes (excluding the null termination byte) available to return in OutConnectionString. If the number of bytes available to return is greater than or equal to BufferLength, the connection string in OutConnectionString is truncated to BufferLength minus the length of a null termination character.

Usage

InConnectionString Argument

A browse request connection string has the following syntax:
connection-string ::= attribute[;] | attribute; connection-string

attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]

attribute-keyword ::= DSN | UID | PWD | NEWPWD
| driver-defined-attribute-keyword

attribute-value ::= character-string
driver-defined-attribute-keyword ::= identifier

where

character-string has zero or more characters
identifier has one or more characters
attribute-keyword is case insensitive
attribute-value may be case sensitive
the value of the DSN keyword does not consist solely of blanks
NEWPWD is used as part of a change password request. The application can either specify the new string to use, for example, NEWPWD=anewpass; or specify NEWPWD=; and rely on a dialog box generated by the DB2 CLI driver to prompt for the new password

Because of connection string and initialization file grammar, keywords and attribute values that contain the characters []{}(),;?*=!@ should be avoided. Because of the grammar in the system information, keywords and data source names cannot contain the backslash (\) character. For DB2 CLI Version 2, braces are required around the DRIVER keyword.

If any keywords are repeated in the browse request connection string, DB2 CLI uses the value associated with the first occurrence of the keyword. If the DSN and DRIVER keywords are included in the same browse request connection string, DB2 CLI uses which ever keyword appears first.

OutConnectionString Argument

The browse result connection string is a list of connection attributes. A connection attribute consists of an attribute keyword and a corresponding attribute value. The browse result connection string has the following syntax:
connection-string ::= attribute[;] | attribute; connection-string

attribute ::= [*]attribute-keyword=attribute-value
attribute-keyword ::= ODBC-attribute-keyword
| driver-defined-attribute-keyword

ODBC-attribute-keyword = {UID | PWD}[:localized-identifier]
driver-defined-attribute-keyword ::= identifer[:localized-identifier]

attribute-value ::= {attribute-value-list} | ?
(The braces are literal; they are returned by DB2 CLI.)
attribute-value-list ::= character-string [:localized-character
string] | character-string [:localized-character string], attribute-value-list

where

character-string and localized-character string have zero or more characters
identifier and localized-identifier have one or more characters; attribute-keyword is case insensitive
attribute-value may be case sensitive

Because of connection string and initialization file grammar, keywords, localized identifiers, and attribute values that contain the characters []{}(),;?*=!@ should be avoided. Because of the grammar in the system information, keywords and data source names cannot contain the backslash (\) character.

The browse result connection string syntax is used according to the following semantic rules:

If an asterisk (*) precedes an attribute-keyword, the attribute is optional, and may be omitted in the next call to SQLBrowseConnect().
The attribute keywords UID and PWD have the same meaning as defined in SQLDriverConnect().
When connecting to a DB2 Universal Database, only DSN, UID and PWD are required. Other keywords can be specified but do not affect the connection.
ODBC-attribute-keywords and driver-defined-attribute-keywords include a localized or user-friendly version of the keyword. This might be used by applications as a label in a dialog box. However, UID, PWD, or the identifier alone must be used when passing a browse request string to DB2 CLI.
The {attribute-value-list} is an enumeration of actual values valid for the corresponding attribute-keyword. Note that the braces ({}) do not indicate a list of choices; they are returned by DB2 CLI. For example, it might be a list of server names or a list of database names.
If the attribute-value is a single question mark (?), a single value corresponds to the attribute-keyword. For example, UID=JohnS; PWD=Sesame.
Each call to SQLBrowseConnect() returns only the information required to satisfy the next level of the connection process. DB2 CLI associates state information with the connection handle so that the context can always be determined on each call.

Using SQLBrowseConnect

SQLBrowseConnect() requires an allocated connection. If SQLBrowseConnect() returns SQL_ERROR, outstanding connections are terminated and the connection is returned to an unconnected state.

When SQLBrowseConnect() is called for the first time on a connection, the browse request connection string must contain the DSN keyword.

On each call to SQLBrowseConnect(), the application specifies the connection attribute values in the browse request connection string. DB2 CLI returns successive levels of attributes and attribute values in the browse result connection string; it returns SQL_NEED_DATA as long as there are connection attributes that have not yet been enumerated in the browse request connection string. The application uses the contents of the browse result connection string to build the browse request connection string for the next call to SQLBrowseConnect(). All mandatory attributes (those not preceded by an asterisk in the OutConnectionString argument) must be included in the next call to SQLBrowseConnect(). Note that the application cannot use the contents of previous browse result connection strings when building the current browse request connection string; that is, it cannot specify different values for attributes set in previous levels.

When all levels of connection and their associated attributes have been enumerated, DB2 CLI returns SQL_SUCCESS, the connection to the data source is complete, and a complete connection string is returned to the application. The connection string is suitable to use in conjunction with SQLDriverConnect() with the SQL_DRIVER_NOPROMPT option to establish another connection. The complete connection string cannot be used in another call to SQLBrowseConnect(), however; if SQLBrowseConnect() were called again, the entire sequence of calls would have to be repeated.

SQLBrowseConnect() also returns SQL_NEED_DATA if there are recoverable, nonfatal errors during the browse process, for example, an invalid password supplied by the application or an invalid attribute keyword supplied by the application. When SQL_NEED_DATA is returned and the browse result connection string is unchanged, an error has occurred and the application can call SQLGetDiagRec() to return the SQLSTATE for browse-time errors. This permits the application to correct the attribute and continue the browse.

An application may terminate the browse process at any time by calling SQLDisconnect(). DB2 CLI will terminate any outstanding connections and return the connection to an unconnected state.

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NEED_DATA
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 24. SQLBrowseConnect SQLSTATEs

SQLSTATE Description Explanation
01000 Warning. Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
01004 Data truncated. The buffer *OutConnectionString was not large enough to return entire browse result connection string, so the string was truncated. The buffer *StringLength2Ptr contains the length of the untruncated browse result connection string. (Function returns SQL_SUCCESS_WITH_INFO.)
01S00 Invalid connection string attribute. An invalid attribute keyword was specified in the browse request connection string (InConnectionString). (Function returns SQL_NEED_DATA.)
An attribute keyword was specified in the browse request connection string (InConnectionString) that does not apply to the current connection level. (Function returns SQL_NEED_DATA.)
01S02 Option value changed. DB2 CLI did not support the specified value of the ValuePtr argument in SQLSetConnectAttr() and substituted a similar value. (Function returns SQL_SUCCESS_WITH_INFO.)
08001 Unable to connect to data source. DB2 CLI was unable to establish a connection with the data source.
08002 Connection in use. The specified connection had already been used to establish a connection with a data source and the connection was open.
08004 The application server rejected establishment of the connection. The data source rejected the establishment of the connection for implementation defined reasons.
08S01 Communication link failure. The communication link between DB2 CLI and the data source to which it was trying trying to connect failed before the function completed processing.
28000 Invalid authorization specification. Either the user identifier or the authorization string or both as specified in the browse request connection string (InConnectionString) violated restrictions defined by the data source.
HY000 General error. An error occurred for which there was no specific SQLSTATE. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause.
HY001 Memory allocation failure. DB2 CLI was 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 StringLength1 was less than 0 and was not equal to SQL_NTS.
The value specified for argument BufferLength was less than 0.

SQLSTATE	Description	Explanation
01000	Warning.	Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
01004	Data truncated.	The buffer `OutConnectionString` was not large enough to return entire browse result connection string, so the string was truncated. The buffer `StringLength2Ptr` contains the length of the untruncated browse result connection string. (Function returns SQL_SUCCESS_WITH_INFO.)
01S00	Invalid connection string attribute.	An invalid attribute keyword was specified in the browse request connection string (`InConnectionString`). (Function returns SQL_NEED_DATA.) An attribute keyword was specified in the browse request connection string (`InConnectionString`) that does not apply to the current connection level. (Function returns SQL_NEED_DATA.)
01S02	Option value changed.	DB2 CLI did not support the specified value of the `ValuePtr` argument in `SQLSetConnectAttr()` and substituted a similar value. (Function returns SQL_SUCCESS_WITH_INFO.)
08001	Unable to connect to data source.	DB2 CLI was unable to establish a connection with the data source.
08002	Connection in use.	The specified connection had already been used to establish a connection with a data source and the connection was open.
08004	The application server rejected establishment of the connection.	The data source rejected the establishment of the connection for implementation defined reasons.
08S01	Communication link failure.	The communication link between DB2 CLI and the data source to which it was trying trying to connect failed before the function completed processing.
28000	Invalid authorization specification.	Either the user identifier or the authorization string or both as specified in the browse request connection string (`InConnectionString`) violated restrictions defined by the data source.
HY000	General error.	An error occurred for which there was no specific SQLSTATE. The error message returned by `SQLGetDiagRec()` in the `*MessageText` buffer describes the error and its cause.
HY001	Memory allocation failure.	DB2 CLI was 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 `StringLength1` was less than 0 and was not equal to SQL_NTS. The value specified for argument `BufferLength` was less than 0.

Restrictions

None.

Example

See the README file in the sqllib\samples\cli (or sqllib/samples/cli) subdirectory for a list of appropriate samples.

References

[ Top of Page | Previous Page | Next Page ]