Procedure

     CVPOOL ( Check variable in the pool for update)

     ENTRY CVPOOL ( AGENT, UPDATE )

Abstract

     Indicate whether or not any watched kernel variables that have a
     specified agent on their notification list have been updated.

Required_Reading

     KERNEL

Keywords

     SYMBOLS
     UTILITY

Declarations

    CHARACTER*(*)         AGENT
    LOGICAL               UPDATE

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     AGENT      I   Name of the agent to check for notices.
     UPDATE     O   .TRUE. if variables for AGENT have been updated.

Detailed_Input

     AGENT    is the name of a subroutine, entry point, 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 .TRUE. if the
              variables in the kernel pool that are associated with
              AGENT have been updated since the last call to CVPOOL.

              UPDATE will be set to .TRUE. on the first call made for
              the specified agent, whether or not the associated
              variables have been updated since the agent was placed
              on their notification list, as long as the agent is
              associated with any watched variables.

Parameters

     See the umbrella subroutine POOL.

Exceptions

     None.

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 (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 has a side effect.
     Two consecutive calls to CVPOOL with the same
     AGENT will always result in the UPDATE being .FALSE.
     on the second call. In other words, if you embed
     the following two lines of code in a piece of code

        CALL CVPOOL ( AGENT, UPDATE )
        CALL CVPOOL ( AGENT, UPDATE )

     and then test UPDATE, it will be .FALSE. The idea is
     that once a call to CVPOOL 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 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

        CALL CVPOOL ( AGENT, UPDATE )
        CALL LDPOOL ( 'MYFILE.DAT'  )
        CALL CVPOOL ( AGENT, UPDATE )

     the value of UPDATE will be true if one of the variables
     associated with AGENT was updated by the call to
     LDPOOL (and that variable has been specified as one
     to watch by call a call to SWPOOL).

     It should also be noted that any call to CVPOOL that
     occurs immediately after a call to SWPOOL will result in
     UPDATE being returned as .TRUE. In other words, code
     such as shown below, will always result in the value
     of UPDATE as being returned .TRUE.

        CALL SWPOOL ( AGENT, NNAMES, NAMES  )
        CALL CVPOOL ( AGENT,         UPDATE )

     See the header for SWPOOL 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.

     C
     C     On the first call to this routine establish those variables
     C     that we will want to read from the kernel pool only when
     C     new values have been established.
     C
           IF ( FIRST ) THEN

              FIRST = .FALSE.
              HAVE  = .FALSE.

              CALL SWPOOL ( 'MYTASK', NNAMES, NAMES )

           END IF

     C
     C     If any of the variables has been updated, fetch
     C     it from the kernel pool. (Note that this also
     C     handles getting variables for the first time.)
     C     We use HAVE to indicate the fetch succeeded. If it
     C     didn't, we need to attempt the fetch on the next
     C     pass into this routine.
     C
           CALL CVPOOL ( 'MYTASK', UPDATE )

           IF (  UPDATE  .OR (.NOT. HAVE ) ) THEN

              CALL GDPOOL ( 'MYTASK_VAR_1', 1, M, N1, VALS1, FOUND(1) )
              CALL GDPOOL ( 'MYTASK_VAR_2', 1, M, N2, VALS2, FOUND(2) )
                      .
                      .
                      .
              CALL GDPOOL ( 'MYTASK_VAR_N', 1, M, NN, VALSN, FOUND(N) )

           END IF

           IF ( FAILED() ) THEN
                 .
                 .
              do something about the failure
                 .
                 .

           ELSE

              HAVE = .TRUE.

           END IF

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     W.L. Taber         (JPL)

Version

    SPICELIB Version 8.1.2, 17-AUG-2021 (JDR)

        Edited the header to comply with NAIF standard.

    SPICELIB Version 8.1.1, 30-JUN-2014 (NJB)

        Description of the output variable UPDATE now
        mentions that the initial value of .TRUE. will
        be returned after an agent is associated with
        kernel variables.

    SPICELIB Version 8.1.0, 19-MAR-2009 (NJB)

        ZZPINI call was updated for compatibility
        with new watcher system implementation.

        The code example was updated to handle kernel pool
        fetch failure.

    SPICELIB Version 8.0.0, 04-JUN-1999 (WLT)

        Added the entry points PCPOOL, PDPOOL and PIPOOL to allow
        direct insertion of data into the kernel pool without having
        to read an external file.

        Added the interface LMPOOL that allows SPICE
        programs to load text kernels directly from memory
        instead of requiring a text file.

        Added the entry point SZPOOL to return kernel pool definition
        parameters.

        Added the entry point DVPOOL to allow the removal of a variable
        from the kernel pool.

        Added the entry point GNPOOL to allow users to determine
        variables that are present in the kernel pool

    SPICELIB Version 7.0.0, 20-SEP-1995 (WLT)

        The implementation of the kernel pool was completely redone
        to improve performance in loading and fetching data. In
        addition the pool was upgraded so that variables may be
        either string or numeric valued.

    SPICELIB Version 6.0.0, 31-MAR-1992 (WLT)

        The entry points SWPOOL and CVPOOL were added.