1 Version 4.0 -- 5/1/89 dbopen_a (VMS only)
______________________________________________________________________
NAME: dbopen_a (VMS only)
FUNCTION:
Create and initialize a DBPROCESS structure.
SYNTAX:
RETCODE dbopen_a(login, server, dbproc, final_result,
ast_proc, ast_param)
LOGINREC *login;
char *server;
DBPROCESS *dbproc;
dbopen_a (VMS only) Version 4.0 -- 5/1/89 2
______________________________________________________________________
RETCODE *final_result;
void (*ast_proc)();
BYTE *ast_param;
COMMENTS:
o dbopen_a() is the asynchronous version of dbopen().
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 The following three events must occur before any other
DB-Library routines can be called:
o dbopen_a() must return SUCCEED.
3 Version 4.0 -- 5/1/89 dbopen_a (VMS only)
______________________________________________________________________
o *final_result must be set to SUCCEED by DB-Library.
o ast_proc() must be invoked by DB-Library.
If dbopen_a() returns FAIL, *final_result will not be set and
ast_proc() will not be invoked. If dbopen_a() returns SUCCEED,
*final_result will be set to SUCCEED or FAIL and ast_proc()
will be invoked by DB-Library.
o dbopen_a() is useful in VMS applications that use multi-tasking
or are otherwise trying to respond to multiple input and output
streams. dbopen() waits until a connection to the SQL Server
has been made or until all retries have been exhausted. By
substituting dbopen_a() for dbopen(), the time it takes to
obtain a SQL Server can be used to service other parts of the
application.
o Once the application has logged into a SQL Server, it can
change databases by calling the dbuse() routine.
dbopen_a (VMS only) Version 4.0 -- 5/1/89 4
______________________________________________________________________
o References in this manual to the dbopen() routine also pertain
to dbopen_a().
o For an example that illustrates the use of dbopen_a(), see the
DB-Library Reference Supplement.
PARAMETERS:
login - A pointer to a LOGINREC structure. This pointer will be
passed as an argument to dbopen_a(). You can get one by cal-
ling dblogin().
Once the application has made all its dbopen_a() 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.
dbopen_a() looks up server in the interfaces file to get
information for connecting to a SQL Server.
5 Version 4.0 -- 5/1/89 dbopen_a (VMS only)
______________________________________________________________________
If server is NULL (and you have not called dbsetconnect() as
described below), dbopen_a() 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 desig-
nating an interfaces file, see the manual page for dbseti-
file(). 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.
dbproc - A pointer which will point to a newly-allocated DBPRO-
CESS structure if dbopen_a() returns SUCCEED and
*final_result is set to SUCCEED. Otherwise, dbproc will be
invalid.
dbopen_a (VMS only) Version 4.0 -- 5/1/89 6
______________________________________________________________________
final_result - A pointer to a RETCODE which is set to SUCCEED or
FAIL if dbopen_a() returns SUCCEED. *final_result is set to
SUCCEED if a successful connection to a SQL Server has been
made. The most common reason that *final_result gets set to
FAIL is because the login to the SQL Server failed.
When *final_result is set to FAIL, a DB-Library error number
that indicates the error may be accessed through an error
handler. However, if there's an unexpected communications
failure during the SQL Server login process and an error
handler has not been installed, the program will be aborted.
ast_proc - A pointer to a user-supplied routine that will be
queued when the success of the current command is finally
determined by SQL Server. *final_result will always be set
before this procedure is invoked.
ast_param - A generic BYTE pointer that will be passed to the
user-supplied ast_proc(). ast_param allows the user to pass
any parameter or structure to the ast_proc routine.
7 Version 4.0 -- 5/1/89 dbopen_a (VMS only)
______________________________________________________________________
RETURNS:
SUCCEED or FAIL. dbopen_a() will return FAIL if either of the
following conditions are true:
o The maximum number of DBPROCESS structures has been exceeded.
This number can be set with the DB-Library routine dbsetmax-
procs().
o There's not enough memory to allocate another DBPROCESS
structure.
SEE ALSO:
dbclose, dbexit, dbinit, dblogin, dbloginfree, dbopen, dbsetcon-
nect, dbsetifile, dbuse