Museum

  1                       Version 4.0 -- 5/1/89           dbsetinterrupt
  ______________________________________________________________________

  NAME:  dbsetinterrupt

  FUNCTION:
       Call user-supplied functions to handle interrupts  while  waiting
       on a read from SQL Server.

  SYNTAX:
       void dbsetinterrupt(dbproc, chkintr, hndlintr)

       DBPROCESS *dbproc;
       int       (*chkintr)();
       int       (*hndlintr)();







  dbsetinterrupt          Version 4.0 -- 5/1/89                        2
  ______________________________________________________________________

  COMMENTS:

       o DB-Library does  non-blocking  reads  from  SQL Server.   While
         waiting  for a read from SQL Server, it will call the chkintr()
         function to see if an interrupt is pending.   If  there  is  an
         interrupt,  hndlintr() will be called. dbsetinterrupt() is pro-
         vided so that the programmer can substitute alternative  inter-
         rupt  handling for the time that the host program is waiting on
         reads from SQL Server.
       o hndlintr() must return one of the interrupt returns defined  in
         the   header   file   sybfront.h:  INT_EXIT,  INT_CONTINUE,  or
         INT_CANCEL.  chkintr() must return TRUE or FALSE.

       o You can use dbcancel() to cancel the current command batch.  If
         you have set your own interrupt handler using dbsetinterrupt(),
         however, you cannot call dbcancel() in your interrupt  handler,
         because this will cause output from SQL Server to DB-Library to


  3                       Version 4.0 -- 5/1/89           dbsetinterrupt
  ______________________________________________________________________
         become out of sync.  If you want to cancel the current  command
         batch from your interrupt handler, the interrupt handler should
         set a  flag  that  you  can  check  before  the  next  call  to
         dbresults() or dbnextrow().

       o Note for Macintosh programmers:  Because dbsetinterrupt()  only
         makes  sense  in conjunction with signal(), it is valid only in
         MPW Tools.
       o Here are example chkintr() and hndlintr() routines:

            int chkintr(dbproc)
            DBPROCESS       *dbproc;
            {
                /* This routine assumes that the application sets the
                 * global variable "OS_interrupt_happened" upon catching
                 * an interrupt via some operating system facility.
                 */



  dbsetinterrupt          Version 4.0 -- 5/1/89                        4
  ______________________________________________________________________
                if (OS_interrupt_happened)
                {
                    /* Clear the interrupt flag, for future use. */
                    OS_interrupt_happened = FALSE;

                    return(TRUE);
                }
                else
                    return(FALSE);
            }

            int hndlintr(dbproc)
            DBPROCESS       *dbproc;
            {
                char       response[10];

                printf("\nAn interrupt has occurred. Do you want to:\n\n");



  5                       Version 4.0 -- 5/1/89           dbsetinterrupt
  ______________________________________________________________________
                printf("\t1) Abort the program\n");
                printf("\t2) Cancel the current query\n");
                printf("\t3) Continue processing the current query's results\n\n");
                printf("Press 1, 2, or 3, followed by the return key: ");
                gets(response);

                switch(response[0])
                {
                  case '1':
                    return(INT_EXIT);
                    break;
                  case '2':
                    return(INT_CANCEL);
                    break;
                  case '3':
                    return(INT_CONTINUE);
                    break;



  dbsetinterrupt          Version 4.0 -- 5/1/89                        6
  ______________________________________________________________________
                  default:
                    printf("Reponse not understood. Aborting program.\n");
                    return(INT_EXIT);
                    break;
                }
            }


  PARAMETERS:
       dbproc -  A pointer to the DBPROCESS structure that provides  the
           connection for a particular front-end/SQL Server process.  It
           contains all the information that DB-Library uses  to  manage
           communications and data between the front end and SQL Server.
       chkintr -  A pointer to the user function  that  DB-Library  will
           call  to  check  whether an interrupt is pending.  DB-Library
           calls  it  periodically  while  waiting  on   a   read   from
           SQL Server.   DB-Library   calls   chkintr()  with  a  single



  7                       Version 4.0 -- 5/1/89           dbsetinterrupt
  ______________________________________________________________________
           parameter-a pointer to the  DBPROCESS  from  the  dbsetinter-
           rupt() call.

           chkintr() must return TRUE or FALSE.
       hndlintr -  A pointer to the user function that  DB-Library  will
           call if an interrupt is returned. DB-Library calls hndlintr()
           with a single parameter-a pointer to the DBPROCESS  from  the
           dbsetinterrupt() call.
           hndlintr() must return one of the following three values:

           INT_EXIT         Abort the program.  (Note to  UNIX  program-
                            mers:  DB-Library  will  not  leave  a  core
                            file.)

           INT_CANCEL       Cancel the current command batch.
           INT_CONTINUE     Continue  to   wait   for   the   SQL Server
                            response.



  dbsetinterrupt          Version 4.0 -- 5/1/89                        8
  ______________________________________________________________________

  RETURNS:
       None.

  SEE ALSO:
       dbcancel, dbsetbusy, dbsetidle