badkpv_c

Index Page badkpv_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
       SpiceBoolean badkpv_c ( ConstSpiceChar    *caller,
                               ConstSpiceChar    *name,
                               ConstSpiceChar    *comp,
                               SpiceInt           size,
                               SpiceInt           divby,
                               SpiceChar          type   )
#### Abstract
       Determine if a kernel pool variable is present and if so
       that it has the correct size and type.
#### Required_Reading
        None.
#### Keywords
        ERROR
#### 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 SPICEFALSE 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_c 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 == size
                     "<"      dim <  size
                     ">"      dim >  size
                     "=>"     dim >= size
                     "<="     dim <= 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 SPICEFALSE if the kernel pool variable
       has the expected properties.  Otherwise the routine signals
       an error and returns the value SPICETRUE.
#### Parameters
       None.
#### Exceptions
       1) If the kernel pool variable specified by name is not
          present in the kernel pool, the error
          SPICE(VARIABLENOTFOUND) will be signaled and the
          routine will return the value SPICETRUE.

       2) If the comparison operator specified by comp is unrecognized
          the error SPICE(UNKNOWNCOMPARE) will be signaled and the
          routine will return the value SPICETRUE.

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

       4) If the variable does not have the expected type, the error
          SPICE(BADVARIABLETYPE) will be signaled and the routine
          will return the value SPICETRUE.

       5) If any input string pointers are null, the error
          SPICE(NULLPOINTER) will be signaled.

       6) If any input strings have length zero, the error
          SPICE(EMPTYSTRING) will be signaled.
#### 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
       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 following shows how you might use
       this routine to handle the details of checking of
       the various items.

             caller  == "MYROUTINE"

          We need some data for body 399 and we expect there to
          be an even number of items available.  Moreover we
          expect these items to be numeric.

             name  == "BODY_399_DATA"
             comp  == ">"
             size  ==  1
             divby ==  2
             type  == 'N'

          In addition we need the units associated with this data.
          We expect the units to be character and that the number
          of components is 1.

             name  == "BODY_399_DATAUNIT";
             comp  == "="
             size  == 1
             divby == 1
             type  == 'C'

          if (   badkpv_c( caller, "BODY_399_DATA",      ">", 1, 2, 'N' )
              || badkpv_c( caller, "BODY_399_DATAUNITS", "=", 1, 1, 'C' ) )
          {
             chkout_c ( "MYROUTINE" );
             return;
          }
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       W.L. Taber      (JPL)
       N.J. Bachman    (JPL)
#### Version
       -CSPICE Version 1.0.0, 07-JUL-2000 (WLT) (NJB)
#### Index_Entries
       Check the properties of a kernel pool variable
#### Link to routine badkpv_c source file badkpv_c.c

    Thu Apr 16 08:57:22 2009