home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbadata.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  5.8 KB  |  155 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                  dbadata
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbadata
  6.  
  7.   FUNCTION:
  8.        Return a pointer to the data for a compute column.
  9.  
  10.   SYNTAX:
  11.        BYTE *dbadata(dbproc, computeid, column)
  12.  
  13.        DBPROCESS *dbproc;
  14.        int       computeid;
  15.        int       column;
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbadata                 Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.   COMMENTS:
  28.  
  29.        o After each call to dbnextrow(), you can  use  this  routine  to
  30.          return  a pointer to the data for a particular column in a com-
  31.          pute row.  The  data  is  not  null-terminated.   You  can  use
  32.          dbadlen() to get the length of the data.
  33.        o When a column of integer data is summed or averaged, SQL Server
  34.          always  returns a 4-byte integer, regardless of the size of the
  35.          column. Therefore, be sure that the variable which is  to  con-
  36.          tain the result from such a compute is declared as DBINT.
  37.  
  38.        o Here's a short program fragment which illustrates  the  use  of
  39.          dbadata():
  40.  
  41.          DBPROCESS       *dbproc;
  42.          int             rowinfo;
  43.          DBINT           sum;
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                  dbadata
  47.   ______________________________________________________________________
  48.  
  49.          /* first, put the commands into the command buffer */
  50.          dbcmd(dbproc, "select db_name(dbid), dbid, size from sysusages");
  51.          dbcmd(dbproc, " order by dbid");
  52.          dbcmd(dbproc, " compute sum(size) by dbid");
  53.  
  54.          /* send the commands to SQL Server and start execution */
  55.          dbsqlexec(dbproc);
  56.  
  57.          /* process the command */
  58.          dbresults(dbproc);
  59.  
  60.          /* examine the results of the COMPUTE clause */
  61.          while((rowinfo = dbnextrow(dbproc)) != NO_MORE_ROWS)
  62.          {
  63.              if (rowinfo == REG_ROW)
  64.                  printf("regular row returned.\n");
  65.  
  66.  
  67.  
  68.   dbadata                 Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.              else
  71.              {
  72.                  /* This row is the result of a COMPUTE clause, and
  73.                   * "rowinfo" is the computeid of this COMPUTE clause.
  74.                   */
  75.  
  76.                  sum = *(DBINT *)(dbadata(dbproc, rowinfo, 1));
  77.                  printf("sum = %ld\n", sum);
  78.              }
  79.          }
  80.  
  81.  
  82.        o The function dbaltbind() automatically binds  compute  data  to
  83.          your  program  variables.   It  does a copy of the data, but is
  84.          often easier to use than dbadata().  Furthermore, it includes a
  85.          convenient  type conversion capability.  By means of this capa-
  86.          bility, the application can, among other things, easily  add  a
  87.          null  terminator  to  a  result  string  or  convert  money and
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                  dbadata
  91.   ______________________________________________________________________
  92.          datetime data to printable strings.
  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.        computeid -  The id that identifies the particular compute row of
  100.            interest.   A  SQL SELECT statement may have multiple COMPUTE
  101.            clauses, each of which returns a separate compute  row.   The
  102.            computeid  corresponding  to  the  first  COMPUTE clause in a
  103.            SELECT is 1.  The computeid is  returned  by  dbnextrow()  or
  104.            dbgetrow().
  105.        column -  The number of the column of interest.  The first column
  106.            returned  is  number 1.  Note that the order in which compute
  107.            columns are returned  is  determined  by  the  order  of  the
  108.            corresponding columns in the select-list, not by the order in
  109.  
  110.  
  111.  
  112.   dbadata                 Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.            which the compute columns  were  originally  specified.   For
  115.            example, in the following query the result of "sum(price)" is
  116.            referenced by giving column a value of 1, not 2:
  117.  
  118.                 select price, advance from titles
  119.                      compute sum(advance), sum(price)
  120.  
  121.            The relative order of compute  columns  in  the  select-list,
  122.            rather  than their absolute position, determines the value of
  123.            column.  For instance, given the following variation  of  the
  124.            previous SELECT:
  125.  
  126.                 select title_id, price, advance from titles
  127.                      compute sum(advance), sum(price)
  128.  
  129.            the column for "sum(price)" still has a value of 1 and not 2,
  130.            because  the  "title_id"  column  in the select-list is not a
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89                  dbadata
  135.   ______________________________________________________________________
  136.            compute column and therefore is ignored when determining  the
  137.            compute column's number.
  138.  
  139.   RETURNS:
  140.        A BYTE pointer to the data for a particular column in a  particu-
  141.        lar  compute.  Be sure to cast this pointer into the proper type.
  142.        A BYTE pointer to NULL is returned if there is no such column  or
  143.        compute or if the data has a null value.
  144.  
  145.        DB-Library allocates and frees  the  data  space  that  the  BYTE
  146.        pointer points to.  Do not overwrite this space.
  147.  
  148.   SEE ALSO:
  149.        dbadlen, dbaltbind,  dbaltlen,  dbalttype,  dbgetrow,  dbnextrow,
  150.        dbnumalts
  151.  
  152.  
  153.  
  154.  
  155.