home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbrpcparam.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  3.8 KB  |  100 lines
  1. .Na "dbrpcparam"
  2. .mc |
  3. .Aa
  4. .Fu
  5. Add a parameter to a remote procedure call.
  6. .Ih "remote procedure call"
  7. .Ih "stored procedure, calling"
  8. .Ih "call, remote procedure"
  9. .Sy
  10. .Sf "RETCODE dbrpcparam(dbproc, paramname, status, type, maxlen,"
  11. .sp -1v
  12. .Sf "                   datalen, value)"
  13. .Sp "DBPROCESS" "*dbproc"
  14. .Sp "char" "*paramname"
  15. .Sp "BYTE" "status"
  16. .Sp "int" "type"
  17. .Sp "DBINT" "maxlen"
  18. .Sp "DBINT" "datalen"
  19. .Sp "BYTE" "*value"
  20. .Co
  21. .Bl
  22. An application can call a stored procedure in two ways:
  23. by executing a command buffer containing a \*N EXECUTE statement or by making a
  24. remote procedure call (``rpc'').
  25. See the manual page for \f2dbrpcinit()\f1 for a discussion of
  26. the differences between these techniques.
  27. .Bl
  28. To make a remote procedure call,
  29. first call \f2dbrpcinit()\f1 to specify the stored procedure that's to be invoked.
  30. Then call \f2dbrpcparam()\f1 once for each of the stored procedure's parameters.
  31. Finally, call \f2dbrpcsend()\f1 to signify the end of the parameter list.
  32. This causes the server to begin executing the specified procedure.
  33. You can then call \f2dbsqlok()\f1, \f2dbresults()\f1, and \f2dbnextrow()\f1
  34. to process the stored procedure's results.
  35. (Note that you will need to call \f2dbresults()\f1 multiple times if the
  36. stored procedure contains more than one SELECT statement.)
  37. After all of the stored procedure's results have been processed,
  38. you can call the routines that process return parameters and status numbers,
  39. such as \f2dbretdata()\f1 and \f2dbretstatus()\f1.
  40. .Bl
  41. For an example of a remote procedure call, 
  42. see Example 8 in the \f2\*L Reference Supplement\f1.
  43. .Bz
  44. .Pa
  45. .Pi dbproc
  46. A pointer to the DBPROCESS structure that provides the connection
  47. for a particular front-end/server process.  It contains all the
  48. information that \*L uses to manage communications and data between the
  49. front end and the server.
  50. .Pi paramname
  51. A pointer to the name of the parameter to be invoked.
  52. This name must begin with the ``@'' symbol, which prefixes
  53. all stored procedure parameter names.
  54. As in the \*N EXECUTE statement, the name is optional.
  55. If it is not used, it should be specified as NULL.
  56. In that case, the order of the \f2dbrpcparam()\f1 calls
  57. determines the parameter to which each refers.
  58. .Pi status
  59. A one-byte bitmask of rpc-parameter options. So far, the only
  60. option available is DBRPCRETURN, which signifies that the
  61. application program would like this parameter used as
  62. a return parameter.
  63. .Pi type
  64. The datatype of the parameter (\f2e.g.,\f1 SYBINT1, SYBCHAR, etc.).
  65. .Pi maxlen
  66. For return parameters, this is the maximum desired byte length
  67. for the rpc parameter value returned from the stored procedure.
  68. \f2maxlen\f1 is relevant only for values whose datatypes are not fixed in length\(emthat is, 
  69. character, text, binary, and image values.
  70. If this parameter doesn't apply (\f2i.e.,\f1 if the \f2type\f1 is a fixed length datatype such as
  71. SYBINT2) or if you don't care about restricting
  72. the lengths of return parameters, set \f2maxlen\f1 to -1.
  73. \f2maxlen\f1 should also be set to -1 for parameters not designated as return parameters.
  74. .Pi datalen
  75. The actual byte length of the rpc parameter value that gets sent to the stored procedure.
  76. \f2datalen\f1 must be used with values whose datatypes are not fixed in length; that is, 
  77. character, text, binary, and image values.
  78. The byte length should \f2not\f1 count any null terminator.
  79. If this parameter doesn't apply (\f2i.e.,\f1 if the \f2type\f1 is a fixed length datatype such as
  80. SYBINT2), set \f2datalen\f1 to -1.
  81. If the value of the rpc parameter is NULL,
  82. you must set \f2datalen\f1 to 0, 
  83. even if the \f2type\f1 is a fixed length datatype.
  84. .Pi value
  85. A pointer to the rpc parameter itself.
  86. If \f2datalen\f1 is 0, this pointer will be ignored and treated as NULL.
  87. .in -.375i
  88. .Re
  89. .br
  90. SUCCEED or FAIL.
  91. .Sa
  92. dbnextrow,
  93. dbresults,
  94. dbretdata,
  95. dbretstatus,
  96. dbrpcinit,
  97. dbrpcsend,
  98. dbsqlok
  99. .mc
  100.