home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 for Intel / NeXTSTEP 3.2 for Intel.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbsetinterrupt.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  3.8 KB  |  150 lines
  1. .Na "dbsetinterrupt" 
  2. .Aa
  3. .Fu
  4. Call user-supplied functions to handle interrupts while waiting
  5. on a read from \*S.
  6. .Ih "function, calling to handle interrupts"
  7. .Ih "interrupt handling"
  8. .Sy
  9. .Sf "void dbsetinterrupt(dbproc, chkintr, hndlintr)"
  10. .Sp "DBPROCESS" "*dbproc"
  11. .Sp "int" "(*chkintr)()"
  12. .Sp "int" "(*hndlintr)()"
  13. .Co
  14. .Bl
  15. \*L does non-blocking reads from \*S.  While waiting for a
  16. read from \*S, it will call the
  17. .I "chkintr()"
  18. function to see if an interrupt is pending.  If there is an interrupt,
  19. .I "hndlintr()"
  20. will be called.  
  21. .I "dbsetinterrupt()"
  22. is provided so that the programmer can substitute alternative interrupt handling for
  23. the time that the host program is waiting on reads from \*S.
  24. .Bl
  25. .I "hndlintr()"
  26. must return one of the interrupt returns defined in the header file
  27. \f2sybfront.h\f1: INT_EXIT, INT_CONTINUE, or INT_CANCEL.
  28. .I "chkintr()"
  29. must return TRUE or FALSE.
  30. .Bl
  31. You can use 
  32. .I "dbcancel()"
  33. to cancel the current command batch.
  34. If you have set your own interrupt handler using
  35. .I "dbsetinterrupt(),"
  36. however,
  37. you cannot call
  38. .I "dbcancel()"
  39. in your interrupt handler, because this will cause output from \*S to
  40. \*L to become out of sync.
  41. If you want to cancel the current command batch from your interrupt handler,
  42. the interrupt handler should set a flag that you can check before
  43. the next call to 
  44. .I "dbresults()"
  45. or 
  46. .I "dbnextrow()."
  47. .Bl
  48. \f3Note for Macintosh programmers:\f1  Because \f2dbsetinterrupt()\f1 only makes sense in
  49. conjunction with \f2signal()\f1,
  50. it is valid only in MPW Tools.
  51. .Bl
  52. Here are example \f2chkintr()\f1 and \f2hndlintr()\f1 routines:
  53. .SD
  54. .in +3n
  55. .ta +4n +4n +4n +4n +4n +4n
  56. .ne 3
  57. int chkintr(dbproc)
  58. DBPROCESS       *dbproc;
  59. {
  60.     /* This routine assumes that the application sets the
  61.      * global variable "OS_interrupt_happened" upon catching 
  62.      * an interrupt via some operating system facility.
  63.      */
  64.     if (OS_interrupt_happened)
  65.     {
  66.         /* Clear the interrupt flag, for future use. */
  67.         OS_interrupt_happened = FALSE;
  68.  
  69.         return(TRUE);
  70.     }
  71.     else
  72.         return(FALSE);
  73. }
  74.  
  75. int hndlintr(dbproc)
  76. DBPROCESS       *dbproc;
  77. {
  78.     char       response[10];
  79.  
  80.     printf("\enAn interrupt has occurred. Do you want to:\en\en");
  81.     printf("\et1) Abort the program\en");
  82.     printf("\et2) Cancel the current query\en");
  83.     printf("\et3) Continue processing the current query's results\en\en");
  84.     printf("Press 1, 2, or 3, followed by the return key: ");
  85.     gets(response);
  86.  
  87.     switch(response[0])
  88.     {
  89.       case '1':
  90.         return(INT_EXIT);
  91.         break;
  92.       case '2':
  93.         return(INT_CANCEL);
  94.         break;
  95.       case '3':
  96.         return(INT_CONTINUE);
  97.         break;
  98.       default:
  99.         printf("Reponse not understood. Aborting program.\en");
  100.         return(INT_EXIT);
  101.         break;
  102.     }
  103. }
  104. .in -3n
  105. .ED
  106. .Bz
  107. .Pa
  108. .Pi dbproc
  109. A pointer to the DBPROCESS structure that provides the connection
  110. for a particular front-end/\*S process.  It contains all the
  111. information that \*L uses to manage communications and data between the
  112. front end and \*S.
  113. .Pi chkintr
  114. A pointer to the user function that \*L will call to check
  115. whether an interrupt is pending.  \*L calls it periodically while waiting
  116. on a read from \*S.  
  117. \*L calls \f2chkintr()\f1 with a single parameter\(ema pointer to the
  118. DBPROCESS from the \f2dbsetinterrupt()\f1 call.
  119. .sp 0.5v
  120. \f2chkintr()\f1 must return TRUE or FALSE.
  121. .Pi hndlintr
  122. A pointer to the user function that \*L will call if an interrupt is
  123. returned.  
  124. \*L calls \f2hndlintr()\f1 with a single parameter\(ema pointer to the
  125. DBPROCESS from the \f2dbsetinterrupt()\f1 call.
  126. .sp 0.5v
  127. \f2hndlintr()\f1 must return one of the following three values:
  128. .sp
  129. .in +17n
  130. .ta +17n
  131. .ti -17n
  132. INT_EXIT    Abort the program.
  133. (Note to UNIX programmers: \*L will not leave a core file.)
  134. .sp 0.5v
  135. .ti -17n
  136. INT_CANCEL    Cancel the current command batch.
  137. .sp 0.5v
  138. .ti -17n
  139. INT_CONTINUE    Continue to wait for the \*S response.
  140. .sp
  141. .in -17n
  142. .in -.375i
  143. .Re
  144. .br
  145. None.
  146. .Sa
  147. dbcancel,
  148. dbsetbusy,
  149. dbsetidle
  150.