Index Page cvpool_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       void cvpool_c ( ConstSpiceChar  * agent,
                       SpiceBoolean    * update )
#### Abstract
       Determine whether or not any of the variables that are to be watched
       and have a specified agent on their distribution list have been
       updated.
#### Required_Reading
       KERNEL
#### Keywords
       SYMBOLS
       UTILITY
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       agent      I   Name of the agent to check for notices.
       update     O   SPICETRUE if variables for agent have been updated.
#### Detailed_Input
       agent     is the name of a function or significant portion of code
                 that needs to access variables in the kernel pool.
                 Generally this agent will buffer these variables
                 internally and fetch them from the kernel pool only when
                 they are updated.
#### Detailed_Output
       update    is a logical flag that will be set to SPICETRUE if the
                 variables in the kernel pool that are required by agent
                 have been updated since the last call to cvpool_c.
#### Parameters
       See function szpool_c.
#### Exceptions
       1) If the string pointer for agent is null, the error
          SPICE(NULLPOINTER) will be signaled.

       2) If the input string haslength zero, the error SPICE(EMPTYSTRING)
          will be signaled.
#### Files
       None.
#### Particulars
       This entry point allows the calling program to determine whether or
       not variables associated with with agent have been updated.  Making
       use of this entry point in conjunction with the entry point swpool_c
       (set watch on pool variables) modules can buffer kernel pool
       variables they need and fetch values from the kernel pool only when
       variables have been updated.

       Note that the call to cvpool_c has a side effect. Two consecutive
       calls to cvpool_c with the same agent will always result in the
       update being SPICEFALSE on the second call.  In other words, if you
       imbed the following two lines of code in a piece of code

          cvpool_c ( agent, &update );
          cvpool_c ( agent, &update );

       and then test update, it will be SPICEFALSE.  The idea is that once
       a call to cvpool_c has been made, the kernel pool has performed its
       duty and notified the calling routine that one of the agent's
       variables has been updated. Consequently, on the second call to
       cvpool_c above, the kernel pool will not have any updates to report
       about any of agent's variables.

       If, on the other hand, you have code such as

          cvpool_c ( agent, &update );
          furnsh_c ( "myfile.dat"   );
          cvpool_c ( agent, &update );

       the value of update will be true if one of the variables associated
       with agent was updated by the call to furnsh_c (and that variable
       has been specified as one to watch by call a call to swpool_c).

       It should also be noted that any call to cvpool_c that occurs
       immediately after a call to swpool_c will result in update being
       returned as SPICETRUE  In other words, code such as shown below,
       will always result in the value of UPDATE as being returned
       SPICETRUE:

          swpool_c ( agent, nnames, namelen, names   );
          cvpool_c ( agent,                  &update );

       See the header for swpool_c for a full discussion of this
       feature.
#### Examples
       Suppose that you have an application subroutine, MYTASK, that
       needs to access a large data set in the kernel pool.  If this
       data could be kept in local storage and kernel pool queries
       performed only when the data in the kernel pool has been
       updated, the routine can perform much more efficiently.

       The code fragment below illustrates how you might make use of this
       feature.

          #include "SpiceUsr.h"
               .
               .
               .
          /.
          On the first call to this routine establish those variables
          that we will want to read from the kernel pool only when
          new values have been assigned.
          ./
          if ( first )
          {
             first = SPICEFALSE;
             swpool_c ( "MYTASK", nnames, namelen, names );
          }

          /.
          If any of the variables has been updated, fetch them from the
          kernel pool.
          ./

          cvpool_c ( "MYTASK", &update );

          if ( update )
          {
             for ( i = 0;  i < NVAR;  i++ )
             {
                gdpool_c( MYTASK_VAR[i], 1, NMAX, n[i], val[i], &found[i] );
             }
          }
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman   (JPL)
       W.L. Taber     (JPL)
#### Version
       -CSPICE Version 1.0.1, 14-AUG-2006   (EDW)

          Replace mention of ldpool_c with furnsh_c.

       -CSPICE Version 1.0.0, 05-JUN-1999 (NJB) (WLT)
#### Index_Entries
       Check the kernel pool for updated variables
#### Link to routine cvpool_c source file cvpool_c.c

    Wed Jun  9 13:05:20 2010