home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbretlen.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  5.0 KB  |  133 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                 dbretlen
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbretlen
  6.  
  7.   FUNCTION:
  8.        Determine the length of a return parameter value generated  by  a
  9.        stored procedure.
  10.  
  11.   SYNTAX:
  12.        DBINT dbretlen(dbproc, retnum)
  13.  
  14.        DBPROCESS *dbproc;
  15.        int       retnum;
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbretlen                Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.   COMMENTS:
  28.  
  29.        o dbretlen() returns the length of a particular return  parameter
  30.          value  generated  by  a stored procedure.  It is useful in con-
  31.          junction with remote procedure calls and EXECUTE statements  on
  32.          stored procedures.
  33.        o Transact-SQL stored procedures can return values for  specified
  34.          "return  parameters."  Changes  made  to  the value of a return
  35.          parameter inside the stored procedure are then available to the
  36.          program  that  called  the procedure.  This is analogous to the
  37.          "pass by reference"  facility  available  in  some  programming
  38.          languages.
  39.  
  40.          For a parameter to function as a return parameter, it  must  be
  41.          declared  as  such  within  the  stored procedure.  The EXECUTE
  42.          statement or remote procedure call that calls the  stored  pro-
  43.          cedure must also indicate that the parameter should function as
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                 dbretlen
  47.   ______________________________________________________________________
  48.          a return parameter.  In the case of a remote procedure call, it
  49.          is  the dbrpcparam() routine that specifies whether a parameter
  50.          is a return parameter.
  51.  
  52.        o When executing a  stored  procedure,  the  server  returns  any
  53.          parameter values immediately after returning all other results.
  54.          Therefore, the application can call dbretlen() only after  pro-
  55.          cessing  the stored procedure's results by calling dbresults(),
  56.          as well as dbnextrow() if appropriate.   (Note  that  a  stored
  57.          procedure  can  generate  several  sets of results-one for each
  58.          SELECT it contains.  Before the application can call dbretlen()
  59.          or  any  other routines that process return parameters, it must
  60.          call dbresults() and dbnextrow() as many times as necessary  to
  61.          process all the results.)
  62.        o If the stored procedure is  invoked  with  a  remote  procedure
  63.          call,  the  return parameter values are automatically available
  64.          to  the  application.   If,  on  the  other  hand,  the  stored
  65.  
  66.  
  67.  
  68.   dbretlen                Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          procedure is invoked with  an  EXECUTE  statement,  the  return
  71.          parameter  values  are available only if the command batch con-
  72.          taining the EXECUTE statement uses local  variables,  not  con-
  73.          stants, for the return parameters.
  74.  
  75.        o Other  routines  return  additional  information  about  return
  76.          parameter values:
  77.           o dbnumrets() returns the total  number  of  return  parameter
  78.             values.
  79.  
  80.           o dbretdata() returns a pointer to a parameter value.
  81.           o dbretname() returns the name of a parameter value.
  82.  
  83.           o dbrettype() returns the datatype of a parameter value.
  84.        o For an example of this routine, see Example 8 in the DB-Library
  85.          Reference Supplement.
  86.  
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                 dbretlen
  91.   ______________________________________________________________________
  92.  
  93.   PARAMETERS:
  94.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  95.            connection for a particular front-end/SQL Server process.  It
  96.            contains all the information that DB-Library uses  to  manage
  97.            communications and data between the front end and SQL Server.
  98.        retnum -  The number of the return parameter value  of  interest.
  99.            The first return value is 1.  Values are returned in the same
  100.            order as the parameters  were  originally  specified  in  the
  101.            stored  procedure's  CREATE  PROCEDURE statement.  (Note that
  102.            this is not necessarily the same order as  specified  in  the
  103.            remote  procedure  call.)  When specifying retnum, non-return
  104.            parameters do not count.  For example, if the second  parame-
  105.            ter  in  a stored procedure is the only return parameter, its
  106.            retnum is 1, not 2.
  107.  
  108.   RETURNS:
  109.  
  110.  
  111.  
  112.   dbretlen                Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.        The length of the specified return parameter value.  If retnum is
  115.        out  of  range,  dbretlen()  returns  -1.  If the return value is
  116.        null, dbretlen() returns 0.
  117.  
  118.   SEE ALSO:
  119.        dbnextrow, dbnumrets, dbresults, dbretdata, dbretname, dbrettype,
  120.        dbrpcinit, dbrpcparam
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.