SQLDriverConnect (Extension Level 1)

[This is preliminary documentation and subject to change.]

This is the most common way for applications to connect to a data source.

In the connection string to SQLDriverConnect, the caller specifies either:

• "DSN=dataSourceName" (it can optionally include the correlation keywords as described below), or
• "DRIVER=driverName" (it can optionally include the correlation keywords as described below).

In addition to the standard data source name, user name, and password, the adapter understands the following attribute-keywords: namespaces, dbq, home, server, sysprops.

Namespaces is a comma-separated list of database/namespace names. These must be fully qualified namespaces (if home is not specified) that the adapter can use directly with the provider gateway API.

The namespace names can be specified in the following format:

Namespaces={namespace name, style}

Where style can be either:

shallow

include only the namespace specified

deep

include the namespace specified and all its children

For example:

Namespaces={Root\Default, shallow}

This specifies just the Root\Default namespace

Namespaces={Root\Default,deep}

This specifies the Root\Default namespace and all its children

Namespaces={Root\Wellfleet,shallow},{Root\Cisco,deep}

This specifies the Root\Wellfleet namespace plus the Root\Cisco namespace plus all the children of the Root\Cisco namespace

If you specify just Namespaces=Root\Default, this is equivalent to

Namespaces={Root\Default,shallow}

DBQ is the database qualifier. This is the fully qualified default working namespace.

Home is the common root path to all the namespaces specified in the namespaces list. If the home keyword is defined, all names in the namespaces list are assumed to be relative names to the Homenamespace. The fully qualified namespace path can be derived by adding as a prefix the Home namespace to each of the names in the namespace list. If the Home keyword is not defined, then all namespaces in the namespaces list are assumed to be fully qualified.

For example:

Home=Root\Redmond; Namespaces=Fred

The fully qualified namespace is Root\Redmond\Fred

Server is the name of the WBEM server. This attribute-keyword is used primarily to specify a remote WBEM server. If this attribute-keyword is omitted, the local WBEM server is used.

For example:

Server=\\Redmond

Sysprops indicates whether or not the adapter exposes WBEM system properties. Set this to TRUE to expose system properties; that is, in the connection string, include SYSPROPS=TRUE. You can also activate system properties using the checkbox control in the Connection dialog box.

If you specify the Driver keyword, the user is prompted to enter a database category (if SQLDriverConnect was called with an fCompletionFlag of SQL_NO_PROMPT, this function returns an error). The keyword value is a string used to filter down the total number of databases present in WBEM. This is based on a global environment variable of the ODBC Category in the database with a value equal to this string. An exception to this is if the category string is specified as ALL. In that case, all databases fall under this data source.

If sufficient information has not been specified in the connection string (and if the fCompletionFlag is not SQL_NO_PROMPT), then a dialog box is displayed that allows users to select namespaces. The dialog box contains a standard tree control to show the nesting of namespaces. Each namespace has an associated bitmap image to represent its state. The bitmap image looks like a checkbox with a folder.

Clicking within the area of the checkbox or folder selects or clears the selection of the namespace. If the namespace tree control item has not been expanded (a + button is seen on the left), then the selection or cancellation of the selection, depending on its current state, occurs recursively. If the item is already expanded (or has no child tree items), then only the tree control item is affected

The state of each tree control item is represented as follows:

• Clear Unchecked Checkbox. Item is not selected and no child items (if any) are selected.
• Gray Unchecked Checkbox. Item is not selected. However, at least one child item is selected.
• Clear Checked Checkbox. Item is selected but no child items (if any) are selected.
• Gray Checked Checkbox. Item is selected and at least one child item is selected.

The dialog box also allows you to select namespaces from a remote WBEM database. This functionality is available by means of the Browse button and edit box.

If you choose to enter manually a remote server name in the edit box (maximum length 128 characters), the update does not take place until you exit the edit control using the TAB key. The current tree control is cleared and replaced by the tree control for the new remote server. If the edit box does not contain any text, then the local server is used.

If you click the Browse button, a new Server Selection dialog box is displayed. This presents information similar to the Microsoft® Windows NT® Network Neighborhood. The dialog box initially displays the network resources on the LAN. There is also a link to view the entire network (represented by a globe). If you double-click on an image that does not represent a server, then the current display is cleared and the contents of the chosen network resource are displayed.

The dialog box also has three bitmap buttons:

• The Folder button allows you to go back to the previous network resource selection.
• The Link view button displays all the network resources as a list.
• The Report view button displays all the network resources as a report.