home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbsetbusy.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  5.9 KB  |  177 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                dbsetbusy
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbsetbusy
  6.  
  7.   FUNCTION:
  8.        Call a user-supplied function when  DB-Library  is  reading  from
  9.        SQL Server.
  10.  
  11.   SYNTAX:
  12.        void dbsetbusy(dbproc, busyfunc)
  13.  
  14.        DBPROCESS *dbproc;
  15.        void      (*(*busyfunc)())();
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbsetbusy               Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.  
  27.   COMMENTS:
  28.  
  29.        o This routine  associates  a  user-supplied  function  with  the
  30.          specified  dbproc.   The  user-supplied function will automati-
  31.          cally be called whenever DB-Library is reading  or  waiting  to
  32.          read  output  from SQL Server.  For example, an application may
  33.          want to  print  a  message  whenever  SQL Server  is  accessed.
  34.          dbsetbusy() will cause the user-supplied function busyfunc() to
  35.          be called in this case.
  36.        o Similarly, dbsetidle() may also be used to  associate  a  user-
  37.          supplied  function, idlefunc(), with a dbproc.  idlefunc() will
  38.          automatically be called whenever DB-Library has finished  read-
  39.          ing output from SQL Server.
  40.  
  41.        o The server sends result data to the application in  packets  of
  42.          512  bytes.   (The final packet in a set of results may be less
  43.          than 512 bytes.) DB-Library calls busyfunc() at  the  beginning
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                dbsetbusy
  47.   ______________________________________________________________________
  48.          of each packet and idlefunc() at the end of  each  packet.   If
  49.          the  output  from the server spans multiple packets, busyfunc()
  50.          and idlefunc() will be called multiple times.
  51.  
  52.        o Here's an example of installing  and  defining  busyfunc()  and
  53.          idlefunc():
  54.  
  55.             int     (*busyfunc())();        /* busyfunc is a function which returns
  56.                                              * a pointer to a function which returns
  57.                                              * an integer.
  58.                                              */
  59.             void    idlefunc();
  60.  
  61.             int     counterfunc();
  62.                 ...
  63.  
  64.             main()
  65.             {
  66.  
  67.  
  68.   dbsetbusy               Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.                 DBPROCESS       *dbproc;
  71.                 ...
  72.  
  73.                 dbproc = dbopen(login, NULL);
  74.  
  75.                 /* Now that we have a DBPROCESS, install the busy-function
  76.                  * and the idle-function.
  77.                  */
  78.                 dbsetbusy(dbproc, busyfunc);
  79.                 dbsetidle(dbproc, idlefunc);
  80.  
  81.                 dbcmd(dbproc, "select * from sysdatabases");
  82.                 dbcmd(dbproc, " select * from sysobjects");
  83.                 dbsqlexec(dbproc);
  84.  
  85.                 /* DB-Library calls busyfunc() for the first time during
  86.                  * dbsqlexec(). Depending on the size of the results,
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                dbsetbusy
  91.   ______________________________________________________________________
  92.                  * it may call busyfunc() again during processing of
  93.                  * the results. */
  94.  
  95.                 while (dbresults(dbproc) != NO_MORE_RESULTS)
  96.                     dbprrow(dbproc);
  97.  
  98.                 /* DB-Library calls idlefunc() each time a packet of results
  99.                  * has been received. Depending on the size of the results,
  100.                  * it may call idlefunc() multiple times during processing of
  101.                    the results. */
  102.                 ...
  103.             }
  104.  
  105.             int (*busyfunc(dbproc))()
  106.             DBPROCESS   *dbproc;
  107.             {
  108.                 printf("Waiting for data...\n");
  109.  
  110.  
  111.  
  112.   dbsetbusy               Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.  
  115.                 /* busyfunc returns a pointer to a routine which returns an integer. */
  116.                 return(counterfunc);
  117.             }
  118.  
  119.             void idlefunc(procptr, dbproc)
  120.             int             (*procptr)();   /* idlefunc's first parameter is a pointer
  121.                                              * to a routine which returns an integer.
  122.                                              * This is the same pointer that busyfunc
  123.                                              * returns.
  124.                                              */
  125.             DBPROCESS       *dbproc;
  126.             {
  127.                 int count;
  128.  
  129.                 printf("Data is ready.\n");
  130.                 count = (*procptr)();
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89                dbsetbusy
  135.   ______________________________________________________________________
  136.  
  137.                 printf
  138.                  ("Counterfunc has been called %d %s.\n",
  139.                   count, (count == 1 ? "time" : "times"));
  140.  
  141.             }
  142.  
  143.             int counterfunc()
  144.             {
  145.                 static int      counter = 0;
  146.  
  147.                 return(++counter);
  148.             }
  149.  
  150.  
  151.   PARAMETERS:
  152.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  153.  
  154.  
  155.  
  156.   dbsetbusy               Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.            connection for a particular front-end/SQL Server process.  It
  159.            contains  all  the information that DB-Library uses to manage
  160.            communications and data between the front end and SQL Server.
  161.        busyfunc -  The user-supplied function that DB-Library will  call
  162.            whenever it accesses SQL Server.  DB-Library calls busyfunc()
  163.            with a single parameter-a pointer to the DBPROCESS  from  the
  164.            dbsetbusy() call.
  165.  
  166.            busyfunc() returns a pointer to a function  that  returns  an
  167.            integer.
  168.  
  169.   RETURNS:
  170.        None.
  171.  
  172.   SEE ALSO:
  173.        dbsetidle
  174.  
  175.  
  176.  
  177.