home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbrpcinit.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  4.3 KB  |  111 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                dbrpcinit
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbrpcinit
  6.  
  7.   FUNCTION:
  8.        Initialize a remote procedure call.
  9.  
  10.   SYNTAX:
  11.        RETCODE dbrpcinit(dbproc, rpcname, options)
  12.  
  13.        DBPROCESS *dbproc;
  14.        char      *rpcname;
  15.        DBSMALLINToptions;
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbrpcinit               Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.   COMMENTS:
  28.  
  29.        o An application can call a stored procedure in two ways: by exe-
  30.          cuting  a  command  buffer  containing  a  Transact-SQL EXECUTE
  31.          statement or by making a remote procedure call ("rpc").
  32.        o Remote procedure calls  have  a  few  advantages  over  EXECUTE
  33.          statements:
  34.  
  35.           o An rpc passes the stored  procedure's  parameters  in  their
  36.             native  datatypes,  in  contrast  to  the EXECUTE statement,
  37.             which passes parameters as ASCII characters.  Therefore, the
  38.             rpc  method is faster and usually more compact than the EXE-
  39.             CUTE statement, because  it  does  not  require  either  the
  40.             application  program or the server to convert between native
  41.             datatypes and their ASCII equivalents.
  42.           o It is simpler and faster  to  accommodate  stored  procedure
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                dbrpcinit
  47.   ______________________________________________________________________
  48.             return parameters with an rpc, instead of an EXECUTE  state-
  49.             ment.   With an rpc, the return parameters are automatically
  50.             available to the application.  (Note, however, that a return
  51.             parameter  must  be  specified  as such when it's originally
  52.             added to the rpc via the dbrpcparam() routine.) If,  on  the
  53.             other  hand,  a  stored  procedure is called with an EXECUTE
  54.             statement, the return parameter values are available only if
  55.             the  command  batch  containing  the  EXECUTE statement uses
  56.             local variables, not constants, as  the  return  parameters.
  57.             This involves additional parsing each time the command batch
  58.             is executed.
  59.  
  60.        o To make a remote procedure  call,  first  call  dbrpcinit()  to
  61.          specify  the  stored procedure that's to be invoked.  Then call
  62.          dbrpcparam() once for each of the  stored  procedure's  parame-
  63.          ters.   Finally,  call  dbrpcsend()  to  signify the end of the
  64.          parameter list.  This causes the server to begin executing  the
  65.          specified procedure.  You can then call dbsqlok(), dbresults(),
  66.  
  67.  
  68.   dbrpcinit               Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          and dbnextrow() to  process  the  stored  procedure's  results.
  71.          (Note  that you will need to call dbresults() multiple times if
  72.          the stored procedure contains more than one SELECT  statement.)
  73.          After  all  of  the  stored  procedure's results have been pro-
  74.          cessed, you can call the routines that process  return  parame-
  75.          ters and status numbers, such as dbretdata() and dbretstatus().
  76.  
  77.        o For an example of a remote procedure call, see Example 8 in the
  78.          DB-Library Reference Supplement.
  79.  
  80.   PARAMETERS:
  81.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  82.            connection  for  a  particular  front-end/server process.  It
  83.            contains all the information that DB-Library uses  to  manage
  84.            communications and data between the front end and the server.
  85.        rpcname -  A pointer to the name of the stored  procedure  to  be
  86.            invoked.
  87.        options -  A two-byte bitmask of rpc options. So  far,  the  only
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                dbrpcinit
  91.   ______________________________________________________________________
  92.            option available is DBRPCRECOMPILE, which causes  the  stored
  93.            procedure to be recompiled before it is executed.
  94.  
  95.   RETURNS:
  96.        SUCCEED or FAIL.
  97.  
  98.   SEE ALSO:
  99.        dbnextrow,   dbresults,   dbretdata,   dbretstatus,   dbrpcparam,
  100.        dbrpcsend, dbsqlok
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.