dbopen

Allocates and initializes a DBPROCESS connection structure.

Syntax

PDBPROCESS dbopen (
PLOGINREC login,
LPCSTR servername );

where

login
Is a pointer to a LOGINREC structure. You can get one by calling dblogin.
servername
Is the name of the SQL Server that you want 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 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:

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 timeout expires. For more information on setting the login timeout, 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 Client Configuration 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 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.

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

dbclose, dbexit, dblogin, dbsetlogintime