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 
 
Wed Apr  5 17:54:28 2017