home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbsqlok.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  5.1 KB  |  120 lines
  1. .Na "dbsqlok" 
  2. .Aa
  3. .Fu
  4. Wait for results from the \*S and verify the correctness of the instructions
  5. the \*S is responding to.
  6. .Ih "command batch, verifying the correctness of"
  7. .Sy
  8. .Sf "RETCODE dbsqlok(dbproc)"
  9. .Sp "DBPROCESS" "*dbproc"
  10. .Co
  11. .Bl
  12. This routine waits for results from the \*S and verifies the correctness of the
  13. instructions that the \*S is responding to.
  14. .sp 0.5v
  15. The ``instructions that the \*S is responding to'' can be any of the following:
  16. .in +3n
  17. .Bl *
  18. A command batch (when \f2dbsqlok()\f1 is used with \f2dbsqlsend()\f1).
  19. .Bl *
  20. Processing information for handling chunks of text or image data
  21. (when \f2dbsqlok()\f1 is used with \f2dbmoretext()\f1).
  22. .Bl *
  23. A remote procedure call (when \f2dbsqlok()\f1 is used with \f2dbrpcsend()\f1).
  24. .in -3n
  25. .Bl
  26. The application must call \f2dbsqlok()\f1
  27. after a call to \f2dbsqlsend()\f1 or \f2dbrpcsend()\f1,
  28. and before and after a set of \f2dbmoretext()\f1 calls.
  29. A successful \f2dbsqlok()\f1 call must always be followed by
  30. a call to \f2dbresults()\f1 to process the results.
  31. .Bl
  32. \f2dbsqlexec()\f1 is equivalent to \f2dbsqlsend()\f1 followed by \f2dbsqlok()\f1.
  33. .Bl
  34. The use of \f2dbsqlsend()\f1 with \f2dbsqlok()\f1 is of particular value in UNIX
  35. applications.
  36. After sending a query to \*S, \f2dbsqlexec()\f1 waits until
  37. a response is received or until the timeout period has elapsed.
  38. By substituting \f2dbsqlsend()\f1 and \f2dbsqlok()\f1 for \f2dbsqlexec()\f1,
  39. you can sometimes provide a way for a UNIX application
  40. to respond more effectively to multiple input and output streams.
  41. The time between the request for
  42. information from \*S (made via a call to \f2dbsqlsend()\fP)
  43. and \*S's response (read by calling \f2dbsqlok()\fP)
  44. can be used, in conjunction with \f2DBIORDESC()\f1 or \f2DBIOWDESC()\f1, to
  45. service other parts of the application.
  46. \f2DBIORDESC()\f1 and \f2DBIOWDESC()\f1 are available for UNIX only.
  47. See the manual pages for those two routines for more information.
  48. .sp 0.5v
  49. To manage input data streams efficiently, a UNIX
  50. application using \f2dbsqlok()\f1 should
  51. confirm that unread bytes are available,
  52. either in the \*L network buffer (by calling \f2DBRBUF()\f1) or in the network itself
  53. (by calling the UNIX \f2select()\f1 function), before calling \f2dbresults()\f1.
  54. .sp 0.5v
  55. For a UNIX example that illustrates the use of \f2dbsqlok()\f1 with \f2dbsqlsend()\f1,
  56. \f2DBRBUF()\f1, \f2DBIORDESC()\f1, and \f2DBIOWDESC()\f1, see the \f2\*L Reference Supplement\f1.
  57. .sp 0.5v
  58. On occasion the operating system may inform the application that
  59. data is ready for \f2dbsqlok()\f1 to read when only the first part of the
  60. \*S response is present.
  61. When this occurs, \f2dbsqlok()\f1 waits for the rest of the response or until
  62. the timeout period has elapsed, just like \f2dbsqlexec()\f1.
  63. In practice, however, the entire response is usually available at one time.
  64. .Bl
  65. \f2dbsqlok()\f1 is also useful in text update operations.
  66. When chunks of text are sent to \*S via \f2dbwritetext()\f1 and \f2dbmoretext()\f1,
  67. \f2dbsqlok()\f1 must be called before the first call to \f2dbmoretext()\f1 and after the last
  68. call to \f2dbmoretext()\f1.
  69. For an example of its use in this context, see the manual page for \f2dbwritetext()\f1.
  70. .Bl
  71. \f2dbsqlok()\f1 is also necessary when making remote procedure calls.
  72. The application must call it
  73. after \f2dbrpcsend()\f1 and before \f2dbresults()\f1.
  74. .Bz
  75. .Pa
  76. .Pi dbproc
  77. A pointer to the DBPROCESS structure that provides the connection
  78. for a particular front-end/\*S process.  It contains all the
  79. information that \*L uses to manage communications and data between the
  80. front end and \*S.
  81. .in -.375i
  82. .Re
  83. .br
  84. SUCCEED or FAIL. 
  85. The most common reason for failing is a SQL syntax error.
  86. \f2dbsqlok()\f1 will also fail if there are semantic errors, such as
  87. incorrect column or table names.
  88. Failure occurs if \f2any\f1 of the commands in the batch contains a semantic or syntax error.
  89. .sp 0.5v
  90. In addition, a run-time error, such as a database protection violation, will cause \f2dbsqlok()\f1 to
  91. fail \f2if\f1 the command buffer contains only a single command.
  92. If the command buffer contains multiple commands, a run-time error will \f2not\f1 cause \f2dbsqlok()\f1 to fail.
  93. Instead, failure will occur with the \f2dbresults()\f1 call that processes the command causing the run-time error.
  94. .sp 0.5v
  95. The situation is a bit more complicated for run-time errors and stored procedures.
  96. A run-time error on an EXECUTE command may cause \f2dbsqlok()\f1 to fail,
  97. in accordance with the rule given in the previous paragraph.
  98. A run-time error on a statement \f2inside\f1 a stored procedure will not cause \f2dbsqlok()\f1 to fail,
  99. however.
  100. For example, if the stored procedure contains an INSERT statement and the user does not have
  101. insert permission on the database table, the INSERT statement will fail, but \f2dbsqlok()\f1
  102. will still return SUCCEED.
  103. To check for run-time errors inside stored procedures, use the \f2dbretstatus()\f1 routine
  104. to look at the procedure's return status, and trap relevant \*S messages inside your message handler.
  105. .Sa
  106. dbcmd, 
  107. dbfcmd,
  108. DBIORDESC, 
  109. DBIOWDESC, 
  110. dbmoretext,
  111. dbnextrow, 
  112. DBRBUF,
  113. dbresults, 
  114. dbretstatus,
  115. dbrpcsend,
  116. dbsettime, 
  117. dbsqlexec,
  118. dbsqlsend,
  119. dbwritetext
  120.