home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbresults.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  4.2 KB  |  115 lines
  1. .Na "dbresults" 
  2. .Aa
  3. .Fu
  4. Set up the results of the next query.
  5. .Ih "result data, getting"
  6. .Sy
  7. .Sf "RETCODE dbresults(dbproc)"
  8. .Sp "DBPROCESS" "*dbproc"
  9. .Co
  10. .Bl
  11. This routine sets up the next command in the command batch for processing.
  12. The application program calls it after
  13. .I "dbsqlexec()"
  14. or
  15. .I "dbsqlok()"
  16. returns SUCCEED.
  17. The first call to
  18. .I "dbresults()" 
  19. will always return either SUCCEED or NO_MORE_RESULTS if
  20. the call to
  21. .I "dbsqlexec()"
  22. or
  23. .I "dbsqlok()"
  24. has returned SUCCEED.
  25. Once \f2dbresults()\f1 returns SUCCEED,
  26. the application typically processes any result rows with
  27. .I "dbnextrow()."
  28. .Bl
  29. To manage multiple input data streams efficiently, a UNIX
  30. application can confirm that unread bytes are available,
  31. either in the \*L network buffer (by calling \f2DBRBUF()\f1) or in the network itself
  32. (by calling the UNIX \f2select()\f1 function), before calling \f2dbresults()\f1.
  33. .Bl
  34. .I "dbresults()"
  35. must be called for each command in the command batch, whether or not the command returns
  36. any rows.  If the application code
  37. doesn't know how many commands are in the batch (for example, if the application is
  38. designed to process ad hoc queries), it can call
  39. .I "dbresults()"
  40. until it returns NO_MORE_RESULTS.
  41. .sp 0.5v
  42. \f2dbresults()\f1 must also ordinarily
  43. be called once for any stored procedure executed in the command batch.
  44. .Ih "stored procedure results"
  45. .Ih "results, stored procedure"
  46. However, if the stored procedure contains more than one SQL SELECT statement,
  47. then \f2dbresults()\f1 must be called once for each SELECT.
  48. Again, the easiest way to do this is to continue to call \f2dbresults()\f1 
  49. until it returns NO_MORE_RESULTS.
  50. .Bl
  51. To cancel the remaining results from the command batch (and eliminate the need to continue
  52. calling \f2dbresults()\f1 until it returns NO_MORE_RESULTS), call \f2dbcancel()\f1.
  53. .Bl
  54. To determine whether a particular command is one that returns rows and
  55. needs results processing with \f2dbnextrow()\f1, call \f2DBROWS()\f1 after
  56. the \f2dbresults()\f1 call.
  57. .Bl
  58. The typical sequence of calls for using \f2dbresults()\f1 with \f2dbsqlexec()\f1 is:
  59. .ta +4n +4n +4n +4n +4n +4n
  60. .SD
  61. .so dbresults.ex
  62. .ED
  63. Example 1 in the \f2\*L Reference Supplement\f1 shows how to use \f2dbresults()\f1 to process a multi-query command batch.
  64. .Bl
  65. Another use for
  66. \f2dbresults()\f1 is to process the results of a remote procedure
  67. call made with \f2dbrpcsend()\f1.
  68. See the \f2dbrpcsend()\f1 manual page for details.
  69. .Bl
  70. An asynchronous version of \f2dbresults()\f1, called \f2dbresults_a()\f1, is available for VMS.
  71. .Bz
  72. .Pa
  73. .Pi dbproc
  74. A pointer to the DBPROCESS structure that provides the connection
  75. for a particular front-end/\*S process.  It contains all the
  76. information that \*L uses to manage communications and data between the
  77. front end and \*S.
  78. .in -.375i
  79. .Re
  80. .br
  81. SUCCEED, FAIL or NO_MORE_RESULTS.
  82. \f2dbresults()\f1 returns
  83. NO_MORE_RESULTS if all commands in the buffer have already been processed.
  84. The most common reason for failing is a run-time error, such as a database permission violation.
  85. .sp 0.5v
  86. The number of commands in the command buffer determines whether \f2dbsqlexec()\f1 or \f2dbresults()\f1
  87. traps a run-time error. 
  88. If the buffer contains only a single command, a run-time error will cause
  89. \f2dbsqlexec()\f1 to fail.
  90. If the command buffer contains multiple commands, 
  91. a run-time error will \f2not\f1 cause \f2dbsqlexec()\f1 to fail.
  92. Instead, the \f2dbresults()\f1 call that processes the command causing the run-time error will fail.
  93. .sp 0.5v
  94. The situation is a bit more complicated for run-time errors and stored procedures.
  95. A run-time error on an EXECUTE command may cause \f2dbresults()\f1 to fail,
  96. in accordance with the rule given in the previous paragraph.
  97. A run-time error on a statement \f2inside\f1 a stored procedure will not cause \f2dbresults()\f1 to fail,
  98. however.
  99. For example, if the stored procedure contains an INSERT statement and the user does not have
  100. insert permission on the database table, the INSERT statement will fail, but \f2dbresults()\f1
  101. will still return SUCCEED.
  102. To check for run-time errors inside stored procedures, use the \f2dbretstatus()\f1 routine
  103. to look at the procedure's return status, and trap relevant \*S messages inside your message handler.
  104. .Sa
  105. dbbind,
  106. dbcancel,
  107. dbnextrow,
  108. DBRBUF,
  109. dbresults_a,
  110. dbretstatus,
  111. DBROWS,
  112. dbrpcsend,
  113. dbsqlexec,
  114. dbsqlok
  115.