Export (0) Print
Expand All

dbopen

SQL Server 2000

  New Information - SQL Server 2000 SP3.

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.

Security Note  Authorization information, including user name and password, is stored in memory in the LOGINREC structure. It is possible that someone accessing a memory dump of the machine running the application could access this information. Please take precautions to prevent access to memory output by unauthorized individuals.

servername

Is the name of the server running Microsoft® SQL Server™ 2000 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® 4.0 Registry.

Returns

A DBPROCESS pointer if everything is correct. Ordinarily, NULL is returned if a DBPROCESS structure could not 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.

Security Note  Connection information, including user name and password, is stored in memory in the DBPROCESS structure. It is possible that someone accessing a memory dump of the machine running the application could access this information. Take precautions to prevent access to memory output by unauthorized individuals.

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.

Error code Description
SQLEMEM Unable to allocate sufficient memory.
SQLEDBPS Maximum number of DBPROCESS structures already allocated.
SQLECONN Unable to connect: SQL Server is unavailable or does not exist.
SQLEPWD Login incorrect.

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 4.0 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 4.0, Microsoft Windows® 95 or Windows 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();
DBSETLSECURE(loginrec);
DBSETLAPP(loginrec, "my_program");
dbproc = dbopen(loginrec, "my_server");

See Also

dbclose

dbsetlfallback

dbexit

dbsetlogintime

dblogin

Show:
© 2015 Microsoft