home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbrpcparam.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  5.2 KB  |  133 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89               dbrpcparam
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbrpcparam
  6.  
  7.   FUNCTION:
  8.        Add a parameter to a remote procedure call.
  9.  
  10.   SYNTAX:
  11.        RETCODE dbrpcparam(dbproc, paramname, status, type, maxlen,
  12.                           datalen, value)
  13.  
  14.        DBPROCESS *dbproc;
  15.        char      *paramname;
  16.        BYTE      status;
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbrpcparam              Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.        int       type;
  27.        DBINT     maxlen;
  28.        DBINT     datalen;
  29.        BYTE      *value;
  30.  
  31.   COMMENTS:
  32.  
  33.        o An application can call a stored procedure in two ways: by exe-
  34.          cuting  a  command  buffer  containing  a  Transact-SQL EXECUTE
  35.          statement or by making a remote procedure  call  ("rpc").   See
  36.          the manual page for dbrpcinit() for a discussion of the differ-
  37.          ences between these techniques.
  38.        o To make a remote procedure  call,  first  call  dbrpcinit()  to
  39.          specify  the  stored procedure that's to be invoked.  Then call
  40.          dbrpcparam() once for each of the  stored  procedure's  parame-
  41.          ters.   Finally,  call  dbrpcsend()  to  signify the end of the
  42.          parameter list.  This causes the server to begin executing  the
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89               dbrpcparam
  47.   ______________________________________________________________________
  48.          specified procedure.  You can then call dbsqlok(), dbresults(),
  49.          and  dbnextrow()  to  process  the  stored procedure's results.
  50.          (Note that you will need to call dbresults() multiple times  if
  51.          the  stored procedure contains more than one SELECT statement.)
  52.          After all of the stored  procedure's  results  have  been  pro-
  53.          cessed,  you  can call the routines that process return parame-
  54.          ters and status numbers, such as dbretdata() and dbretstatus().
  55.  
  56.        o For an example of a remote procedure call, see Example 8 in the
  57.          DB-Library Reference Supplement.
  58.  
  59.   PARAMETERS:
  60.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  61.            connection  for  a  particular  front-end/server process.  It
  62.            contains all the information that DB-Library uses  to  manage
  63.            communications and data between the front end and the server.
  64.        paramname -  A pointer  to  the  name  of  the  parameter  to  be
  65.            invoked.   This  name  must  begin with the "@" symbol, which
  66.  
  67.  
  68.   dbrpcparam              Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.            prefixes all stored procedure parameter  names.   As  in  the
  71.            Transact-SQL  EXECUTE statement, the name is optional.  If it
  72.            is not used, it should be specified as NULL.  In  that  case,
  73.            the  order of the dbrpcparam() calls determines the parameter
  74.            to which each refers.
  75.        status -  A one-byte bitmask of rpc-parameter  options.  So  far,
  76.            the  only  option  available  is DBRPCRETURN, which signifies
  77.            that the application program would like this  parameter  used
  78.            as a return parameter.
  79.        type -  The datatype of the parameter  (e.g.,  SYBINT1,  SYBCHAR,
  80.            etc.).
  81.        maxlen -  For return parameters, this is the maximum desired byte
  82.            length  for  the rpc parameter value returned from the stored
  83.            procedure.  maxlen is relevant only for  values  whose  data-
  84.            types  are  not  fixed  in  length-that  is, character, text,
  85.            binary, and image values.  If this  parameter  doesn't  apply
  86.            (i.e.,  if  the  type  is  a  fixed  length  datatype such as
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89               dbrpcparam
  91.   ______________________________________________________________________
  92.            SYBINT2) or if you don't care about restricting  the  lengths
  93.            of  return  parameters, set maxlen to -1.  maxlen should also
  94.            be set to -1 for parameters not designated as return  parame-
  95.            ters.
  96.        datalen -  The actual byte length of the rpc parameter value that
  97.            gets sent to the stored procedure.  datalen must be used with
  98.            values whose datatypes are not  fixed  in  length;  that  is,
  99.            character,  text,  binary, and image values.  The byte length
  100.            should not count any  null  terminator.   If  this  parameter
  101.            doesn't  apply  (i.e., if the type is a fixed length datatype
  102.            such as SYBINT2), set datalen to -1.  If the value of the rpc
  103.            parameter  is  NULL,  you  must set datalen to 0, even if the
  104.            type is a fixed length datatype.
  105.        value -  A pointer to the rpc parameter itself.  If datalen is 0,
  106.            this pointer will be ignored and treated as NULL.
  107.  
  108.   RETURNS:
  109.  
  110.  
  111.  
  112.   dbrpcparam              Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.        SUCCEED or FAIL.
  115.  
  116.   SEE ALSO:
  117.        dbnextrow,   dbresults,   dbretdata,   dbretstatus,    dbrpcinit,
  118.        dbrpcsend, dbsqlok
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.