sce2s_c

Index Page sce2s_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 sce2s_c ( SpiceInt        sc,
                      SpiceDouble     et,
                      SpiceInt        lenout,
                      SpiceChar     * sclkch  )
#### Abstract
       Convert an epoch specified as ephemeris seconds past J2000 (ET) to a
       character string representation of a spacecraft clock value (SCLK).
#### Required_Reading
       SCLK
       TIME
#### Keywords
       CONVERSION
       TIME
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       sc         I   NAIF spacecraft clock ID code.
       et         I   Ephemeris time, specified as seconds past J2000.
       lenout     I   Maximum length of output string.
       sclkch     O   An SCLK string.
#### Detailed_Input
       sc             is a NAIF ID code for a spacecraft clock whose
                      reading at the epoch specified by `et' is desired.

       et             is an epoch, specified as ephemeris seconds past
                      J2000 TDB.

       lenout         is the maximum number of characters that can be
                      accommodated in the output string.  This count
                      includes room for the terminating null character. For
                      example, if the maximum allowed length of the output
                      string, including the terminating null, is 25
                      characters, then `lenout' should be set to 25.

                      In order to choose an appropriate value of `lenout',
                      you can examine an SCLK kernel for the clock specified
                      by `sc'.  The format of string representations of
                      the clock's values is specified by kernel variables
                      associated with the clock.  See Examples below for
                      further information.
#### Detailed_Output
       sclkch         is a character string representation of the
                      spacecraft clock value that corresponds to `et', for
                      the spacecraft clock specified by the input argument
                      `sc'. `sclkch' is an absolute spacecraft clock value,
                      so a partition number is included in the string. The
                      format of `sclkch' is specified in the SCLK kernel
                      for the clock `sc'.  A general discussion of
                      spacecraft clock string formats is available in the
                      SCLK Required Reading.
#### Parameters
       None.
#### Exceptions
       1)  This routine assumes that an SCLK kernel appropriate to the
           spacecraft clock identified by the input argument SC has been
           loaded.  If an SCLK kernel has not been loaded, does not contain
           all of the required data, or contains invalid data, error
           diagnoses will be performed by routines in the call tree of this
           routine.  The output argument `sclkch' will not be modified.

       2)  When using an SCLK kernel that maps SCLK to a time system other
           than ET (also called barycentric dynamical time---"TDB"), it is
           necessary to have a leapseconds kernel loaded at the time this
           routine is called.  If a leapseconds kernel is required for
           conversion between SCLK and ET but is not loaded, the error will
           be diagnosed by routines called by this routine. The output
           argument `sclkch' will not be modified.

           The time system to which an SCLK kernel maps SCLK epochs is
           indicated by the variable SCLK_TIME_SYSTEM_nn in the kernel,
           where nn is the negative of the NAIF integer code for the
           spacecraft. The time system used in a kernel is TDB if and only
           if the variable is assigned the value 1.

       3)  If the input ET value is not representable in the spacecraft
           clock string format for the spacecraft clock identified by `sc',
           the error will be diagnosed by routines in the call tree of this
           routine.  The output argument `sclkch' will not be modified.

       4)  If the declared length of the output argument `sclkch' is too
           short to contain the output spacecraft clock string produced by
           this routine, the error will be diagnosed by routines in the
           call tree of this routine.  The output argument `sclkch' may
           contain a portion of the truncated string.
#### Files
       1)  An SCLK kernel appropriate to the spacecraft clock identified
           by SC must be loaded at the time this routine is called.

       2)  If the SCLK kernel used with this routine does not map SCLK
           directly to barycentric dynamical time, a leapseconds kernel
#### Particulars
       This routine is provided as a convenience; it is simply shorthand
       for the code fragment

          sce2t_c  ( sc,  et,      &sclkdp );
          scdecd_c ( sc,  sclkdp,   sclkch );
