home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbqual.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  8.6 KB  |  221 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                   dbqual
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbqual
  6.  
  7.   FUNCTION:
  8.        Return a pointer to a WHERE clause suitable for use  in  updating
  9.        the current row in a browsable table.
  10.  
  11.   SYNTAX:
  12.        char *dbqual(dbproc, tabnum, tabname)
  13.  
  14.        DBPROCESS *dbproc;
  15.        int       tabnum;
  16.        char      *tabname;
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbqual                  Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.   COMMENTS:
  28.  
  29.        o dbqual() is one of the DB-Library browse  mode  routines.   See
  30.          the Introduction for a detailed discussion of browse mode.
  31.        o dbqual() provides a WHERE clause that the application  can  use
  32.          to update a single row in a browsable table.  Columns from this
  33.          row must have previously been retrieved  into  the  application
  34.          through  a  browse-mode  SELECT query (i.e., a SELECT that ends
  35.          with the key words FOR BROWSE).
  36.  
  37.          The WHERE clause produced by dbqual() begins with  the  keyword
  38.          WHERE  and  contains  references  to the row's unique index and
  39.          timestamp column.  The application  simply  appends  the  WHERE
  40.          clause  to  an  UPDATE or DELETE statement; it does not need to
  41.          examine it or manipulate it in any way.
  42.          The timestamp column indicates the time that the particular row
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                   dbqual
  47.   ______________________________________________________________________
  48.          was last updated.  An update on a browsable table will fail  if
  49.          the  timestamp column in the dbqual()-generated WHERE clause is
  50.          different from the timestamp column in the table.  Such a  con-
  51.          dition,  which provokes SQL Server error message 532, indicates
  52.          that another user updated the row between the time this  appli-
  53.          cation selected it for browsing and the time it tried to update
  54.          it.  The application itself must provide the logic for handling
  55.          the update failure.  The following program fragment illustrates
  56.          one approach:
  57.  
  58.          /* This code fragment illustrates a technique for handling the case where
  59.           * a browse-mode update fails because the row has already been updated
  60.           * by another user. In this example, we simply retrieve the entire row
  61.           * again, allow the user to examine and modify it, and try the update
  62.           * again.
  63.           *
  64.           * Note that "q_dbproc" is the DBPROCESS used to query the database, and
  65.  
  66.  
  67.  
  68.   dbqual                  Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.           * "u_dbproc" is the DBPROCESS used to update the database.
  71.           */
  72.  
  73.              /* First, find out which employee record the user wants to update. */
  74.              employee_id = which_employee();
  75.  
  76.              while (1)
  77.              {
  78.                  /* Retrieve that employee record from the database. We'll
  79.                   * assume that "empid" is a unique index, so this query will
  80.                   * return only one row.
  81.                   */
  82.                  dbfcmd
  83.                   (q_dbproc,
  84.                    "select * from employees where empid = %d for browse",
  85.                    employee_id);
  86.                  dbsqlexec(q_dbproc);
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                   dbqual
  91.   ______________________________________________________________________
  92.                  dbresults(q_dbproc);
  93.                  dbnextrow(q_dbproc);
  94.  
  95.                  /* Now, let the user examine or edit the employee's
  96.                   * data, first placing the data into program variables.
  97.                   */
  98.                  extract_employee_data(q_dbproc, employee_struct);
  99.                  examine_and_edit(employee_struct, &edit_flag);
  100.  
  101.                  if (edit_flag == FALSE)
  102.                  {
  103.                      /* The user didn't edit this record,
  104.                       * so we're done.
  105.                       */
  106.                      break;
  107.                  }
  108.                  else
  109.  
  110.  
  111.  
  112.   dbqual                  Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.                  {
  115.                      /* The user edited this record, so we'll use the edited
  116.                       * data to update the corresponding row in the database.
  117.                       */
  118.                      qualptr = dbqual(q_dbproc, -1, "employees");
  119.                      dbcmd(u_dbproc, "update employees");
  120.                      dbfcmd
  121.                       (u_dbproc,
  122.                        " set address = '%s', salary = %d %s",
  123.                        employee_struct->address, employee_struct->salary,
  124.                        qualptr);
  125.                      dbfreequal(qualptr);
  126.                      if ((dbsqlexec(u_dbproc) == FAIL)
  127.                          || (dbresults(u_dbproc) == FAIL))
  128.                      {
  129.                          /* Our update failed. In a real program, it
  130.                           * would be necessary to examine the messages
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89                   dbqual
  135.   ______________________________________________________________________
  136.                           * returned from the SQL Server to determine
  137.                           * why it failed.  In this example, we'll
  138.                           * assume that the update failed because
  139.                           * someone else has already updated this
  140.                           * row, thereby changing the timestamp.
  141.                           *
  142.                           * To cope with this situation, we'll just
  143.                           * repeat the loop, retrieving the changed
  144.                           * row for our user to examine and edit.
  145.                           * This will give our user the opportunity
  146.                           * to decide whether to overwrite the change
  147.                           * made by the other user.
  148.                           */
  149.                          continue;
  150.                      }
  151.                      else
  152.                      {
  153.  
  154.  
  155.  
  156.   dbqual                  Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.                          /* The update succeeded, so we're done. */
  159.                          break;
  160.                      }
  161.                  }
  162.              }
  163.  
  164.  
  165.        o dbqual() can only construct WHERE clauses for browsable tables.
  166.          You  can  use  dbtabbrowse()  to  determine  whether a table is
  167.          browsable.
  168.        o dbqual() is usually called after dbnextrow().
  169.  
  170.        o For a complete example that uses dbqual() to perform  a  browse
  171.          mode  update, see Example 6 in the DB-Library Reference Supple-
  172.          ment.
  173.  
  174.   PARAMETERS:
  175.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  176.  
  177.  
  178.   9                       Version 4.0 -- 5/1/89                   dbqual
  179.   ______________________________________________________________________
  180.            connection for a particular front-end/SQL Server process.  It
  181.            contains  all  the information that DB-Library uses to manage
  182.            communications and data between the front end and SQL Server.
  183.        tabnum -  The number of the table of interest,  as  specified  in
  184.            the  SELECT  statement's FROM clause.  Table numbers start at
  185.            1.  If tabnum is -1, the tabname parameter will  be  used  to
  186.            identify the table.
  187.        tabname -  A pointer to  the  null-terminated  name  of  a  table
  188.            specified  in  the SELECT statement's FROM clause. If tabname
  189.            is NULL, the tabnum parameter will be used  to  identify  the
  190.            table.
  191.  
  192.   RETURNS:
  193.        A pointer to a null-terminated WHERE clause for the  current  row
  194.        in the specified table. This buffer is dynamically allocated, and
  195.        it  is  the  application's  responsibility   to   free   it   via
  196.        dbfreequal().
  197.  
  198.  
  199.  
  200.   dbqual                  Version 4.0 -- 5/1/89                       10
  201.   ______________________________________________________________________
  202.        dbqual() will return a NULL pointer if the specified table is not
  203.        browsable.   For a table to be "browsable," it must have a unique
  204.        index and a timestamp column.
  205.  
  206.        dbqual() will also return a NULL pointer if the preceding  SELECT
  207.        did not include the FOR BROWSE option.
  208.  
  209.   SEE ALSO:
  210.        dbcolbrowse, dbcolsource,  dbfreequal,  dbtabbrowse,  dbtabcount,
  211.        dbtabname, dbtabsource, dbtsnewlen, dbtsnewval, dbtsput
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.