home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbsetbusy.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  3.7 KB  |  150 lines
  1. .Na "dbsetbusy" 
  2. .Aa
  3. .Fu
  4. Call a user-supplied function when \*L is reading from \*S.
  5. .Ih "function, calling when \*L is reading from \*S"
  6. .Sy
  7. .Sf "void dbsetbusy(dbproc, busyfunc)"
  8. .Sp "DBPROCESS" "*dbproc"
  9. .mc |
  10. .Sp "void" "(*(*busyfunc)())()"
  11. .Co
  12. .mc
  13. .Bl
  14. This routine associates a user-supplied function with the
  15. specified \f2dbproc\f1.
  16. The user-supplied function will automatically be called whenever
  17. \*L is reading or waiting to read output from \*S.
  18. For example, an application may want to print a message 
  19. whenever \*S is accessed.
  20. .I "dbsetbusy()"
  21. will cause the user-supplied function
  22. .I "busyfunc()"
  23. to be called in this case.
  24. .Bl
  25. Similarly,
  26. .I "dbsetidle()"
  27. may also be used to associate a user-supplied function, \f2idlefunc()\f1, with a
  28. .I "dbproc."
  29. \f2idlefunc()\f1 will automatically be 
  30. called whenever \*L has finished reading
  31. output from \*S.
  32. .Bl
  33. The server sends result data to the application in packets of 512 bytes.
  34. (The final packet in a set of results may be less than 512 bytes.)
  35. \*L calls \f2busyfunc()\f1 at the beginning of
  36. each packet and \f2idlefunc()\f1 at
  37. the end of each packet.
  38. If the output from the server spans multiple packets,
  39. \f2busyfunc()\f1 and \f2idlefunc()\f1 will be called
  40. multiple times.
  41. .mc |
  42. .Bl
  43. Here's an example of
  44. installing and defining \f2busyfunc()\f1 and \f2idlefunc()\f1:
  45. .SD
  46. .in +3n
  47. .ta +4n +4n +4n +4n +4n +4n
  48. .ne 3
  49. int     (*busyfunc())();        /* busyfunc is a function which returns
  50.                                  * a pointer to a function which returns
  51.                                  * an integer.
  52.                                  */
  53. void    idlefunc();
  54.  
  55. int     counterfunc();
  56.     ...
  57.  
  58. main()
  59. {
  60.     DBPROCESS       *dbproc;
  61.     ...
  62.  
  63.     dbproc = dbopen(login, NULL);
  64.  
  65.     /* Now that we have a DBPROCESS, install the busy-function
  66.      * and the idle-function.
  67.      */
  68.     dbsetbusy(dbproc, busyfunc);
  69.     dbsetidle(dbproc, idlefunc);
  70.  
  71.     dbcmd(dbproc, "select * from sysdatabases");
  72.     dbcmd(dbproc, " select * from sysobjects");
  73.     dbsqlexec(dbproc);
  74.  
  75.     /* DB-Library calls busyfunc() for the first time during
  76.      * dbsqlexec(). Depending on the size of the results,
  77.      * it may call busyfunc() again during processing of
  78.      * the results. */
  79.  
  80.     while (dbresults(dbproc) != NO_MORE_RESULTS)
  81.         dbprrow(dbproc);
  82.  
  83.     /* DB-Library calls idlefunc() each time a packet of results 
  84.      * has been received. Depending on the size of the results,
  85.      * it may call idlefunc() multiple times during processing of
  86.        the results. */
  87.     ...
  88. }
  89.  
  90. int (*busyfunc(dbproc))()
  91. DBPROCESS    *dbproc;
  92. {
  93.     printf("Waiting for data...\en");
  94.  
  95.     /* busyfunc returns a pointer to a routine which returns an integer. */
  96.     return(counterfunc);
  97. }
  98.  
  99. void idlefunc(procptr, dbproc)
  100. int             (*procptr)();   /* idlefunc's first parameter is a pointer
  101.                                  * to a routine which returns an integer.
  102.                                  * This is the same pointer that busyfunc
  103.                                  * returns.
  104.                                  */
  105. DBPROCESS       *dbproc;
  106. {
  107.     int count;
  108.  
  109.     printf("Data is ready.\en");
  110.     count = (*procptr)();
  111.  
  112.     printf
  113.      ("Counterfunc has been called %d %s.\en",
  114.       count, (count == 1 ? "time" : "times"));
  115.  
  116. }
  117.  
  118. int counterfunc()
  119. {
  120.     static int      counter = 0;
  121.  
  122.     return(++counter);
  123. }
  124. .in -3n 
  125. .ED
  126. .mc
  127. .Bz
  128. .Pa
  129. .Pi dbproc
  130. A pointer to the DBPROCESS structure that provides the connection
  131. for a particular front-end/\*S process.  It contains all the
  132. information that \*L 
  133. uses to manage communications and data between the
  134. front end and \*S.
  135. .mc |
  136. .Pi busyfunc
  137. The user-supplied function that \*L will call whenever
  138. it accesses \*S.
  139. \*L calls \f2busyfunc()\f1 with a single parameter\(ema pointer to the
  140. DBPROCESS from the \f2dbsetbusy()\f1 call.
  141. .sp
  142. \f2busyfunc()\f1 returns a pointer to a function that returns an integer.
  143. .in -.375i
  144. .Re
  145. .mc
  146. .br
  147. None.
  148. .Sa
  149. dbsetidle
  150.