#### Examples
       The numerical results shown for these examples may differ across
       platforms.  The results depend on the SPICE kernels used as
       input, the compiler and supporting libraries, and the machine
       specific arithmetic implementation.

       1)  Determine the length of Galileo spacecraft clock strings.

           Examine a Galileo SCLK kernel.  There you'll find the
           kernel variable assignments

              SCLK01_MODULI_77          = ( 16777215 91 10 8 )
              SCLK01_OFFSETS_77         = (        0  0  0 0 )

           Each field of the clock string contains values ranging
           from the offset value to M-1, where M is the corresponding
           modulus.  So the Galileo clock fields have maximum values

              16777214 90 9 7

           representing the partition number by the symbol "pp" and
           the field delimiter character by the symbol "D", we see
           that the GLL SCLK format is

              pp/xxxxxxxxDxxDxDx

           This string has length 18 characters.  Accounting for the
           terminating null character, the value of `lenout' should
           be set to at least 19.

           Note:  the delimiter character is determined by the integer
           code assignment

              SCLK01_OUTPUT_DELIM_77    = (                2 )

           The SCLK Required Reading indicates that 2 is the SCLK kernel
           code for the colon character.

       2)  Find the Galileo SCLK value corresponding to the ET value

              -322452420.5593641.

           We can use the program below:

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

              int main()
              {
                 #define SCLKLEN         30

                 /.
                 The spacecraft ID code for the Galileo orbiter
                 is -77.  This is the code for the Galileo spacecraft
                 clock as well.
                 ./
                 #define GLL             -77

                 SpiceChar               sclkch[SCLKLEN];
                 SpiceDouble             et;

                 /.
                 Start out by loading the SCLK kernel.  In your own
                 program, you must use the name of a real SCLK kernel.
                 The name shown here is fictitious.
                 ./
                 furnsh_c ( "gllsclk.ker" );

                 /.
                 Load a leapseconds kernel in case it is needed for
                 SCLK-to-ET conversion.  Depending on the SCLK kernel
                 used, it may not be necessary to load this file; it's
                 just a simple, reliable way of making sure that the
                 leapseconds kernel constants are available if we need
                 them.  Again, a fictitious name is used.
                 ./
                 furnsh_c ( "leapseconds.ker" );

                 et = -322452420.5593641;

                 sce2s_c ( GLL, et, SCLKLEN, sclkch );

                 printf ( "ET        = %25.17e\n"
                          "GLL SCLK  =  %s\n",
                          et,
                          sclkch                    );

                 return ( 0 );

              }

           The output will be

              ET        =  -3.22452420559364080e+08
              GLL SCLK  =  1/00010001:44:2:0

       3)  Convert the UTC time

              August 25 1989 4:00:00

           to a Voyager 2 SCLK value.

           To perform this conversion, we could use the program below.

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

              int main()
              {
                 /.
                 The spacecraft ID code for the Voyager 2 spacecraft
                 is -32.  This is the code for the Voyager 2 spacecraft
                 clock as well.
                 ./
                 #define VGR2            -32
                 #define SCLKLEN         30

                 SpiceChar               sclkch[SCLKLEN];
                 SpiceDouble             et;

                 /.
                 Load SCLK and leapseconds kernels.
                 ./
                 furnsh_c ( "vgr2sclk.ker"    );
                 furnsh_c ( "leapseconds.ker" );

                 /.
                 Find the Voyager 2 SCLK string corresponding to the
                 specified UTC time.
                 ./
                 str2et_c ( "Aug 25 1989 4:00:00",  &et              );
                 sce2s_c  ( VGR2,       et,         SCLKLEN,  sclkch );

                 printf ( "ET         = %25.17e\n"
                          "VGR2 SCLK  =  %s\n",
                          et,
                          sclkch                    );

                 return ( 0 );
              }

           The output will be

              ET         =  -3.26707143817267537e+08
              VGR2 SCLK  =  4/11390:22:012
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       C.H. Acton     (JPL)
       N.J. Bachman   (JPL)
#### Version
       -CSPICE Version 1.1.1, 29-JUL-2003 (NJB) (CHA)

          Various header changes were made to improve clarity and
          more fully explain the routine's functionality.

       -CSPICE Version 1.1.0, 09-FEB-1998 (NJB)

          Re-implemented routine without dynamically allocated, temporary
          strings.  Updated the Exceptions header section.

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

          Based on SPICELIB Version 1.2.0, 10-APR-1992 (NJB) (WLT)
#### Index_Entries
       ephemeris time to spacecraft_clock string
#### Link to routine sce2s_c source file sce2s_c.c

    Thu Apr 16 08:59:03 2009