Index Page
kplfrm_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

   void kplfrm_c ( SpiceInt      frmcls,
                   SpiceCell   * idset   ) 

Abstract

 
   Return a SPICE set containing the frame IDs of all reference 
   frames of a given class having specifications in the kernel pool. 
 

Required_Reading

 
   CELLS 
   FRAMES 
   KERNEL 
   NAIF_IDS 
   SETS 
 

Keywords

 
   FRAME 
   SET 
   UTILITY 
 

Brief_I/O

 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   frmcls     I   Frame class. 
   idset      O   Set of ID codes of frames of the specified class. 
 

Detailed_Input

 
   frmcls         is an integer code specifying the frame class or
                  classes for which frame ID codes are requested. The
                  applicable reference frames are those having
                  specifications present in the kernel pool.
 
                  `frmcls' may designate a single class or "all 
                  classes." 
 
                  The headerfile SpiceFrm.h declares parameters 
                  identifying frame classes. The supported values 
                  and corresponding meanings of `frmcls' are 
 
                     Parameter          Value    Meaning 
                     ================   =====    ================= 
                     SPICE_FRMTYP_ALL     -1     All frame classes 
                                                 specified in the  
                                                 kernel pool. Class 1 
                                                 is not included. 
 
                     SPICE_FRMTYP_INERTL   1     Built-in inertial. 
                                                 No frames will be  
                                                 returned in the  
                                                 output set. 
                                              
                     SPICE_FRMTYP_PCK      2     PCK-based frame.
 
                     SPICE_FRMTYP_CK       3     CK-based frame.
 
                     SPICE_FRMTYP_TK       4     Fixed rotational 
                                                 offset ("text 
                                                 kernel") frame.
 
                     SPICE_FRMTYP_DYN      5     Dynamic frame.

 

Detailed_Output

 
   idset          is a SPICE set containing the ID codes of all 
                  reference frames having specifications present in 
                  the kernel pool and belonging to the specified 
                  class or classes. 
 

Parameters

 
   See the header file SpiceFrm.h. 
 

Exceptions

 
   1)  If the input frame class argument is not defined in SpiceFrm.h,
       the error is diagnosed by a routine in the call tree of this
       routine.
 
   2)  If the size of `idset' is too small to hold the requested frame
       ID set, the error is diagnosed by a routine in the call tree of
       this routine.
 
   3)  Frames of class 1 may not be specified in the kernel pool.
       However, for the convenience of users, this routine does not
       signal an error if the input class is set to
       SPICE_FRMTYP_INERTL. In this case the output set will be empty.
 
   4)  This routine relies on the presence of just three kernel 
       variable assignments for a reference frame in order to 
       determine that that reference frame has been specified: 
 
         FRAME_<frame name>       = <ID code> 
         FRAME_<ID code>_NAME     = <frame name> 
 
      and either 
 
         FRAME_<ID code>_CLASS    = <class> 
 
      or 
 
         FRAME_<frame name>_CLASS = <class> 
 
      It is possible for the presence of an incomplete frame  
      specification to trick this routine into incorrectly  
      deciding that a frame has been specified. This routine 
      does not attempt to diagnose this problem. 
 

Files

 
   1) Reference frame specifications for frames that are not 
      built in are typically established by loading frame kernels. 
 

Particulars

 
   This routine enables SPICE-based applications to conveniently 
   find the frame ID codes of reference frames having specifications 
   present in the kernel pool. Such frame specifications are  
   introduced into the kernel pool either by loading frame kernels 
   or by means of calls to the kernel pool "put" API routines 
  
      pcpool_c 
      pdpool_c 
      pipool_c 
    
   Given a reference frame's ID code, other attributes of the 
   frame can be obtained via calls to the CSPICE APIs
 
      frmnam_c {Return a frame's name} 
      frinfo_c {Return a frame's center, class, and class ID} 
 
   This routine has a counterpart  
 
      bltfrm_c 
 
   which fetches the frame IDs of all built-in reference frames. 
    

Examples

 
   1)  Display the IDs and names of all reference frames having 
       specifications present in the kernel pool. Group the outputs 
       by frame class. Also fetch and display the entire set of IDs 
       and names using the parameter SPICE_FRMTYP_ALL. 
 
       The meta-kernel used for this example is shown below. The 
       Rosetta kernels referenced by the meta-kernel are available 
       in the path 
 
          pub/naif/ROSETTA/kernels/fk 
 
       on the NAIF server. Older, but officially archived versions 
       of these kernels are available in the path 
 
          pub/naif/pds/data/ros-e_m_a_c-spice-6-v1.0/ 
          rossp_1000/DATA/FK 
 
       The referenced PCK is available from the pck path under the 
       generic_kernels path on the same server. 
 
 
          KPL/MK 
 
          \begindata 
 
             KERNELS_TO_LOAD = ( 'pck00010.tpc' 
                                 'EARTHFIXEDITRF93.TF' 
                                 'ROS_LUTETIA_RSOC_V03.TF' 
                                 'ROS_V18.TF' 
                                 'RSSD0002.TF'            ) 
          \begintext 
 
 
       Program source code: 


          #include <stdio.h>
          #include "SpiceUsr.h"

          int main()
          {
             /.
             Local parameters 
             ./    
             #define META            "kplfrm.tm"
             #define FRNMLN          33
             #define NFRAME          1000
             #define LNSIZE          81

             /.
             Local variables 
             ./
             SPICEINT_CELL           ( idset, NFRAME );

             SpiceChar               frname  [ FRNMLN ];
             SpiceChar               outlin  [ LNSIZE ];

             SpiceInt                i;
             SpiceInt                j;

             /.
             Load kernels that contain frame specifications.
             ./
             furnsh_c ( META );

             /.
             Fetch and display the frames of each class. 
             ./
             for ( i = 1;  i <= 6;  i++ )
             {
                if ( i < 6 )
                {
                   /.
                   Fetch the frames of class i.
                   ./
                   kplfrm_c ( i, &idset );

                   sprintf ( outlin, 
                             "Number of frames of class %d: %d",
                             (int) i,
                             (int) card_c(&idset)                );
                }
                else
                {
                   /.
                   Fetch IDs of all frames specified in the kernel pool.
                   ./
                   kplfrm_c ( SPICE_FRMTYP_ALL, &idset );

                   sprintf ( outlin, 
                             "Number of frames in the kernel pool: %d",
                             (int) card_c(&idset)                     );
                }

                /.
                Display the fetched frame IDs and corresponding names. 
                ./
                printf ( "\n"
                         "%s\n"
                         "   Frame IDs and names\n",
                         outlin                     );

                for ( j = 0;  j < card_c(&idset);  j++ )
                {
                   frmnam_c ( ((SpiceInt *)idset.data)[j], FRNMLN, frname );

                   printf ( "%12.0ld   %s\n", 
                            ( (long) ((SpiceInt *)idset.data)[j] ),  frname );
                }
             }

             return ( 0 );
          }

 
       The output from the program, when the program was linked 
       against the N0064 CSPICE Toolkit, is shown below. The output 
       shown here has been abbreviated. 
 
 
          Number of frames of class 1: 0 
             Frame IDs and names 
 
          Number of frames of class 2: 3 
             Frame IDs and names 
               1000012   67P/C-G_FIXED 
               2000021   LUTETIA_FIXED 
               2002867   STEINS_FIXED 
 
          Number of frames of class 3: 7 
             Frame IDs and names 
               -226570   ROS_RPC_BOOM2 
               -226215   ROS_VIRTIS-M_SCAN 
               -226072   ROS_HGA_AZ 
               -226071   ROS_HGA_EL 
               -226025   ROS_SA-Y 
               -226015   ROS_SA+Y 
               -226000   ROS_SPACECRAFT 
 
          Number of frames of class 4: 64 
             Frame IDs and names 
              -2260021   ROS_LUTETIA 
               -226999   ROSLND_LOCAL_LEVEL 
               -226900   ROSLND_LANDER 
               -226560   ROS_RPC_BOOM1 
 
                  ... 
 
               -226030   ROS_MGA-S 
               -226020   ROS_SA-Y_ZERO 
               -226010   ROS_SA+Y_ZERO 
               1502010   HCI 
               1502301   LME2000 
               1503299   VME2000 
               1503499   MME2000 
 
          Number of frames of class 5: 19 
             Frame IDs and names 
               -226967   2867/STEINS_CSO 
               -226945   45P/H-M-P_CSO 
               -226921   21/LUTETIA_CSO 
               -226920   21/LUTETIA_CSEQ 
               -226912   67P/C-G_CSO 
               -226910   67P/C-G_CSEQ 
               1500010   HEE 
               1500299   VSO 
               1500301   LSE 
               1500399   GSE 
               1500499   MME 
               1501010   HEEQ 
               1501299   VME 
               1501301   LME 
               1501399   EME 
               1501499   MME_IAU2000 
               1502399   GSEQ 
               1502499   MSO 
               1503399   ECLIPDATE 
 
          Number of frames in the kernel pool: 93 
             Frame IDs and names 
              -2260021   ROS_LUTETIA 
               -226999   ROSLND_LOCAL_LEVEL 
               -226967   2867/STEINS_CSO 
               -226945   45P/H-M-P_CSO 
               -226921   21/LUTETIA_CSO 
 
                  ... 
 
               1503299   VME2000 
               1503399   ECLIPDATE 
               1503499   MME2000 
               2000021   LUTETIA_FIXED 
               2002867   STEINS_FIXED

 

Restrictions

 
   1) This routine will work correctly if the kernel pool 
      contains no invalid frame specifications. See the 
      description of exception 4 above. Users must ensure 
      that no invalid frame specifications are introduced 
      into the kernel pool, either by loaded kernels or 
      by means of the kernel pool "put" APIs.         
 

Literature_References

 
   None. 
 

Author_and_Institution

 
   N.J. Bachman    (JPL) 
 

Version

 
   -CSPICE Version 1.0.1, 12-JUL-2016 (EDW)

      Edit to example program to use "%d" with explicit casts
      to int for printing SpiceInts with printf.

   -CSPICE Version 1.0.0, 22-MAY-2012 (NJB)

Index_Entries

 
   fetch names of reference_frames from the kernel_pool 
 
Wed Apr  5 17:54:37 2017