home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbopen.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  4.7 KB  |  133 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                   dbopen
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbopen
  6.  
  7.   FUNCTION:
  8.        Create and initialize a DBPROCESS structure.
  9.  
  10.   SYNTAX:
  11.        DBPROCESS *dbopen(login, server)
  12.  
  13.        LOGINREC  *login;
  14.        char      *server;
  15.  
  16.   COMMENTS:
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbopen                  Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.        o This routine allocates and initializes a  DBPROCESS  structure.
  28.          This structure is the basic data structure that DB-Library uses
  29.          to communicate with SQL Server.  It is the  first  argument  in
  30.          almost every DB-Library call.  Besides allocating the DBPROCESS
  31.          structure, this routine sets up communication with the network,
  32.          logs into SQL Server, and initializes any default options.
  33.        o Here's a program fragment that uses dbopen():
  34.  
  35.          DBPROCESS       *dbproc;
  36.          LOGINREC        *loginrec;
  37.  
  38.          loginrec = dblogin();
  39.          DBSETLPWD(loginrec, "server_password");
  40.          DBSETLAPP(loginrec, "my_program");
  41.          dbproc = dbopen(loginrec, "my_server");
  42.  
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                   dbopen
  47.   ______________________________________________________________________
  48.  
  49.        o Once the application has  logged  into  a  SQL Server,  it  can
  50.          change databases by calling the dbuse() routine.
  51.  
  52.   PARAMETERS:
  53.        login -  A pointer to a LOGINREC structure.  This pointer will be
  54.            passed  as  an argument to dbopen().  You can get one by cal-
  55.            ling dblogin().
  56.            Once the application has made all  its  dbopen()  calls,  the
  57.            LOGINREC  structure  is no longer necessary.  The program can
  58.            then call dbloginfree() to free the LOGINREC structure.
  59.        server -  The SQL Server that you want to connect to.  server  is
  60.            the  alias  given to the server in the interfaces file.  dbo-
  61.            pen() looks up server in the interfaces file to get  informa-
  62.            tion for connecting to a SQL Server.
  63.  
  64.            If server is NULL (and you have not called dbsetconnect()  as
  65.            described below), dbopen() looks up the interfaces entry that
  66.  
  67.  
  68.   dbopen                  Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.            corresponds to the value of the DSQUERY environment  variable
  71.            or  logical name.  If DSQUERY has not been explicitly set, it
  72.            has a value of "SYBASE".  (For information on designating  an
  73.            interfaces  file,  see the manual page for dbsetifile().  For
  74.            more information on  the  interfaces  file  itself,  see  the
  75.            SYBASE Installation Guide.)
  76.  
  77.            You specify a value for this parameter only if you  want  the
  78.            interfaces  file  to determine the SQL Server connection.  If
  79.            the dbsetconnect() routine  has  previously  been  called  to
  80.            determine   the  SQL Server  connection,  this  parameter  is
  81.            ignored and should be NULL.
  82.  
  83.   RETURNS:
  84.        A DBPROCESS pointer if everything went  well.   Ordinarily,  dbo-
  85.        pen()  returns  NULL if a DBPROCESS structure couldn't be created
  86.        or initialized, or if your login to SQL Server failed.  When dbo-
  87.        pen()  returns  NULL, it generates a DB-Library error number that
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                   dbopen
  91.   ______________________________________________________________________
  92.        indicates the error.   The  application  can  access  this  error
  93.        number  through  an  error handler.  However, if there's an unex-
  94.        pected communications failure during the SQL Server login process
  95.        and  an error handler has not been installed, the program will be
  96.        aborted.
  97.  
  98.   ERRORS:
  99.        dbopen() will return NULL if any of the following are true:
  100.  
  101.        SYBEMEM           Unable to allocate sufficient memory.
  102.        SYBEDBPS          Maximum number of DBPROCESSes already allocated.
  103.        SYBESOCK          Unable to open socket.
  104.        SYBEINTF          Server name not found in interfaces file.
  105.        SYBEUHST          Unknown host machine name.
  106.        SYBECONN          Unable to connect: SQL Server is unavailable or does not exist.
  107.        SYBEPWD           Login incorrect.
  108.        SYBEOPIN          Could not open interfaces file.
  109.  
  110.  
  111.  
  112.   dbopen                  Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.  
  115.   SEE ALSO:
  116.        dbclose,  dbexit,  dbinit,  dblogin,  dbloginfree,  dbsetconnect,
  117.        dbsetifile, dbuse
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.