1 Version 4.0 -- 5/1/89 dbopen
______________________________________________________________________
NAME: dbopen
FUNCTION:
Create and initialize a DBPROCESS structure.
SYNTAX:
DBPROCESS *dbopen(login, server)
LOGINREC *login;
char *server;
COMMENTS:
dbopen Version 4.0 -- 5/1/89 2
______________________________________________________________________
o This routine allocates and initializes a DBPROCESS structure.
This structure is the basic data structure that DB-Library uses
to communicate with SQL 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 SQL Server, and initializes any default options.
o Here's 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");
3 Version 4.0 -- 5/1/89 dbopen
______________________________________________________________________
o Once the application has logged into a SQL Server, it can
change databases by calling the dbuse() routine.
PARAMETERS:
login - A pointer to a LOGINREC structure. This pointer will be
passed as an argument to dbopen(). You can get one by cal-
ling 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 SQL Server that you want to connect to. server is
the alias given to the server in the interfaces file. dbo-
pen() looks up server in the interfaces file to get informa-
tion for connecting to a SQL Server.
If server is NULL (and you have not called dbsetconnect() as
described below), dbopen() looks up the interfaces entry that
dbopen Version 4.0 -- 5/1/89 4
______________________________________________________________________
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 manual page for dbsetifile(). For
more information on the interfaces file itself, see the
SYBASE Installation Guide.)
You specify a value for this parameter only if you want the
interfaces file to determine the SQL Server connection. If
the dbsetconnect() routine has previously been called to
determine the SQL Server connection, this parameter is
ignored and should be NULL.
RETURNS:
A DBPROCESS pointer if everything went well. Ordinarily, dbo-
pen() returns NULL if a DBPROCESS structure couldn't be created
or initialized, or if your login to SQL Server failed. When dbo-
pen() returns NULL, it generates a DB-Library error number that
5 Version 4.0 -- 5/1/89 dbopen
______________________________________________________________________
indicates the error. The application can access this error
number through an error handler. However, if there's an unex-
pected communications failure during the SQL Server login process
and an error handler has not been installed, the program will be
aborted.
ERRORS:
dbopen() will return NULL if any of the following are true:
SYBEMEM Unable to allocate sufficient memory.
SYBEDBPS Maximum number of DBPROCESSes already allocated.
SYBESOCK Unable to open socket.
SYBEINTF Server name not found in interfaces file.
SYBEUHST Unknown host machine name.
SYBECONN Unable to connect: SQL Server is unavailable or does not exist.
SYBEPWD Login incorrect.
SYBEOPIN Could not open interfaces file.
dbopen Version 4.0 -- 5/1/89 6
______________________________________________________________________
SEE ALSO:
dbclose, dbexit, dbinit, dblogin, dbloginfree, dbsetconnect,
dbsetifile, dbuse