Index Page boddef_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 boddef_c ( ConstSpiceChar   * name,
                       SpiceInt           code )
#### Abstract
       Define a body name/ID code pair for later translation via
       bodn2c_c or bodc2n_c.
#### Required_Reading
       NAIF_IDS
#### Keywords
       BODY
       CONVERSION
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       name       I   Common name of some body.
       code       I   Integer code for that body.
#### Detailed_Input
       name        is an arbitrary name of a body which could be
                   a planet, satellite, barycenter, spacecraft,
                   asteroid, comet, or other ephemeris object.

                   The case and positions of blanks in a name are
                   significant. bodc2n_c returns the same string
                   (case and space) most recently mapped to a code.
                   When 'name' consists of more than one word, the
                   words require separation by at least one blank.

                   The kernel sub-system stores 'name' as described in
                   the boddef_c call, but creates an equivalence class
                   based on 'name for comparisons in bodn2c_c. This class
                   ignores leading/trailing whitespace, compresses
                   interior whitespace to a single space, and ignores
                   character case.

                   The following strings belong to the same equivalence
                   class:

                           "JUPITER BARYCENTER"
                           "Jupiter Barycenter"
                           "JUPITER BARYCENTER   "
                           "JUPITER    BARYCENTER"
                           "   JUPITER BARYCENTER"

                   However, "JUPITERBARYCENTER" is distinct from
                   the names above.

                   When ignoring trailing blanks, NAME must be short
                   enough to fit into the space defined by parameter
                   MAXL.The value may be found in the C file
                   zzbodtrn.c. Due to the way in which f2c converts
                   FORTRAN code to C, you must examine the dimensions
                   assigned to the variables:

                       defnam
                       defnor
                       kernam
                       kernor

                    to obtain the MAXL value. These variables have a
                    declaration of the form:

                       static char variable_name[MAXL*array_length]

                      (note MAXL is this first value).

                   The maximum allowed length of a name is in any case
                   at least 32 characters.

       code        is the integer ID code for assignment to body 'name'.
#### Detailed_Output
       None.
#### Parameters
       None.
#### Exceptions
       1) An attempt to associate more than one code with a given name
          will cause an error to be signaled by a routine called by this
          routine.

       2) Names too long to be stored will be truncated on the right.
          Names of length not exceeding 32 characters will not be
          truncated.
#### Files
       None.
#### Particulars
       boddef_c is one of five related subroutines,

          bods2c_c      Body string to code
          bodc2s_c      Body code to string
          bodn2c_c      Body name to code
          bodc2n_c      Body code to name
          boddef_c      Body name/code definition

       bods2c_c, bodc2s_c, bodn2c_c, and bodc2n_c perform translations between
       body names and their corresponding integer ID codes which are
       used in SPICE files and routines.

       bods2c_c is a slightly more general version of bodn2c_c: support
       for strings containing ID codes in string format enables a caller
       to identify a body using a string, even when no name is
       associated with that body.

       bodc2s_c is a general version of bodc2n_c; the routine returns either
       the name assigned in the body ID to name mapping or a string
       representation of the CODE value if no mapping exists.

       boddef_c assigns a body name to ID mapping. The mapping has priority
       in name-to-ID and ID-to-name translations.

       Refer to NAIF_IDs for the list of name/code associations built into
       SPICE, and for details concerning adding new name/code
       associations at run time by loading text kernels.

       Modifying the SPICE name-ID mapping set
       =======================================

       Each body has a unique integer 'code', but may have several
       names. Thus you may associate more than one name with
       a particular integer code.

       'code' may already have a name as defined by a previous
       call to boddef_c or as part of the set of default
       definitions.  That previous definition will remain,
       and a translation of that name will still give the
       same 'code'.  However, future translations of 'code' will
       give the new 'name' instead of the previous one.  This
       feature is useful for assigning a more familiar or
       abbreviated name to a body. For example, in addition
       to the default name for body 5, "JUPITER BARYCENTER",
       you could define the abbreviation "JB" to mean 5.

       Note: In the case where boddef_c performs a name-to-ID mapping
       assignment for an unused body name and unused ID value,
       any subsequent assignment to NAME destroys the previous
       mapping.

          boddef_c ( "spud", 22)

       then

          boddef_c ( "spud", 23)

       results in the state "spud" maps to 23, 23 maps to "spud",
       and 22 maps to nothing ('found' in bodc2n_c returns SPICEFALSE).
#### Examples
       You may associate a new name with a particular code that
       has already been defined:

              boddef_c ( "JB", 5 );

       You may also define the name and integer code for a new body:

              boddef_c ( "Asteroid Frank", 20103456 );

       After these calls to boddef_c, bodn2c_c would return the following
       translations:

          Name                         Code    Found?
          ------------------------   ------    ------
          "JB"                            5    Yes
          "Jupiter Barycenter"            5    Yes
          "ASTEROID FRANK"         20103456    Yes
          "ASTEROIDFRANK"                 -    No
          "Frank"                         -    No

       and BODC2N will return these translations:

          Code        Name                     Found?
          -------     -------------------      ------
                 5    "JB"                     Yes
          20103456    "Asteroid Frank"         Yes
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
       K.R. Gehringer  (JPL)
       B.V. Semenov    (JPL)
#### Version
       -CSPICE Version 2.2.2, 16-MAY-2009 (EDW)

           Edit to Particulars section to document the bodc2s_c routine.

       -CSPICE Version 2.2.1, 27-FEB-2008 (BVS)

           Corrected the contents of the Required_Reading section of
           the header.

       -CSPICE Version 2.2.0, 23-JAN-2004 (EDW)

          Rewrote header for clarity with regards to the
          current capabilities of the kernel subsystem.

       -CSPICE Version 2.1.0, 17-NOV-2003 (EDW)

          Updated header to describe the maximum allowed length
          for 'name' and its effect on this module.

          Updated header with information on new functionality.
          The code-to-name retrieval routines now return the exact
          string as defined in the last code/name mapping (case
          and space).

       -CSPICE Version 2.0.1, 08-FEB-1998 (EDW)

          Corrected and clarified header entries.

       -CSPICE Version 2.0.0, 06-JAN-1998 (NJB)

           The type of the input argument name was changed to
           ConstSpiceChar *.

           References to C2F_CreateStr_Sig were removed; code was
           cleaned up accordingly.  String checks are now done using
           the macro CHKFSTR.

       -CSPICE Version 1.0.0, 25-OCT-1997 (NJB)

          Based on SPICELIB Version 1.0.0, 23-JAN-1996 (KRG)
#### Index_Entries
       body name/id code definition
#### Link to routine boddef_c source file boddef_c.c

    Wed Jun  9 13:05:19 2010