Index Page srfs2c_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 srfs2c_c ( ConstSpiceChar  * srfstr,
                       ConstSpiceChar  * bodstr,
                       SpiceInt        * code,
                       SpiceBoolean    * found )

#### Abstract

       Translate a surface string, together with a body string, to the
       corresponding surface ID code. The input strings may contain
       names or integer ID codes.

#### Required_Reading

       DSK
       NAIF_IDS

#### Keywords

       CONVERSION
       DSK
       ID
       NAME
       STRING
       SURFACE

#### Brief_I/O

       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       srfstr     I   Surface name or ID string.
       bodstr     I   Body name or ID string.
       code       O   Integer surface ID code.
       found      O   Flag indicating whether surface ID was found.

#### Detailed_Input

       srfstr     is a string designating a surface. `srfstr' may contain
                  a surface name or a string representation of the
                  surface's integer ID code.

                  Case and leading and trailing blanks in a surface name
                  are not significant. Sequences of consecutive embedded
                  blanks are considered equivalent to a single blank. For
                  example, all of the strings below are considered to be
                  equivalent:

                     "MGS MOLA 128 PIXEL/DEG"
                     "MGS MOLA 128 pixel/deg"
                     "MGS MOLA 128 PIXEL/DEG   "
                     "MGS MOLA 128    PIXEL/DEG"
                     "   MGS MOLA 128 PIXEL/DEG"

                  However,

                     "MGSMOLA 128PIXEL/DEG"

                  is not equivalent to the names above.

       bodstr     is a string designating the body associated with the
                  input surface ID code. `bodstr' may contain a body name
                  or a string representation of the body's integer ID
                  code. For example, `bodstr' may contain

                     "1000012"

                  instead of

                     "67P/CHURYUMOV-GERASIMENKO (1969 R1)"

                  Case and leading and trailing blanks in a name are not
                  significant. The treatment of blanks in `bodstr' is the
                  same as for `srfstr'.

#### Detailed_Output

       code       is integer ID code of the surface designated by `srfstr',
                  for the body designated by `bodstr', if for this body an
                  association exists between the input surface string and a
                  surface ID code. `code' is defined if and only if the
                  output flag `found' is SPICETRUE.

       found      is a logical flag that is SPICETRUE if a surface code
                  corresponding to the input strings was found and
                  SPICEFALSE otherwise.

#### Parameters

       None.

#### Exceptions

       1)  If the input surface string does not map to an ID code
           and does not represent an integer, the output `code' is
           undefined and the output `found' is set to SPICEFALSE.

           This case is not treated as an error.

       2)  If the input body string does not map to an ID code and does
           not represent an integer, the output `code' is undefined and
           the output `found' is set to SPICEFALSE.

           This case is not treated as an error.

       3)  The error SPICE(EMPTYSTRING) is signaled if either input string
           does not contain at least one character, since such an input
           string cannot be converted to a Fortran-style string in this
           case.

       4)  The error SPICE(NULLPOINTER) is signaled if either input string
           pointer is null.

#### Files

       Surface name-to-ID mappings may be defined at run time by loading
       text kernels containing kernel variable assignments of the form

          NAIF_SURFACE_NAME += ( <surface name 1>, ... )
          NAIF_SURFACE_CODE += ( <surface code 1>, ... )
          NAIF_SURFACE_BODY += ( <body code 1>,    ... )

       Above, the Ith elements of the lists on the assignments' right
       hand sides together define the Ith surface name/ID mapping.

       The same effect can be achieved using assignments formatted as
       follows:

          NAIF_SURFACE_NAME += <surface name 1>
          NAIF_SURFACE_CODE += <surface code 1>
          NAIF_SURFACE_BODY += <body code 1>

          NAIF_SURFACE_NAME += <surface name 2>
          NAIF_SURFACE_CODE += <surface code 2>
          NAIF_SURFACE_BODY += <body code 2>

             ...

       Note the use of the

          +=

       operator; this operator appends to rather than overwrites the
       kernel variable named on the left hand side of the assignment.

#### Particulars

       Surfaces are always associated with bodies (which usually are
       ephemeris objects). For any given body, a mapping between surface
       names and surface ID codes can be established.

       Bodies serve to disambiguate surface names and ID codes: the set
       of surface names and surface ID codes for a given body can be
       thought of as belonging to a name space. A given surface ID code
       or surface name may be used for surfaces of multiple bodies,
       without conflict.

       Associations between surface names and ID codes are always made
       via kernel pool assignments; there are no built-in associations.

       srfs2c_c is one of four related subroutines:

          srfs2c_c    Surface string and body string to surface ID code
          srfscc_c    Surface string and body ID code to surface ID code
          srfc2s_c    Surface ID code and body ID code to surface string
          srfcss_c    Surface ID code and body string to surface string

       srfs2c_c, srfc2s_c, srfscc_c, and srfcss_c perform translations
       between surface strings and their corresponding integer ID codes.

       Refer to naif_ids.req for details concerning adding new surface
       name/code associations at run time by loading text kernels.

#### Examples

       The formatting of the results shown for this example may differ
       across platforms.

       1) Supposed a text kernel has been loaded that contains
          the following assignments:

             NAIF_SURFACE_NAME += ( 'MGS MOLA  64 pixel/deg',
                                    'MGS MOLA 128 pixel/deg',
                                    'PHOBOS GASKELL Q512'     )
             NAIF_SURFACE_CODE += (   1,   2,    1 )
             NAIF_SURFACE_BODY += ( 499, 499,  401 )

          Translate each surface and body string pair to the
          associated surface ID code. Also perform a translation
          for a surface name having no matching ID and for
          a body string having no matching body ID code.

          Use the meta-kernel shown below to define the required SPICE
          kernel variables.

             KPL/MK

             File: srfs2c_ex1.tm

             This meta-kernel is intended to support operation of SPICE
             example programs. The file contents shown here should not be
             assumed to contain adequate or correct versions of data
             required by SPICE-based user applications.

             \begindata

             NAIF_SURFACE_NAME += ( 'MGS MOLA  64 pixel/deg',
                                    'MGS MOLA 128 pixel/deg',
                                    'PHOBOS GASKELL Q512'     )
             NAIF_SURFACE_CODE += (   1,   2,    1 )
             NAIF_SURFACE_BODY += ( 499, 499,  401 )

             \begintext

         Example code begins here.

            /.
            srfs2c_c example 1
            ./
            #include <stdio.h>
            #include "SpiceUsr.h"

            int main()
            {
               /.
               Local constants
               ./
               #define BDNMLN          37
               #define SFNMLN          SPICE_SRF_SFNMLN
               #define NCASE           8

               /.
               Local variables
               ./
               SpiceBoolean            found;

               static SpiceChar        bodstr [NCASE][BDNMLN] =

                                         { "MARS", "PHOBOS", "MARS",
                                           "499",  "PHOBOS", "499",
                                           "MARS", "ZZZ" };

               static SpiceChar        srfstr [NCASE][BDNMLN] =

                                         { "MGS MOLA  64 pixel/deg",
                                           "PHOBOS GASKELL Q512",
                                           "MGS MOLA 128 pixel/deg",
                                           "MGS MOLA  64 pixel/deg",
                                           "1",
                                           "2",
                                           "ZZZ",
                                           "1"                      };

               static SpiceChar        tf     [2][6] =

                                         { "false", "true" };

               SpiceChar             * meta;

               SpiceInt                i;
               SpiceInt                surfid;

               meta = "srfs2c_ex1.tm";

               furnsh_c ( meta );

               printf ( "\n" );

               for ( i = 0;  i < NCASE;  i++ )
               {
                  srfs2c_c ( srfstr[i], bodstr[i], &surfid, &found );

                  printf ( "surface string   = %s\n"
                           "body string      = %s\n"
                           "surface ID found = %s\n",
                           srfstr[i],
                           bodstr[i],
                           tf[found]                 );

                  if ( found )
                  {
                     printf ( "surface ID       = %d\n", surfid );
                  }
                  printf ( "\n" );
               }
               return ( 0 );
            }

       When this program was executed on a PC/Linux/gcc/64-bit
       platform, the output was:

          surface string   = MGS MOLA  64 pixel/deg
          body string      = MARS
          surface ID found = true
          surface ID       = 1

          surface string   = PHOBOS GASKELL Q512
          body string      = PHOBOS
          surface ID found = true
          surface ID       = 1

          surface string   = MGS MOLA 128 pixel/deg
          body string      = MARS
          surface ID found = true
          surface ID       = 2

          surface string   = MGS MOLA  64 pixel/deg
          body string      = 499
          surface ID found = true
          surface ID       = 1

          surface string   = 1
          body string      = PHOBOS
          surface ID found = true
          surface ID       = 1

          surface string   = 2
          body string      = 499
          surface ID found = true
          surface ID       = 2

          surface string   = ZZZ
          body string      = MARS
          surface ID found = false

          surface string   = 1
          body string      = ZZZ
          surface ID found = false

#### Restrictions

       None.

#### Literature_References

       None.

#### Author_and_Institution

       N.J. Bachman    (JPL)
       B.V. Semenov    (JPL)
       E.D. Wright     (JPL)

#### Version

       -CSPICE Version 1.0.0, 22-JAN-2016 (NJB) (BVS) (EDW)

#### Index_Entries

       surface string and body string to surface ID code

#### Link to routine srfs2c_c source file srfs2c_c.c

    Wed Apr  5 17:54:44 2017