home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbretname.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  5.1 KB  |  133 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                dbretname
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbretname
  6.  
  7.   FUNCTION:
  8.        Determine the name of the stored procedure  parameter  associated
  9.        with a particular return parameter value.
  10.  
  11.   SYNTAX:
  12.        char *dbretname(dbproc, retnum)
  13.  
  14.        DBPROCESS *dbproc;
  15.        int       retnum;
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbretname               Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.   COMMENTS:
  28.  
  29.        o dbretname() returns a pointer to the null-terminated  parameter
  30.          name  associated  with  a  return parameter value from a stored
  31.          procedure.  It is useful in conjunction with  remote  procedure
  32.          calls and EXECUTE statements on 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                dbretname
  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 dbretname() 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  dbret-
  59.          name() or any other routines that process return parameters, it
  60.          must call dbresults() and dbnextrow() as many times  as  neces-
  61.          sary to 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.   dbretname               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 dbretlen() returns the length 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                dbretname
  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.   dbretname               Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.        A pointer to the null-terminated parameter name for the specified
  115.        return  value.   If  retnum  is out of range, dbretname() returns
  116.        NULL.
  117.  
  118.   SEE ALSO:
  119.        dbnextrow, dbnumrets, dbresults, dbretdata, dbretlen,  dbrettype,
  120.        dbrpcinit, dbrpcparam
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.