home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbsetinterrupt.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  5.8 KB  |  177 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89           dbsetinterrupt
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbsetinterrupt
  6.  
  7.   FUNCTION:
  8.        Call user-supplied functions to handle interrupts  while  waiting
  9.        on a read from SQL Server.
  10.  
  11.   SYNTAX:
  12.        void dbsetinterrupt(dbproc, chkintr, hndlintr)
  13.  
  14.        DBPROCESS *dbproc;
  15.        int       (*chkintr)();
  16.        int       (*hndlintr)();
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbsetinterrupt          Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.   COMMENTS:
  28.  
  29.        o DB-Library does  non-blocking  reads  from  SQL Server.   While
  30.          waiting  for a read from SQL Server, it will call the chkintr()
  31.          function to see if an interrupt is pending.   If  there  is  an
  32.          interrupt,  hndlintr() will be called. dbsetinterrupt() is pro-
  33.          vided so that the programmer can substitute alternative  inter-
  34.          rupt  handling for the time that the host program is waiting on
  35.          reads from SQL Server.
  36.        o hndlintr() must return one of the interrupt returns defined  in
  37.          the   header   file   sybfront.h:  INT_EXIT,  INT_CONTINUE,  or
  38.          INT_CANCEL.  chkintr() must return TRUE or FALSE.
  39.  
  40.        o You can use dbcancel() to cancel the current command batch.  If
  41.          you have set your own interrupt handler using dbsetinterrupt(),
  42.          however, you cannot call dbcancel() in your interrupt  handler,
  43.          because this will cause output from SQL Server to DB-Library to
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89           dbsetinterrupt
  47.   ______________________________________________________________________
  48.          become out of sync.  If you want to cancel the current  command
  49.          batch from your interrupt handler, the interrupt handler should
  50.          set a  flag  that  you  can  check  before  the  next  call  to
  51.          dbresults() or dbnextrow().
  52.  
  53.  
  54.  
  55.  
  56.        o Here are example chkintr() and hndlintr() routines:
  57.  
  58.             int chkintr(dbproc)
  59.             DBPROCESS       *dbproc;
  60.             {
  61.                 /* This routine assumes that the application sets the
  62.                  * global variable "OS_interrupt_happened" upon catching
  63.                  * an interrupt via some operating system facility.
  64.                  */
  65.  
  66.  
  67.  
  68.   dbsetinterrupt          Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.                 if (OS_interrupt_happened)
  71.                 {
  72.                     /* Clear the interrupt flag, for future use. */
  73.                     OS_interrupt_happened = FALSE;
  74.  
  75.                     return(TRUE);
  76.                 }
  77.                 else
  78.                     return(FALSE);
  79.             }
  80.  
  81.             int hndlintr(dbproc)
  82.             DBPROCESS       *dbproc;
  83.             {
  84.                 char       response[10];
  85.  
  86.                 printf("\nAn interrupt has occurred. Do you want to:\n\n");
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89           dbsetinterrupt
  91.   ______________________________________________________________________
  92.                 printf("\t1) Abort the program\n");
  93.                 printf("\t2) Cancel the current query\n");
  94.                 printf("\t3) Continue processing the current query's results\n\n");
  95.                 printf("Press 1, 2, or 3, followed by the return key: ");
  96.                 gets(response);
  97.  
  98.                 switch(response[0])
  99.                 {
  100.                   case '1':
  101.                     return(INT_EXIT);
  102.                     break;
  103.                   case '2':
  104.                     return(INT_CANCEL);
  105.                     break;
  106.                   case '3':
  107.                     return(INT_CONTINUE);
  108.                     break;
  109.  
  110.  
  111.  
  112.   dbsetinterrupt          Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.                   default:
  115.                     printf("Reponse not understood. Aborting program.\n");
  116.                     return(INT_EXIT);
  117.                     break;
  118.                 }
  119.             }
  120.  
  121.  
  122.   PARAMETERS:
  123.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  124.            connection for a particular front-end/SQL Server process.  It
  125.            contains all the information that DB-Library uses  to  manage
  126.            communications and data between the front end and SQL Server.
  127.        chkintr -  A pointer to the user function  that  DB-Library  will
  128.            call  to  check  whether an interrupt is pending.  DB-Library
  129.            calls  it  periodically  while  waiting  on   a   read   from
  130.            SQL Server.   DB-Library   calls   chkintr()  with  a  single
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89           dbsetinterrupt
  135.   ______________________________________________________________________
  136.            parameter-a pointer to the  DBPROCESS  from  the  dbsetinter-
  137.            rupt() call.
  138.  
  139.            chkintr() must return TRUE or FALSE.
  140.        hndlintr -  A pointer to the user function that  DB-Library  will
  141.            call if an interrupt is returned. DB-Library calls hndlintr()
  142.            with a single parameter-a pointer to the DBPROCESS  from  the
  143.            dbsetinterrupt() call.
  144.            hndlintr() must return one of the following three values:
  145.  
  146.            INT_EXIT         Abort the program.  (Note to  UNIX  program-
  147.                             mers:  DB-Library  will  not  leave  a  core
  148.                             file.)
  149.  
  150.            INT_CANCEL       Cancel the current command batch.
  151.            INT_CONTINUE     Continue  to   wait   for   the   SQL Server
  152.                             response.
  153.  
  154.  
  155.  
  156.   dbsetinterrupt          Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.  
  159.   RETURNS:
  160.        None.
  161.  
  162.   SEE ALSO:
  163.        dbcancel, dbsetbusy, dbsetidle
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.