home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 for Intel / NeXTSTEP 3.2 for Intel.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbopen.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  3.4 KB  |  117 lines
  1. .Na "dbopen" 
  2. .Aa
  3. .Fu
  4. Create and initialize a DBPROCESS structure.
  5. .Ih "DBPROCESS structure, allocating"
  6. .Ih "\*S connection, establishing"
  7. .Ih "\*S, logging into"
  8. .Ih "logging into \*S"
  9. .Sy
  10. .Sf "DBPROCESS *dbopen(login, server)"
  11. .Sp "LOGINREC" "*login"
  12. .Sp "char" "*server"
  13. .Co
  14. .Bl
  15. This routine allocates and initializes a DBPROCESS structure.
  16. This structure is the basic data structure that \*L
  17. uses to communicate with \*S.
  18. It is the first argument in almost every \*L call.
  19. Besides allocating
  20. the DBPROCESS structure, this routine sets up communication with
  21. the network, logs into \*S, and initializes any default options.
  22. .Bl
  23. Here's a program fragment that uses \f2dbopen()\fP:
  24. .ta +4n +4n +4n +4n +4n +4n
  25. .SD
  26. .ne 7
  27. .so dbopen.ex
  28. .ED
  29. .Bl
  30. Once the application has logged into a \*S, it can change databases
  31. by calling the \f2dbuse()\f1 routine.
  32. .Bl
  33. An asynchronous version of \f2dbopen()\f1, called \f2dbopen_a()\f1, is available for VMS.
  34. .Bz
  35. .Pa
  36. .Pi login
  37. A pointer to a LOGINREC structure.  This pointer will be passed as
  38. an argument to 
  39. .I "dbopen()."
  40. You can get one by calling
  41. .I "dblogin()."
  42. .sp 0.5v
  43. Once the application has made all its \f2dbopen()\f1 calls,
  44. the LOGINREC structure is no longer necessary.
  45. The program can then call \f2dbloginfree()\f1 to free 
  46. the LOGINREC structure.
  47. .Pi server
  48. The \*S that you want to connect to.
  49. \f2server\f1 is the alias given to the server in the \f2interfaces\f1 file.
  50. .Ih "interfaces file"
  51. \f2dbopen()\f1 looks up \f2server\f1 in the
  52. \f2interfaces\f1 file to get information for connecting to a \*S.
  53. .sp 0.5v
  54. If \f2server\f1 is NULL
  55. (and you have not called \f2dbsetconnect()\f1 as described below),
  56. \f2dbopen()\f1 looks up the \f2interfaces\f1 entry that corresponds to
  57. the value of the DSQUERY environment variable or logical name.
  58. .Ih "DSQUERY environment variable"
  59. .Ih "DSQUERY logical name"
  60. If DSQUERY has not been explicitly set, it has a value of ``SYBASE''.
  61. (For information on designating an \f2interfaces\f1 file, see the manual page
  62. for \f2dbsetifile()\f1.
  63. For more information on the \f2interfaces\f1 file itself, 
  64. see the \f2SYBASE Installation Guide\f1.)
  65. .sp 0.5v
  66. You specify a value for this parameter only if
  67. you want the \f2interfaces\f1 file to determine the \*S connection.
  68. If the \f2dbsetconnect()\f1 routine
  69. has previously been called to determine the \*S connection,
  70. this parameter is ignored and should be NULL.
  71. .in -.375i
  72. .Re
  73. .br
  74. A DBPROCESS pointer if everything went well.
  75. Ordinarily,
  76. \f2dbopen()\f1 returns NULL 
  77. if a DBPROCESS structure couldn't be created or initialized, or if your login
  78. to \*S failed.
  79. When \f2dbopen()\f1 returns NULL, 
  80. it generates a \*L error number that indicates the error.
  81. The application can access this error number through an error handler.
  82. However, if there's an unexpected communications failure during the \*S
  83. login process and an error
  84. handler has not been installed, the program will be aborted.
  85. .Er
  86. .in -.375i
  87. .I "dbopen()"
  88. will return NULL if any of the following are true:
  89. .nf
  90. .ta +18n
  91. .sp 0.5v
  92. SYBEMEM        Unable to allocate sufficient memory.
  93. .sp 0.25v
  94. SYBEDBPS    Maximum number of DBPROCESSes already allocated.
  95. .sp 0.25v
  96. SYBESOCK    Unable to open socket.
  97. .sp 0.25v
  98. SYBEINTF    Server name not found in interfaces file.
  99. .sp 0.25v
  100. SYBEUHST    Unknown host machine name.
  101. .sp 0.25v
  102. SYBECONN    Unable to connect: \*S is unavailable or does not exist.
  103. .sp 0.25v
  104. SYBEPWD        Login incorrect.
  105. .sp 0.25v
  106. SYBEOPIN    Could not open interfaces file.
  107. .Sa
  108. dbclose,
  109. dbexit,
  110. dbinit,
  111. dblogin,
  112. dbloginfree,
  113. dbopen_a,
  114. dbsetconnect,
  115. dbsetifile,
  116. dbuse
  117.