home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbsetuserdata.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  6.4 KB  |  199 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89            dbsetuserdata
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbsetuserdata
  6.  
  7.   FUNCTION:
  8.        Use a DBPROCESS structure to save  a  pointer  to  user-allocated
  9.        data.
  10.  
  11.   SYNTAX:
  12.        void dbsetuserdata(dbproc, ptr)
  13.  
  14.        DBPROCESS *dbproc;
  15.        BYTE      *ptr;
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbsetuserdata           Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.   COMMENTS:
  28.  
  29.        o This routine saves, in a  DBPROCESS  structure,  a  pointer  to
  30.          user-allocated data.  The application can access the data later
  31.          with the dbgetuserdata() routine.
  32.        o dbsetuserdata() allows the application to associate  user  data
  33.          with  a  particular  DBPROCESS.   This  avoids the necessity of
  34.          using global variables for this purpose.  One use for this rou-
  35.          tine  is  to  handle  deadlock,  as shown in the example below.
  36.          This routine is particularly useful when  the  application  has
  37.          multiple DBPROCESSes.
  38.  
  39.        o The application must allocate the  data  that  ptr  points  to.
  40.          DB-Library  never  manipulates  this  data; it merely saves the
  41.          pointer to it for later use by the application.
  42.        o Here's an example of using this routine to handle  deadlock,  a
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89            dbsetuserdata
  47.   ______________________________________________________________________
  48.          situation which occurs  occasionally  in  high-volume  applica-
  49.          tions.   See  the System Administration Guide for more informa-
  50.          tion on deadlock.  This program fragment sends updates  to  the
  51.          SQL Server.  It reruns the transaction when its message handler
  52.          detects deadlock.
  53.  
  54.           ...
  55.  
  56.          /*
  57.          **  Deadlock detection:
  58.          **     In the DBPROCESS structure, we save a pointer to a DBBOOL variable.
  59.          **     The message handler sets the variable when deadlock occurs.
  60.          **     The result processing logic checks the variable and resends the
  61.          **     transaction in case of deadlock.
  62.          */
  63.  
  64.              /*
  65.  
  66.  
  67.  
  68.   dbsetuserdata           Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.              **  Allocate the space for the DBBOOL variable and save it in
  71.              **  the DBPROCESS structure.
  72.              */
  73.              dbsetuserdata(dbproc, malloc(sizeof(DBBOOL)));
  74.  
  75.              /*  Initialize the variable to FALSE.  */
  76.              *((DBBOOL *) dbgetuserdata(dbproc)) = FALSE;
  77.  
  78.           ...
  79.  
  80.              /*  Run queries and check for deadlock.  */
  81.          deadlock:
  82.              /*
  83.              **  Did we get here via deadlock?
  84.              **  If so, the server has already aborted the transaction.
  85.              **  We'll just start it again.  In a real application, the
  86.              **  deadlock handling may need to be somewhat more
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89            dbsetuserdata
  91.   ______________________________________________________________________
  92.              **  sophisticated.  For instance, you may want to keep a
  93.              **  counter and retry the transaction just a fixed number
  94.              **  of times.
  95.              */
  96.  
  97.              if (*((DBBOOL *) dbgetuserdata(dbproc)) == TRUE)
  98.              {
  99.                  /* Reset the variable to FALSE. */
  100.                  *((DBBOOL *) dbgetuserdata(dbproc)) = FALSE;
  101.              }
  102.  
  103.              /* Start the transaction.  */
  104.              dbcmd(dbproc, "begin transaction ");
  105.  
  106.              /* Run the first UPDATE command.  */
  107.              dbcmd(dbproc, "update ......");
  108.              dbsqlexec(dbproc);
  109.  
  110.  
  111.  
  112.   dbsetuserdata           Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.              while (dbresults(dbproc) != NO_MORE_RESULTS)
  115.              {
  116.                  /* application code */
  117.              }
  118.  
  119.              /*  Did we deadlock? */
  120.              if (*((DBBOOL *) dbgetuserdata(dbproc)) == TRUE)
  121.                  goto deadlock;
  122.  
  123.              /*  Run the second UPDATE command.  */
  124.              dbcmd(dbproc, "update ......");
  125.              dbsqlexec(dbproc);
  126.              while (dbresults(dbproc) != NO_MORE_RESULTS)
  127.              {
  128.                  /* application code */
  129.              }
  130.  
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89            dbsetuserdata
  135.   ______________________________________________________________________
  136.              /*  Did we deadlock? */
  137.              if (*((DBBOOL *) dbgetuserdata(dbproc)) == TRUE)
  138.                  goto deadlock;
  139.  
  140.              /*  No deadlock -- Commit the transaction.  */
  141.              dbcmd(dbproc, "commit transaction");
  142.              dbsqlexec(dbproc);
  143.              dbresults(dbproc);
  144.  
  145.           ...
  146.  
  147.          /*
  148.          **  SERVERMSGS
  149.          **  This is the server message handler.  Assume that the dbmsghandle()
  150.          **      routine installed it earlier in the program.
  151.          */
  152.          servermsgs(dbproc, msgno, msgstate, serverity, msgtext, srvname, procname, line)
  153.  
  154.  
  155.  
  156.   dbsetuserdata           Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.          DBPROCESS        *dbproc;
  159.          DBINT            msgno;
  160.          int              msgstate;
  161.          int              severity;
  162.          char             *msgtext;
  163.          char             *srvname;
  164.          char             *procname;
  165.          DBUSMALLINT      line;
  166.          {
  167.  
  168.              /*  Is this a deadlock message? */
  169.              if (msgno == 1205)
  170.              {
  171.                  /* Set the deadlock indicator. */
  172.                  *((DBBOOL *) dbsetuserdata(dbproc)) = TRUE;
  173.                  return (0);
  174.              }
  175.  
  176.  
  177.  
  178.   9                       Version 4.0 -- 5/1/89            dbsetuserdata
  179.   ______________________________________________________________________
  180.  
  181.              /*  Normal message handling code here.  */
  182.          }
  183.  
  184.  
  185.   PARAMETERS:
  186.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  187.            connection for a particular front-end/SQL Server process.  It
  188.            contains all the information that DB-Library uses  to  manage
  189.            communications and data between the front end and SQL Server.
  190.        ptr -  A generic BYTE pointer to the user's private data space.
  191.  
  192.   RETURNS:
  193.        None.
  194.  
  195.   SEE ALSO:
  196.        dbgetuserdata
  197.  
  198.  
  199.