dbopen

Allocates and initializes a DBPROCESS connection structure.

Syntax

PDBPROCESS dbopen (
PLOGINREC login,
LPCSTR servername );

Arguments

login

Is a pointer to a LOGINREC structure. You can get one by calling dblogin.

servername

Is the name of the server running Microsoft® SQL Server™ to connect to. This parameter can be the name of an actual SQL Server, NULL or a null string to connect to a local SQL Server, or the logical name matching an entry in the Win.ini file or the Microsoft Windows NT® Registry.

Returns

A DBPROCESS pointer if everything is correct. Ordinarily, NULL is returned if a DBPROCESS structure couldn’t be created or initialized, or if your login to SQL Server failed. When NULL is returned, the user-supplied error handler is called to indicate the error.

Note If there is an unexpected communications failure during the SQL Server login process and an error handler has not been installed, the function returns NULL.

Errors

The dbopen function returns NULL if any of the following are true.

If the specified server cannot be found, a SQLECONN error is returned to your error handler (if one was registered) after the login time-out expires. For more information about setting the login time-out, see dbsetlogintime.

Remarks

The DBPROCESS structure is the basic data structure that DB-Library uses to communicate with SQL Server. The application needs a DBPROCESS structure to communicate with SQL Server. It is the first parameter in almost every DB-Library call. Besides allocating the DBPROCESS structure, this function sets up communication with the network, logs in to SQL Server, and initializes any default options.

In the call to dbopen, DB-Library uses the server name and connection information in the [SQLSERVER] section of Win.ini, or the following subtree of the Windows NT Registry:

HKEY_LOCAL_MACHINE\
    SOFTWARE\
        Microsoft\
            MSSQLServer\
                Client\
                    ConnectTo

Use the SQL Server Client Network Utility to configure server name and connection information.

Note also that the SQL Server ODBC driver uses the same Net-Library mechanism as DB-Library.

There can be only one Net-Library TSR loaded for Microsoft MS-DOS®, so there is no .ini file configuration. Environment variables for the name of the server are used to specify any network-specific connection information.

You can use dbopen to connect to a failover server. When used to connect to a failover server, this function only works with a standby server configuration; it does not apply to a virtual server cluster/failover configration. If an attempt to connect to a primary server fails, dbopen can attempt to connect to a failover server. You must call the DBSETLFALLBACK function to indicate that a failover server can be used. The call to DBSETLFALLBACK must occur before the call to dbopen.

Each call to DBSETLFALLBACK from a computer running Windows NT or Microsoft Windows® 95/98 updates the failover information in the local registry from the SQL Server registry. Failover information is stored in the Win.ini file on computers running 16-bit Windows. The dbopen function retrieves the failover information from the local registry or from the Win.ini file.

When dbopen attempts to connect to a failover server, DB-Library generates warning message 10110 (SQLECONNFB):

Unable to connect: DB Server is unavailable or
does not exist - will attempt a fallback connection.

Example

The following example shows how to use dbopen:

DBPROCESS    *dbproc;
LOGINREC    *loginrec;

loginrec = dblogin();
DBSETLUSER(loginrec, "user");
DBSETLPWD(loginrec, "my_password");
DBSETLAPP(loginrec, "my_program");
dbproc = dbopen(loginrec, "my_server");

See Also