home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbgetrow.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  4.5 KB  |  111 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                 dbgetrow
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbgetrow
  6.  
  7.   FUNCTION:
  8.        Read the specified row in the row buffer.
  9.  
  10.   SYNTAX:
  11.        STATUS dbgetrow(dbproc, row)
  12.  
  13.        DBPROCESS *dbproc;
  14.        DBINT     row;
  15.  
  16.   COMMENTS:
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbgetrow                Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.        o dbgetrow() sets the current row in the row buffer to a specific
  28.          row  and  reads  it.   This  routine only works if the DBBUFFER
  29.          option is on,  enabling  row  buffering.   When  dbgetrow()  is
  30.          called, any binding of row data to program variables (as speci-
  31.          fied with dbbind() or dbaltbind()) takes effect.
  32.        o Row buffering provides a way to  keep  a  specified  number  of
  33.          SQL Server  result rows in program memory.  Without row buffer-
  34.          ing, the result row generated  by  each  new  dbnextrow()  call
  35.          overwrites  the  contents  of  the  previous  result  row.  Row
  36.          buffering is therefore useful for programs that need to look at
  37.          result  rows  in  a  non-sequential  manner.  It does, however,
  38.          carry a memory and performance penalty because each row in  the
  39.          buffer  must  be  allocated and freed individually.  Therefore,
  40.          use it only if you  need  to.   Specifically,  the  application
  41.          should only turn the DBBUFFER option on if it calls dbgetrow().
  42.          Note  that  row  buffering  has  nothing  to  do  with  network
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                 dbgetrow
  47.   ______________________________________________________________________
  48.          buffering and is a completely independent issue.
  49.  
  50.        o When row buffering is not enabled,  the  application  processes
  51.          each  row  as it is read from the SQL Server, by calling dbnex-
  52.          trow() repeatedly until  it  returns  NO_MORE_ROWS.   When  row
  53.          buffering  is  enabled,  the  application can use dbgetrow() to
  54.          jump to any row that has already been read from the  SQL Server
  55.          with  dbnextrow().   Subsequent  calls to dbnextrow() cause the
  56.          application to read successive rows in the buffer.  When dbnex-
  57.          trow()  reaches  the last row in the buffer, it reads rows from
  58.          SQL Server again, if there are any.  Once the buffer  is  full,
  59.          dbnextrow()  does  not read any more rows from SQL Server until
  60.          some of the  rows  have  been  cleared  from  the  buffer  with
  61.          dbclrbuf().
  62.        o The macros DBFIRSTROW(), DBLASTROW(), and DBCURROW() are useful
  63.          in   conjunction  with  dbgetrow()  calls.   DBFIRSTROW(),  for
  64.          instance, gets the number of  the  first  row  in  the  buffer.
  65.  
  66.  
  67.  
  68.   dbgetrow                Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          Thus, the call:
  71.  
  72.          dbgetrow(dbproc, DBFIRSTROW(dbproc))
  73.  
  74.          sets the current row to the first row in the buffer.
  75.  
  76.        o For  an  example  of  row  buffering,  see  Example  4  in  the
  77.          DB-Library Reference Supplement.
  78.  
  79.   PARAMETERS:
  80.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  81.            connection for a particular front-end/SQL Server process.  It
  82.            contains all the information that DB-Library uses  to  manage
  83.            communications and data between the front end and SQL Server.
  84.        row -  The number of the row to read.  Rows are counted from  the
  85.            first  row returned from SQL Server, whose number is 1.  Note
  86.            that the first row in the row buffer is not  necessarily  the
  87.            first row returned from SQL Server.
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                 dbgetrow
  91.   ______________________________________________________________________
  92.  
  93.   RETURNS:
  94.        dbgetrow() can return four different types of values:
  95.  
  96.        o If the current row is a regular row, REG_ROW is returned.
  97.        o If the current row is a compute row, the computeid of  the  row
  98.          is  returned.   (See  dbaltbind() for information on the compu-
  99.          teid.)
  100.  
  101.        o If the row is not in the row buffer, NO_MORE_ROWS  is  returned
  102.          and the current row is left unchanged.
  103.        o If the routine was unsuccessful, FAIL is returned.
  104.  
  105.   SEE ALSO:
  106.        dbaltbind, dbbind,  dbclrbuf,  DBCURROW,  DBFIRSTROW,  DBLASTROW,
  107.        dbnextrow, options
  108.  
  109.  
  110.  
  111.