Procedure

     BADKPV ( Bad Kernel Pool Variable )

     LOGICAL FUNCTION BADKPV ( CALLER, NAME,  COMP,
    .                          SIZE,   DIVBY, TYPE )

Abstract

     Determine if a kernel pool variable is present and if so
     that it has the correct size and type.

Required_Reading

     ERROR
     KERNEL

Keywords

     ERROR

Declarations

     IMPLICIT NONE

     CHARACTER*(*)         CALLER
     CHARACTER*(*)         NAME
     CHARACTER*(*)         COMP
     INTEGER               SIZE
     INTEGER               DIVBY
     CHARACTER*(*)         TYPE

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     CALLER     I   Name of the routine calling this routine.
     NAME       I   Name of a kernel pool variable.
     COMP       I   Comparison operator.
     SIZE       I   Expected size of the kernel pool variable.
     DIVBY      I   A divisor of the size of the kernel pool variable.
     TYPE       I   Expected type of the kernel pool variable.

     The function returns .FALSE. if the kernel pool variable is OK.

Detailed_Input

     CALLER   is the name of the routine calling this routine
              to check correctness of kernel pool variables.

     NAME     is the name of a kernel pool variable that the
              calling program expects to be present in the
              kernel pool.

     COMP     is the comparison operator to use when comparing
              the number of components of the kernel pool variable
              specified by NAME with the integer SIZE. If DIM is
              is the actual size of the kernel pool variable then
              BADKPV will check that the sentence

                 DIM COMP SIZE

              is a true statement. If it is not a true statement
              an error will be signaled.

              Allowed values for COMP and their meanings are:

                 '='      DIM .EQ. SIZE
                 '<'      DIM .LT. SIZE
                 '>'      DIM .GT. SIZE
                 '=>'     DIM .GE. SIZE
                 '<='     DIM .LE. SIZE

     SIZE     is an integer to compare with the actual
              number of components of the kernel pool variable
              specified by NAME.

     DIVBY    is an integer that is one of the factors of the
              actual dimension of the specified kernel pool variable.
              In other words, it is expected that DIVBY evenly
              divides the actual dimension of NAME. In those
              cases in which the factors of the dimension of NAME
              are not important, set DIVBY to 1 in the calling
              program.

     TYPE     is the expected type of the kernel pool variable.
              Recognized values are

                 'C' for character type
                 'N' for numeric type (integer and double precision)

              The case of TYPE is insignificant. If the value
              of TYPE is not one of the 2 values given above
              no check for the type of the variable will be
              performed.

Detailed_Output

     The function returns the value .FALSE. if the kernel pool
     variable has the expected properties. Otherwise the routine
     signals an error and returns the value .TRUE.

Parameters

     None.

Exceptions

     1)  If the kernel pool variable specified by NAME is not present
         in the kernel pool, the error SPICE(VARIABLENOTFOUND) is
         signaled and the routine will return the value .TRUE.

     2)  If the comparison operator specified by COMP is unrecognized,
         the error SPICE(UNKNOWNCOMPARE) is signaled and the routine
         will return the value .TRUE.

     3)  If the expected type of the kernel pool variable TYPE is not
         one of the supported types, the error SPICE(INVALIDTYPE) is
         signaled and the routine will return the value .TRUE.

     4)  If the comparison of the actual size of the kernel pool
         variable with SIZE is not satisfied, the error
         SPICE(BADVARIABLESIZE) is signaled and the routine will
         return the value .TRUE.

     5)  If the variable does not have the expected type, the error
         SPICE(BADVARIABLETYPE) is signaled and the routine will
         return the value .TRUE.

Files

     None.

Particulars

     This routine takes care of routine checking that often needs
     to be done by programs and routines that rely upon kernel
     pool variables being present and having the correct attributes.

     It checks for the presence of the kernel pool variable and
     examines the type and dimension of the variable to make sure
     they conform to the requirements of the calling routine.

