home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbnextrow.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  4.6 KB  |  133 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                dbnextrow
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbnextrow
  6.  
  7.   FUNCTION:
  8.        Read the next result row.
  9.  
  10.   SYNTAX:
  11.        STATUS dbnextrow(dbproc)
  12.  
  13.        DBPROCESS *dbproc;
  14.  
  15.   COMMENTS:
  16.  
  17.        o dbnextrow() reads the next row of result  data,  starting  with
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbnextrow               Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.          the first row returned from the  SQL Server.   Ordinarily,  the
  27.          next  result  row is read directly from the SQL Server.  If the
  28.          DBBUFFER option is turned on and rows have  been  read  out  of
  29.          order  by calling dbgetrow(), the next row is read instead from
  30.          a linked list of buffered rows.  When  dbnextrow()  is  called,
  31.          any binding of row data to program variables (as specified with
  32.          dbbind() or dbaltbind()) takes effect.
  33.  
  34.        o The application must successfully call  dbresults()  before  it
  35.          can make any calls to dbnextrow().
  36.        o To determine whether a particular command is one  that  returns
  37.          rows  and  needs  results  processing  with  dbnextrow(),  call
  38.          DBROWS() after dbresults().
  39.  
  40.        o Normally, each result row is processed in  turn  by  repeatedly
  41.          calling  dbnextrow()  until it returns NO_MORE_ROWS.  To cancel
  42.          the current set of results instead, call dbcanquery.   After  a
  43.          call to dbcanquery(), it is safe to call dbresults() again.
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                dbnextrow
  47.   ______________________________________________________________________
  48.  
  49.        o The typical sequence of calls is:
  50.  
  51.          DBINT         xvariable;
  52.          DBCHAR        yvariable[10];
  53.  
  54.          /* read the query into the command buffer */
  55.          dbcmd(dbproc, "select x = 100, y = 'hello'");
  56.  
  57.          /* send the query to SQL Server */
  58.          dbsqlexec(dbproc);
  59.  
  60.          /* get ready to process the results of the query */
  61.          dbresults(dbproc);
  62.  
  63.          /* bind column data to program variables */
  64.          dbbind(dbproc, 1, INTBIND, (DBINT) 0, (BYTE *) &xvariable);
  65.          dbbind(dbproc, 2, STRINGBIND, (DBINT) 0, yvariable);
  66.  
  67.  
  68.   dbnextrow               Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.  
  71.          /* now process each row */
  72.          while (dbnextrow(dbproc) != NO_MORE_ROWS)
  73.          {
  74.              C-code to print or process row data
  75.          }
  76.  
  77.  
  78.        o The SQL Server can return two types of rows: regular rows  con-
  79.          taining  data  from  columns designated by a SELECT statement's
  80.          select-list,  and  compute  rows  resulting  from  the  COMPUTE
  81.          clause.   To  facilitate  the  processing  of  result rows from
  82.          SQL Server, dbnextrow() returns different values  according  to
  83.          the type of row.  See the section "RETURNS" for details.
  84.        o To display SQL Server result data on the default output device,
  85.          you can use dbprrow() instead of dbnextrow().
  86.  
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                dbnextrow
  91.   ______________________________________________________________________
  92.  
  93.  
  94.   PARAMETERS:
  95.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  96.            connection for a particular front end/SQL Server process.  It
  97.            contains all the information that DB-Library uses  to  manage
  98.            communications and data between the front end and SQL Server.
  99.  
  100.   RETURNS:
  101.        dbnextrow() can return five different types of values:
  102.  
  103.        o If a regular row is read, REG_ROW is returned.
  104.        o If a compute row is read, the computeid of the row is returned.
  105.          (See dbaltbind() for information on the computeid.)
  106.  
  107.        o If there are no more rows to be  read  or  the  command  didn't
  108.          return any rows, NO_MORE_ROWS is returned.
  109.  
  110.  
  111.  
  112.   dbnextrow               Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.        o If buffering is turned on and reading the next row would  cause
  115.          the buffer to be exceeded, BUF_FULL is returned.  In this case,
  116.          no row will have been read. To read any more rows, at least one
  117.          row must first be pruned from the top of the row buffer by cal-
  118.          ling dbclrbuf().
  119.  
  120.        o If the routine was unsuccessful, FAIL is returned.
  121.  
  122.   SEE ALSO:
  123.        dbaltbind, dbbind, dbcanquery, dbclrbuf,  dbgetrow,  dbnextrow_a,
  124.        dbprrow, options
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.