Index of Functions: A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 
Index Page
cspice_badkpv

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


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

I/O


   Given:

      caller   the scalar string name of the routine calling this routine to
               check correctness of kernel pool variables.

               help, caller
                  STRING = Scalar

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

               help, name
                  STRING = Scalar

      comp     the scalar character comparison operator to use when comparing
               the number of components of the kernel pool variable specified
               by `name' with the integer `size'.

               help, comp
                  STRING = Scalar

               If `dim' is the actual size of the kernel pool variable then
               cspice_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     a scalar integer to compare with the actual number of components
               of the kernel pool variable specified by `name'.

               help, size
                  LONG = Scalar

      divby    a scalar integer that is one of the factors of the actual
               dimension of the specified kernel pool variable.

               help, divby
                  LONG = Scalar

               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     a scalar character describing the kernel pool variable's
               expected type.

               help, type
                  STRING = Scalar

               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.

   the call:

      cspice_badkpv, caller, name, comp, size, divby, type

   returns:

      None.

      The procedure does not return a value. The call signals a SPICE error
      if the kernel pool variable lacks the described properties, otherwise
      the call has not effect.

Parameters


   None.

Examples


   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   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 behaviour 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.


      PRO badkpv_ex1

         ;;
         ;; Local parameters.
         ;;
         CALLER =   'BADKPV_EX1'

         ;;
         ;; Load the test kernel.
         ;;
         cspice_furnsh, 'badkpv_ex1.tpc'

         ;;
         ;; Create an error handler.
         ;;
         catch, err

         ;;
         ;; Assume that we need some data for body 399 and we expect
         ;; there to be an even number of items available and at
         ;; least 4 such items. Moreover we expect these items to be
         ;; numeric. Note that the variable assignments below are
         ;; present only to assist in understanding the calls to
         ;; cspice_badkpv.
         ;;
         name   = 'BODY_399_DATA'
         comp   = '=>'
         size   =  4L
         divby  =  2L
         type   = 'N'

         ;;
         ;; Wrap the call, providing an output message on error.
         ;;
         if err eq 0 then begin

            ;;
            ;; Execute the call. If an error occurs, the first statement
            ;; after "catch, err" executes.
            ;;
            cspice_badkpv, CALLER, name, comp, size, divby, type
            print, 'Expected form of variable ', name,                       $
                   ' found in kernel pool.'
            print

         endif else begin

            ;;
            ;; cspice_badkpv signaled an error. Output the error message.
            ;;
            print, !Error_State.Msg

         endelse

         ;;
         ;; Cancel the error handler.
         ;;
         catch, /cancel

         ;;
         ;; Perform another run in the same manner as above. Create an error
         ;; handler respond if an error signals.
         ;;
         catch, err

         ;;
         ;; In addition we need the names given to these items.
         ;; Improperly indicate the array has type numeric.
         ;;
         name   = 'BODY_399_NAMES'
         comp   = '=>'
         size   =  4L
         divby  =  1L
         type   = 'N'

         ;;
         ;; Wrap the call, providing an output message on error.
         ;;
         if err eq 0 then begin

            ;;
            ;; Execute the call. If an error occurs, the first statement
            ;; after "catch, err" executes.
            ;;
            cspice_badkpv, CALLER, name, comp, size, divby, type
            print, 'Expected form of variable ', name,                       $
                   ' found in kernel pool.'
            print

         endif else begin

            ;;
            ;; cspice_badkpv signaled an error. Output the error message.
            ;;
            print, !Error_State.Msg

         endelse

         catch, /cancel

         ;;
         ;; It's always good form to unload kernels after use,
         ;; particularly in IDL due to data persistence.
         ;;
         cspice_unload, 'badkpv_ex1.tpc'

      END


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


      Expected form of variable BODY_399_DATA found in kernel pool.

      CSPICE_BADKPV: SPICE(BADVARIABLETYPE): [badkpv_c->BADKPV]
                       BADKPV_EX1: The kernel pool variable
                       'BODY_399_NAMES' must be of type "NUMERIC".
                       However, the current type is character.
                       (CSPICE_N0066)


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

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.

Exceptions


   1)  If the kernel pool variable specified by `name' is not present
       in the kernel pool, the error SPICE(VARIABLENOTFOUND) is
       signaled by a routine in the call tree of this routine.

   2)  If the comparison operator specified by `comp' is unrecognized,
       the error SPICE(UNKNOWNCOMPARE) is signaled by a routine in
       the call tree of this routine.

   3)  If the expected type of the kernel pool variable `type' is not
       one of the supported types, the error SPICE(INVALIDTYPE) is
       signaled by a routine in the call tree of this routine.

   4)  If the comparison of the actual size of the kernel pool
       variable with `size' is not satisfied, the error
       SPICE(BADVARIABLESIZE) is signaled by a routine in the call
       tree of this routine.

   5)  If the variable does not have the expected type, the error
       SPICE(BADVARIABLETYPE) is signaled by a routine in the call
       tree of this routine.

   6)  If any of the input arguments, `caller', `name', `comp',
       `size', `divby' or `type', is undefined, an error is signaled
       by the IDL error handling system.

   7)  If any of the input arguments, `caller', `name', `comp',
       `size', `divby' or `type', is not of the expected type, or it
       does not have the expected dimensions and size, an error is
       signaled by the Icy interface.

Files


   None.

Restrictions


   None.

Required_Reading


   ERROR.REQ
   ICY.REQ
   KERNEL.REQ

Literature_References


   None.

Author_and_Institution


   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.1.0, 05-SEP-2021 (JDR)

       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.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections, and
       completed -Particulars section.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

   -Icy Version 1.0.0, 29-AUG-2006 (EDW)

Index_Entries


   Check the properties of a kernel pool variable



Fri Dec 31 18:43:02 2021