Examples

     The numerical results shown for this example may differ across
     platforms. The results depend on the SPICE kernels used as
     input, the compiler and supporting libraries, and the machine
     specific arithmetic implementation.

     1) Suppose that you need to fetch a number of variables
        from the kernel pool and want to check that the requested
        items are in fact available prior to performing further
        computations. The code example shows how you might use
        this routine to handle the details of checking of
        the various items.

        Although by default the SPICE error handling system will
        report the error and halt the execution of the program, in
        this example we have decided to change this behavior to
        display the error messages and continue the execution of
        the program.

        Use the kernel shown below to define some variables related
        to the Earth.


           KPL/PCK

           File name: badkpv_ex1.tpc

           The contents of this kernel are not intended for
           real applications. Use only with this example.

           \begindata

              BODY_399_DATA  = ( 3.1416, 2.71828, 0.5, 12.0 )
              BODY_399_NAMES = ( 'PI', 'E', 'HALF', 'DOZEN' )

           \begintext

           End of constants kernel


        Example code begins here.


              PROGRAM BADKPV_EX1
              IMPLICIT NONE

        C
        C     SPICELIB functions.
        C
              LOGICAL               BADKPV
              INTEGER               RTRIM

        C
        C     Local parameters.
        C
              CHARACTER*(*)         CALLER
              PARAMETER           ( CALLER  = 'BADKPV_EX1' )

              INTEGER               KWDLEN
              PARAMETER           ( KWDLEN = 32 )

        C
        C     Local variables.
        C
              CHARACTER*2           COMP
              CHARACTER*(KWDLEN)    NAME
              CHARACTER*1           TYPE

              INTEGER               DIVBY
              INTEGER               SIZE

        C
        C     Load the test kernel.
        C
              CALL FURNSH ( 'badkpv_ex1.tpc' )

        C
        C     Change the default behavior of the SPICE error handling
        C     system to print out all messages and continue the
        C     execution of the program. We do this for demonstration
        C     purposes. Please, refrain from changing the default
        C     behavior on real applications.
        C
              CALL ERRACT ( 'SET', 'REPORT' )

        C
        C     Assume that we need some data for body 399 and we expect
        C     there to be an even number of items available and at
        C     least 4 such items. Moreover we expect these items to be
        C     numeric. Note that the variable assignments below are
        C     present only to assist in understanding the calls to
        C     BADKPV.
        C
              NAME   = 'BODY_399_DATA'
              COMP   = '=>'
              SIZE   =  4
              DIVBY  =  2
              TYPE = 'N'

              IF ( .NOT. BADKPV( CALLER, NAME,  COMP,
             .                   SIZE,   DIVBY, TYPE ) ) THEN

                 WRITE(*,'(3A)') 'Expected form of variable ',
             .                   NAME(:RTRIM(NAME)),
             .                   ' found in kernel pool.'

              END IF

        C
        C     In addition we need the names given to these items.
        C     Improperly indicate the array has type numeric.
        C
              NAME   = 'BODY_399_NAMES'
              COMP   = '=>'
              SIZE   =  4
              DIVBY  =  1
              TYPE = 'N'

              IF ( .NOT. BADKPV( CALLER, NAME,  COMP,
             .                   SIZE,   DIVBY, TYPE ) ) THEN

                 WRITE(*,'(3A)') 'Expected form of variable ',
             .                   NAME(:RTRIM(NAME)),
             .                   ' found in kernel pool.'

              END IF

        C
        C     Change the behavior of the SPICE error handling to
        C     its default.
        C
              CALL ERRACT ( 'SET', 'DEFAULT' )


              END


        When this program was executed on a Mac/Intel/gfortran/64-bit
        platform, the output was:


        Expected form of variable BODY_399_DATA found in kernel pool.

        ============================================================***

        Toolkit version: N0066

        SPICE(BADVARIABLETYPE) --

        BADKPV_EX1: The kernel pool variable 'BODY_399_NAMES' must b***
        "NUMERIC". However, the current type is character.

        A traceback follows.  The name of the highest level module i***
        BADKPV

        ============================================================***


        Warning: incomplete output. 4 lines extended past the right
        margin of the header and have been truncated. These lines are
        marked by "***" at the end of each line.


        Note that, as expected, the error SPICE(BADVARIABLETYPE) is
        signaled by the second BADKPV call, since we have improperly
        indicated that the requested array is numeric, when actually
        it is of character type.

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     J. Diaz del Rio    (ODC Space)
     B.V. Semenov       (JPL)    
     W.L. Taber         (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 1.2.0, 05-SEP-2021 (JDR) (BVS)

        Fixed typo in long message for the case "comparison not
        favorable."

        Added exception SPICE(INVALIDTYPE) for the case of unknown
        expected kernel pool variable type.

        Edited the header to comply with NAIF standard. Added complete
        code example based on existing fragment. Added required
        readings references.

        Removed references to FURNSH and CLPOOL from the "variable
        not present" long error message. 

    SPICELIB Version 1.1.2, 22-AUG-2006 (EDW)

        Replaced references to LDPOOL with references
        to FURNSH.

    SPICELIB Version 1.1.1, 10-MAY-2000 (WLT)

        Modified the example section so that it is consistent with
        calling sequence for BADKPV.

    SPICELIB Version 1.1.0, 26-AUG-1997 (WLT)

        Moved the initial assignment of BADKPV to the lines
        prior to the check of RETURN(). This avoids returning
        without having assigned value to BADKPV.

    SPICELIB Version 1.0.0, 09-APR-1997 (WLT)