dbopen

Description

Create and initialize a DBPROCESS structure.

Syntax

DBPROCESS *dbopen(login, server)
 
LOGINREC      *login;
char                *server;

Parameters

login: A pointer to a LOGINREC structure. This pointer will be passed as an argument to dbopen. You can get one by calling dblogin.

Once the application has made all its dbopen calls, the LOGINREC structure is no longer necessary. The program can then call dbloginfree to free the LOGINREC structure.

server: The server that you want to connect to. server is the alias given to the server in the interfaces file. dbopen looks up server in the interfaces file to get information for connecting to a server.

If server is NULL dbopen looks up the interfaces entry that corresponds to the value of the DSQUERY environment variable or logical name. If DSQUERY has not been explicitly set, it has a value of “SYBASE”. (For information on designating an interfaces file, see the reference page for dbsetifile. See the Open Client and Open Server Configuration Guide.

On non-UNIX platforms, client applications may use a method to find server address information that is different than the UNIX interfaces file. Consult your Open Client and Open Server Configuration Guide for detailed information on how clients connect to servers.

Returns

A DBPROCESS pointer if everything went well. Ordinarily, dbopen returns NULL if a DBPROCESS structure could not be created or initialized, or if your login to the server failed. When dbopen returns NULL, it generates a DB-Library error number that indicates the error. The application can access this error number through an error handler. However, if there is an unexpected communications failure during the server login process and an error handler has not been installed, the program will be aborted.

Usage

This routine allocates and initializes a DBPROCESS structure. This structure is the basic data structure that DB-Library uses to communicate with a server. It is the first argument in almost every DB-Library call. Besides allocating the DBPROCESS structure, this routine sets up communication with the network, logs into the server, and initializes any default options.

Here is a program fragment that uses dbopen:

 DBPROCESS       *dbproc;

 LOGINREC        *loginrec;

 loginrec = dblogin();

 DBSETLPWD(loginrec, "server_password");

 DBSETLAPP(loginrec, "my_program");

 dbproc = dbopen(loginrec, "my_server");

Once the application has logged into a server, it can change databases by calling the dbuse routine.

Multiple query entries in an interfaces file

It is possible to set up an interfaces file so that if dbopen fails to establish a connection with a server, it attempts to establish a connection with an alternate server.

An application can use the dbopen call to connect to the server MARS:

dbopen(loginrec, MARS);

An interfaces file containing an entry for MARS might look like this:

 MARS

     query tcp hp-ether violet 1025

     master tcp hp-ether violet 1025

     console tcp hp-ether violet 1026

 VENUS

     query tcp hp-ether plum 1050

     master tcp hp-ether plum 1050

     console tcp hp-ether plum 1051

 NEPTUNE

     query tcp hp-ether mauve 1060

     master tcp hp-ether mauve 1060

     console tcp hp-ether mauve 1061

The application is directed to port number 1025 on the machine “violet”. If MARS is not available, the dbopen call fails. If the interfaces file has multiple query entries in it for MARS, however, and the first connection attempt fails, dbopen will automatically attempt to connect to the next server listed. Such an interfaces file might look like this:

 MARS

     query tcp hp-ether violet 1025

     query tcp hp-ether plum 1050

     query tcp hp-ether mauve 1060

     master tcp hp-ether violet 1025

     console tcp hp-ether violet 1026

 VENUS

     query tcp hp-ether plum 1050

     master tcp hp-ether plum 1050

     console tcp hp-ether plum 1051

 NEPTUNE

     query tcp hp-ether mauve 1060

     master tcp hp-ether mauve 1060

     console tcp hp-ether mauve 1061

Note that the second query entry under MARS is identical to the query entry under VENUS, and that the third query entry is identical to the query entry under NEPTUNE. If this interfaces file is used and the application fails to connect with MARS, it will automatically attempt to connect with VENUS. If it fails to connect with VENUS, it will automatically attempt to connect with NEPTUNE. There is no limit on the number of alternate servers that may be listed under a server’s interfaces file entry, but each alternate server must be listed in the same interfaces file. You can add two numbers after the server’s name in the interfaces file:
```
# 
```
```
 MARS retries seconds 
```
```
     query tcp hp-ether violet 1025 
```
```
     query tcp hp-ether plum 1050 
```
```
     query tcp hp-ether mauve 1060 
```
```
     master tcp hp-ether violet 1025 
```
```
     console tcp hp-ether violet 1026 
```
retries represents the number of additional times to loop through the list of query entries if no connection is achieved during the first pass. seconds represents the amount of time, in seconds, that dbopen will wait at the top of the loop before going through the list again. These numbers are optional. If they are not included, dbopen will try to connect to each query entry only once. Looping through the list and pausing between loops is useful in case any of the candidate servers is in the process of booting. Multiple query lines can be particularly useful when alternate servers contain mirrored copies of the primary server’s databases.

Errors

The dbopen call will return NULL if any of the following errors occur. These errors can be trapped in the application’s error handler (installed with dberrhandle.)

If dbopen is called in the entry functions of a DLL, a deadlock can arise. dbopen creates operating system threads and tries to synchronize them using system utilities. This synchronization conflicts with the operating system’s serialization process.

The use of SIGALARM in a DB-Library application can cause dbopen to fail.

SYBEMEM	Unable to allocate sufficient memory.
SYBEDBPS	Maximum number of DBPROCESSes already allocated. Note that an application can set or retrieve the maximum number of DBPROCESS structures with dbsetmaxprocs and dbgetmaxprocs.
SYBESOCK	Unable to open socket.
SYBEINTF	Server name not found in interfaces file.
SYBEUHST	Unknown host machine name.
SYBECONN	Unable to connect: Adaptive Server Enterprise is unavailable or does not exist.
SYBEPWD	Login incorrect.
SYBEOPIN	Could not open interfaces file.