home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbrpcinit.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  3.0 KB  |  85 lines
  1. .Na "dbrpcinit"
  2. .mc |
  3. .Aa
  4. .Fu
  5. Initialize a remote procedure call.
  6. .Ih "remote procedure call"
  7. .Ih "stored procedure, calling"
  8. .Ih "call, remote procedure"
  9. .Sy
  10. .Sf "RETCODE dbrpcinit(dbproc, rpcname, options)"
  11. .Sp "DBPROCESS" "*dbproc"
  12. .Sp "char" "*rpcname"
  13. .Sp "DBSMALLINT" "options"
  14. .Co
  15. .Bl
  16. An application can call a stored procedure in two ways:
  17. by executing a command buffer containing a \*N EXECUTE statement or by making a
  18. remote procedure call (``rpc'').
  19. .Bl
  20. Remote procedure calls have a few advantages over EXECUTE statements:
  21. .in +3n
  22. .Bl *
  23. An rpc passes the stored procedure's parameters in their
  24. native datatypes, in contrast to
  25. the EXECUTE statement, which passes parameters 
  26. as ASCII characters.
  27. Therefore, 
  28. the rpc method is faster and usually more compact than the EXECUTE statement,
  29. because it does not require either the application program or the server to
  30. convert between native datatypes and their ASCII equivalents. 
  31. .Bl *
  32. It is simpler and faster to accommodate stored procedure return parameters
  33. with an rpc, instead of an EXECUTE statement.
  34. With an rpc, the return parameters are automatically available to the application.
  35. (Note, however, that a return parameter must be specified as such
  36. when it's originally added to the rpc via the \f2dbrpcparam()\f1 routine.)
  37. If, on the other hand,
  38. a stored procedure is called with an EXECUTE statement, the return parameter values
  39. are available only if the command batch containing the EXECUTE statement uses
  40. local variables, not constants, as the return parameters.
  41. This involves additional parsing each time the command batch is executed.
  42. .in -3n
  43. .Bl
  44. To make a remote procedure call,
  45. first call \f2dbrpcinit()\f1 to specify the stored procedure that's to be invoked.
  46. Then call \f2dbrpcparam()\f1 once for each of the stored procedure's parameters.
  47. Finally, call \f2dbrpcsend()\f1 to signify the end of the parameter list.
  48. This causes the server to begin executing the specified procedure.
  49. You can then call \f2dbsqlok()\f1, \f2dbresults()\f1, and \f2dbnextrow()\f1
  50. to process the stored procedure's results.
  51. (Note that you will need to call \f2dbresults()\f1 multiple times if the
  52. stored procedure contains more than one SELECT statement.)
  53. After all of the stored procedure's results have been processed,
  54. you can call the routines that process return parameters and status numbers,
  55. such as \f2dbretdata()\f1 and \f2dbretstatus()\f1.
  56. .Bl
  57. For an example of a remote procedure call, 
  58. see Example 8 in the \f2\*L Reference Supplement\f1.
  59. .Bz
  60. .Pa
  61. .Pi dbproc
  62. A pointer to the DBPROCESS structure that provides the connection
  63. for a particular front-end/server process.  It contains all the
  64. information that \*L uses to manage communications and data between the
  65. front end and the server.
  66. .Pi rpcname
  67. A pointer to the name of the stored procedure to be invoked.
  68. .Pi options
  69. A two-byte bitmask of rpc options. So far, the only option
  70. available is DBRPCRECOMPILE, which causes the stored
  71. procedure to be recompiled before it is executed.
  72. .in -.375i
  73. .Re
  74. .br
  75. SUCCEED or FAIL.
  76. .Sa
  77. dbnextrow,
  78. dbresults,
  79. dbretdata,
  80. dbretstatus,
  81. dbrpcparam, 
  82. dbrpcsend,
  83. dbsqlok
  84. .mc
  85.