home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 for Intel / NeXTSTEP 3.2 for Intel.iso / NextLibrary / Documentation / Sybase / DBLIB / Coversheet.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  12.8 KB  |  411 lines
  1. .Ds U
  2. .Pt ""
  3. .Ff "" "4.0 DB-Library Changes" "4.0 DB-Library Changes"
  4. Release 4.0 of DB-Library contains a wealth of new features.
  5. There are over 50 new routines, as well as a number of minor changes
  6. to existing routines.
  7. In addition, Release 4.0 comes with a thoroughly revised and greatly
  8. improved \f2\*L Reference Manual\f1.
  9. As part of this revision, the system-specific material formerly
  10. contained in Section 3 of the \f2\*L Reference Manual\f1 now resides in
  11. a separate companion document, the \f2\*L Reference Supplement\f1.
  12. .LP
  13. Change bars along the right margin are used to indicate new and changed
  14. technical features in this release of \*L.
  15. The change bars do not, however, indicate all the changes made to the 
  16. documentation, which was in large part rewritten for this release.
  17. .H1 "New DB-Library Routines"
  18. The new routines cover a number of different categories, as described below.
  19. .H2 "Browse Mode"
  20. Browse mode provides a means for browsing through database rows and updating
  21. their values a row at a time.
  22. Since a row being browsed is not the actual row residing in the database,
  23. but is instead a copy residing in program variables, the program
  24. must be able to ensure that changes to the variables' values can be reliably
  25. used to update the original database row.
  26. In particular, in multi-user situations, the program needs to ensure that
  27. updates made to the database by one user do not unwittingly overwrite
  28. updates recently made by another user.
  29. Browse mode regulates this type of multi-user updating with a timestamp column
  30. in browsable tables.
  31. .LP
  32. A number of routines support this capability:
  33. .sp
  34. .na
  35. .ps -2
  36. .vs -2
  37. .in +16n
  38. .ta +16n
  39. .ti -16n
  40. \f2dbqual()\f1    Return a pointer to a WHERE clause, for use in updating a table.
  41. .ti -16n
  42. \f2dbfreequal()\f1    Free the memory allocated by \f2dbqual()\f1.
  43. .ti -16n
  44. \f2dbtsnewval()\f1    Return the timestamp value.
  45. .ti -16n
  46. \f2dbtsnewlen()\f1    Return the length of the timestamp value.
  47. .ti -16n
  48. \f2dbtsput()\f1        Put the timestamp value into the current row in the DBPROCESS.
  49. .ti -16n
  50. \f2dbcolbrowse()\f1    Determine whether a column can be updated via browse mode.
  51. .ti -16n
  52. \f2dbcolsource()\f1    Return the name of the database column from which
  53. the specified result column was derived.
  54. .ti -16n
  55. \f2dbtabbrowse()\f1    Determine whether a table can be updated via browse mode.
  56. .ti -16n
  57. \f2dbtabcount()\f1    Return the number of tables involved in the current query.
  58. .ti -16n
  59. \f2dbtabname()\f1    Return the name of a table based upon its column.
  60. .ti -16n
  61. \f2dbtabsource()\f1    Return the name of the table from which a particular result column was derived.
  62. .ps +2
  63. .vs +2
  64. .ad
  65. .H2 "Text and Image Handling"
  66. .sp 0.5v
  67. \*S supports two new datatypes: text and image.
  68. Since text and image values can be quite large, several routines are available to facilitate
  69. the process of updating text and image columns in database tables:
  70. .sp
  71. .na
  72. .ps -2
  73. .vs -2
  74. .in +16n
  75. .ta +16n
  76. .ti -16n
  77. \f2dbwritetext()\f1    Send a text or image value to the \*S.
  78. .ti -16n
  79. \f2dbmoretext()\f1    Send part of a text or image value to the \*S.
  80. .ti -16n
  81. \f2dbtxptr()\f1    Return the value of the text pointer for a particular column.
  82. .ti -16n
  83. \f2dbtxtimestamp()\f1    Return the value of the text timestamp for a particular column.
  84. .ti -16n
  85. \f2dbtxtsnewval()\f1    Return the new value of a text timestamp after a call to \f2dbwritetext()\f1.
  86. .ti -16n
  87. \f2dbtxtsput()\f1    Put the new value of a text timestamp into the specified column.
  88. .ps +2
  89. .vs +2
  90. .ad
  91. .H2 "Associating User Data with a DBPROCESS"
  92. It is now possible to associate some arbitrary user-allocated data
  93. with a particular DBPROCESS structure.
  94. One use for this capability is to transfer information from a \*S message
  95. handler to the program code that triggered it.
  96. The following routines support this capability:
  97. .sp
  98. .na
  99. .ps -2
  100. .vs -2
  101. .in +16n
  102. .ta +16n
  103. .ti -16n
  104. \f2dbsetuserdata()\f1    Use a DBPROCESS structure to save a pointer to user-allocated data.
  105. .ti -16n
  106. \f2dbgetuserdata()\f1    Return a pointer to user-allocated data from the DBPROCESS structure.
  107. .in -16n
  108. .ps +2
  109. .vs +2
  110. .ad
  111. .H2 "Return Parameter Values from Stored Procedures"
  112. In Release 4.0, stored procedures can return values to the application
  113. through parameters.
  114. The following routines support this capability:
  115. .sp
  116. .na
  117. .ps -2
  118. .vs -2
  119. .in +16n
  120. .ta +16n
  121. .ti -16n
  122. \f2dbnumrets()\f1    Determine the number of return parameter values generated by a stored procedure.
  123. .ti -16n
  124. \f2dbretdata()\f1    Return a pointer to a return parameter value.
  125. .ti -16n
  126. \f2dbretname()\f1    Return the parameter name associated with a return parameter value.
  127. .ti -16n
  128. \f2dbretlen()\f1    Return the length of a return parameter value.
  129. .ti -16n
  130. \f2dbrettype()\f1    Return the datatype of a return parameter value.
  131. .in -16n
  132. .ps +2
  133. .vs +2
  134. .ad
  135. .H2 "Return Status from Stored Procedures"
  136. Stored procedures now return status values to the application.
  137. The following routines support this capability:
  138. .sp
  139. .na
  140. .ps -2
  141. .vs -2
  142. .in +16n
  143. .ta +16n
  144. .ti -16n
  145. \f2dbretstatus()\f1    Determine the status number returned by a stored procedure.
  146. .ti -16n
  147. \f2dbhasretstat()\f1    Determine whether the current command generated a status number.
  148. .ps +2
  149. .vs +2
  150. .ad
  151. .H2 "Remote Procedure Calls"
  152. Remote procedure calls provide an alternative way to call
  153. a stored procedure.
  154. They have certain advantages over the TRANSACT-SQL EXECUTE
  155. command.
  156. These routines support remote procedure calls:
  157. .sp
  158. .na
  159. .ps -2
  160. .vs -2
  161. .in +16n
  162. .ta +16n
  163. .ti -16n
  164. \f2dbrpcinit()\f1    Initialize a remote procedure call.
  165. .ti -16n
  166. \f2dbrpcparam()\f1    Add a parameter to a remote procedure call.
  167. .ti -16n
  168. \f2dbrpcsend()\f1    Signal the end of a remote procedure call.
  169. .ps +2
  170. .vs +2
  171. .ad
  172. .H2 "Remote Passwords"
  173. In Release 4.0, a command batch or stored procedure running on one
  174. \*S can call a stored procedure on another \*S.
  175. To do this, the first \*S must log into the second.
  176. The application initiating this server-to-server communication
  177. can specify the password that the first \*S will use when it logs into
  178. the remote \*S.
  179. .sp
  180. .na
  181. .ps -2
  182. .vs -2
  183. .in +16n
  184. .ta +16n
  185. .ti -16n
  186. \f2dbrpwset()\f1    Add a remote password to the LOGINREC structure.
  187. .ti -16n
  188. \f2dbrpwclr()\f1    Clear all remote passwords from the LOGINREC structure.
  189. .ps +2
  190. .vs +2
  191. .ad
  192. .H2 "Initialization"
  193. There are two new routines dealing with \*L initialization:
  194. .sp
  195. .na
  196. .ps -2
  197. .vs -2
  198. .in +16n
  199. .ta +16n
  200. .ti -16n
  201. \f2dbinit()\f1    Initialize \*L.
  202. .ti -16n
  203. \f2dbloginfree()\f1    Free a login record.
  204. .ps +2
  205. .vs +2
  206. .ad
  207. .H2 "Result Column Information"
  208. There's one new routine in this category:
  209. .sp
  210. .na
  211. .ps -2
  212. .vs -2
  213. .in +16n
  214. .ta +16n
  215. .ti -16n
  216. \f2dbvarylen()\f1    Determine whether a result column's data can vary in length.
  217. .ps +2
  218. .vs +2
  219. .ad
  220. .H2 "VMS Asynchronous Capability"
  221. Several routines now have asynchronous VMS versions.
  222. These allow the application to perform 
  223. other actions while awaiting a \*S response.
  224. .sp
  225. .na
  226. .ps -2
  227. .vs -2
  228. .in +16n
  229. .ta +16n
  230. .ti -16n
  231. \f2dbcancel_a()\f1    The asynchronous version of \f2dbcancel()\f1.
  232. .ti -16n
  233. \f2dbnextrow_a()\f1    The asynchronous version of \f2dbnextrow()\f1.
  234. .ti -16n
  235. \f2dbopen_a()\f1    The asynchronous version of \f2dbopen()\f1.
  236. .ti -16n
  237. \f2dbresults_a()\f1    The asynchronous version of \f2dbresults()\f1.
  238. .ti -16n
  239. \f2dbsqlexec_a()\f1    The asynchronous version of \f2dbsqlexec()\f1.
  240. .ps +2
  241. .vs +2
  242. .ad
  243. .H2 "Allocating a Network Connection Structure"
  244. For OS/2 and MS-DOS, 
  245. DB-Library contains a routine that allows the application to provide the network connection information
  246. normally obtained through the \f2interfaces\f1 file.
  247. .sp
  248. .na
  249. .ps -2
  250. .vs -2
  251. .in +16n
  252. .ta +16n
  253. .ti -16n
  254. \f2dbsetconnect()\f1    Allocate and initialize a network connection structure.
  255. .ps +2
  256. .vs +2
  257. .ad
  258. .H2 "Bulk Copy"
  259. A new set of bulk copy routines replaces the previous set.
  260. Among the major improvements, the new routines 
  261. use the DB-Library error handling facilities
  262. and allow reuse of a DBPROCESS structure.
  263. In most instances, the new routines correspond closely in function to the old.
  264. .sp
  265. .na
  266. .ps -2
  267. .vs -2
  268. .in +16n
  269. .ta +16n
  270. .ti -16n
  271. \f2bcp_batch()\f1    Save any preceding rows in the \*S.
  272. .ti -16n
  273. \f2bcp_bind()\f1    Bind data from a program variable to a \*S table.
  274. .ti -16n
  275. \f2bcp_colfmt()\f1    Specify the format of a host file for bulk copy purposes.
  276. .ti -16n
  277. \f2bcp_collen()\f1    Set the program variable data length for the current copy IN.
  278. .ti -16n
  279. \f2bcp_colptr()\f1    Set the program variable data address for the current copy IN.
  280. .ti -16n
  281. \f2bcp_columns()\f1    Set the total number of columns found in the host file.
  282. .ti -16n
  283. \f2bcp_control()\f1    Change various control parameter default settings.
  284. .ti -16n
  285. \f2bcp_done()\f1    End a bulk copy from program variables into the \*S.
  286. .ti -16n
  287. \f2bcp_exec()\f1    Execute a bulk copy of data between a database table and a host file.
  288. .ti -16n
  289. \f2bcp_init()\f1    Initialize bulk copy.
  290. .ti -16n
  291. \f2bcp_moretext()\f1    Send part of a text or image value to the \*S.
  292. .ti -16n
  293. \f2bcp_sendrow()\f1    Send a row of data from program variables to the \*S.
  294. .ti -16n
  295. \f2BCP_SETL()\f1    Set the LOGINREC for bulk copy operations.
  296. .ps +2
  297. .vs +2
  298. .ad
  299. .H1 "Changes to Existing Routines and Manual Pages"
  300. The following manual pages have significant changes:
  301. .sp
  302. .na
  303. .ps -2
  304. .vs -2
  305. .in +16n
  306. .ta +16n
  307. .ti -16n
  308. \f2dbbind()\f1        Accommodation for image and text data.
  309. .ti -16n
  310. \f2dbconvert()\f1        Accommodation for image and text data.
  311. .ti -16n
  312. \f2dbcount()\f1    Additional return value.
  313. .ti -16n
  314. \f2dberrhandle()\f1    User-supplied handler has additional parameters.
  315. .ti -16n
  316. \f2dbmsghandle()\f1    User-supplied handler has additional parameters.
  317. .ti -16n
  318. \f2dbsetbusy()\f1    User-supplied handler gets passed a DBPROCESS parameter.
  319. .ti -16n
  320. \f2dbsetidle()\f1    User-supplied handler gets passed a DBPROCESS parameter.
  321. .ti -16n
  322. \f2dbsetinterrupt()\f1    User-supplied handler gets passed a DBPROCESS parameter.
  323. .ti -16n
  324. \f2errors\f1    Additional DB-Library error messages.
  325. .ti -16n
  326. \f2options\f1    Additional DB-Library options.
  327. .ti -16n
  328. \f2types\f1    Text and image datatypes.
  329. .ps +2
  330. .vs +2
  331. .ad
  332. .H1 "Routines No Longer Documented"
  333. The following routines are no longer documented, for the reasons given:
  334. .sp
  335. .na
  336. .ps -2
  337. .vs -2
  338. .in +16n
  339. .ta +16n
  340. .ti -16n
  341. \f2datetochar()\f1    Superseded by \f2dbconvert()\f1.
  342. .ti -16n
  343. \f2mnytochar()\f1    Superseded by \f2dbconvert()\f1.
  344. .ti -16n
  345. \f2dbaltname()\f1    Supported a feature that is not implemented in the \*S.
  346. .ti -16n
  347. \f2dberrstr()\f1    Superseded by \f2dberrhandle()\f1.
  348. .ti -16n
  349. \f2dbperror()\f1    Superseded by \f2dberrhandle()\f1.
  350. .ti -16n
  351. \f2dboserrstr()\f1        Superseded by \f2dberrhandle()\f1.
  352. .ti -16n
  353. \f2dberrno()\f1        Superseded by \f2dberrhandle()\f1.
  354. .ti -16n
  355. \f2dbgetmsg()\f1        Superseded by \f2dbmsghandle()\f1.
  356. .ti -16n
  357. \f2dbservermsg()\f1    Superseded by \f2dbmsghandle()\f1.
  358. .ti -16n
  359. \f2dbnummsg()\f1    Superseded by \f2dbmsghandle()\f1.
  360. .ti -16n
  361. \f2dbsetmsg()\f1    Superseded by \f2dbmsghandle()\f1.
  362. .in -16n
  363. .ps +2
  364. .vs +2
  365. .ad
  366. .sp
  367. In addition, the old bulk copy routines have been replaced by new ones, as described above.
  368. .H1 "The New DB-Library Reference Manual"
  369. The \f2DB-Library Reference Manual\f1 has been revised extensively for Release 4.0.
  370. Besides the changes outlined above,
  371. other major changes include the following:
  372. .Bl
  373. A new Introduction, which serves as an overview to the development of \*S applications.
  374. It includes a short introductory example that uses the most common DB-Library routines.
  375. A detailed description accompanies this example.
  376. The Introduction also contains useful descriptions of the various categories of DB-Library routines.
  377. .Bl
  378. The Section 2 manual pages have undergone considerable revision.
  379. They contain a large number of new comments, many of which deal with issues of usage.
  380. Many of the descriptions of parameters and return values have been expanded.
  381. In addition, much of the text has been rewritten for clarity.
  382. .Bl
  383. Section 3, formerly Section 4, contains an expanded introduction to the two-phase commit special library.
  384. .Bl
  385. Appendix A is new.
  386. It contains the alphabetical list of routines that used to be in the Introduction.
  387. .Bl
  388. The index is greatly expanded, with new entries based on key concepts.
  389. .Bz
  390. .H1 "The DB-Library Reference Supplement"
  391. The new \f2\*L Reference Supplement\f1 serves as a companion document
  392. to the \f2\*L Reference Manual\f1.
  393. It comprises the system-specific material (example programs and
  394. information on compiling and linking an application) formerly
  395. contained in Section 3.
  396. There are separate versions of the \f2Supplement\f1 for each operating
  397. system that \*L runs on.
  398. You should place the version for your operating system
  399. behind the \f2\*L Reference Manual\f1 in the binder.
  400. .LP
  401. The UNIX version of the \f2Supplement\f1 includes an environment-specific section,
  402. Appendix A, to accommodate different versions of UNIX.
  403. Because the contents of this appendix vary according to the UNIX environment you're using,
  404. it is packaged separately, with the \f2Release Bulletin\f1.
  405. .LP
  406. In comparison with the material previously contained in Section 3, the \f2Supplement\f1
  407. includes additional examples that illustrate most of the new routines.
  408. It also includes a complete example of a two-phase commit application.
  409. The VMS version of the \f2Supplement\f1 incorporates the material on shareable \*L,
  410. which first appeared in the \f2SYBASE 3.2 VAX/VMS Supplement\f1.
  411.