scfmt_c

Index Page scfmt_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 scfmt_c ( SpiceInt      sc,
                      SpiceDouble   ticks,
                      SpiceInt      lenout,
                      SpiceChar   * clkstr  )
#### Abstract
       Convert encoded spacecraft clock ticks to character clock format.
#### Required_Reading
       SCLK
#### Keywords
       CONVERSION
       TIME
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       sc         I   NAIF spacecraft identification code.
       ticks      I   Encoded representation of a spacecraft clock count.
       lenout     I   Maximum allowed length of output string.
       clkstr     O   Character representation of a clock count.
#### Detailed_Input
       sc         is the NAIF ID number for the spacecraft whose clock's
                  time is being decoded.

       ticks      is the double precision encoding of a clock time in
                  units of ticks.  Partition information is not reflected
                  in this value.

                  An analogy may be drawn between a spacecraft clock and
                  a standard wall clock.  The number of ticks
                  corresponding to the wall clock string

                     hh:mm:ss

                  would be the number of seconds represented by that
                  time.

                  For example,

                     Clock string    Number of ticks
                     ------------    ---------------
                       00:00:10             10
                       00:01:00             60
                       00:10:00            600
                       01:00:00           3600
                       01:01:00           3660

                  If ticks contains a fractional part the result is the
                  same as if ticks had been rounded to the nearest whole
                  number.

                  See the Examples section below for examples of
                  actual spacecraft clock conversions.

       lenout     The allowed length of the output string.  This length
                  must large enough to hold the 'clkstr' string plus the
                  null terminator.  If the output string is expected to
                  have x characters, 'lenout' must be x + 1.
#### Detailed_Output
       clkstr     is the spacecraft clock character string
                  corresponding to ticks.  Partition information is
                  not included in clkstr.

                  Using Galileo as an example, the full format clock
                  string is

                     wwwwwwww:xx:y:z

                  where z is a mod-8 counter (values 0-7) which
                  increments approximately once every 8 1/3 ms., y is a
                  mod-10 counter (values 0-9) which increments once
                  every time z turns over, i.e., approximately once every
                  66 2/3 ms., xx is a mod-91 (values 0-90) counter
                  which increments once every time y turns over, i.e.,
                  once every 2/3 seconds. wwwwwwww is the Real-Time Image
                  Count (RIM), which increments once every time xx turns
                  over, i.e., once every 60 2/3 seconds. The roll-over
                  expression for the RIM is 16777215, which corresponds
                  to approximately 32 years.

                  wwwwwwww, xx, y, and z are referred to interchangeably
                  as the fields or components of the spacecraft clock.
                  SCLK components may be separated by any of these five
                  characters: " "  ":"  ","  "-"  "."
                  The delimiter used is determined by a kernel pool
                  variable and can be adjusted by the user.

                  Some spacecraft clock components have offset, or
                  starting, values different from zero.  For example,
                  with an offset value of 1, a mod 20 counter would
                  cycle from 1 to 20 instead of from 0 to 19.

                  See the SCLK required reading for a detailed
                  description of the Voyager and Mars Observer clock
                  formats.
#### Parameters
       None.
#### Exceptions
       1) If the data type for the spacecraft is not supported
          then the error SPICE(NOTSUPPORTED) is signaled.

       2) If the value for ticks is negative, the error is diagnosed
          by routines called by this routine.

       3) If the SCLK kernel file does not contain data for the
          spacecraft specified by sc, then the error is diagnosed
          by routines called by this routine.

       4) If the output string pointer is null, the error SPICE(NULLPOINTER)
          is signaled.

       5) If the output string has length less than two characters, it
          is too short to contain one character of output data plus a null
          terminator, so it cannot be passed to the underlying Fortran
          routine.  In this event, the error SPICE(STRINGTOOSHORT) is
          signaled.

       6) If the length of clkstr (indicated by lenout) is at least two
          characters but not large enough to contain the output clock
          string, the error is diagnosed by a routine called by this
          routine.
#### Files
       None.
#### Particulars
       The routine sctiks_c performs the inverse operation to scfmt_c,
       converting from clock format to number of ticks.

       Note the important difference between scfmt_c and scdecd_c. scdecd_c
       converts some number of ticks since the spacecraft clock start
       time to a character string which includes a partition number.
       scfmt_c, which is called by scdecd_c, does not make use of partition
       information.
#### Examples
       The following program fragment finds partition start and stop
       times for the Galileo spacecraft from a spacecraft clock partition
       kernel file, called sclk.ker. Since those times are always
       returned in units of ticks, the program uses scfmt_c to print the
       times in Galileo clock format.

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

          #define                MXPART   9999
          #define                MAXLEN   30

          SpiceChar              start  [ 30 ];
          SpiceChar              stop   [ 30 ];

          SpiceDouble            pstart [ MXPART ];
          SpiceDouble            pstop  [ MXPART ];

          SpiceInt               sc  =  -77;
          SpiceInt               i;
          SpiceInt               nparts;

          furnsh_c ( "sclk.ker" );

          scpart_c ( sc, &nparts, pstart, pstop );

          for ( i = 0;  i < nparts;  i++ )
          {

             scfmt_c ( sc, pstart[ i ], MAXLEN, start );
             scfmt_c ( sc, pstop [ i ], MAXLEN, stop  );

             printf ( "\n"
                      "partition %d: \n"
                      "start =  %s\n"
                      "stop  =  %s\n",
                       i,
                       start,
                       stop                );
          }

       Below are some examples illustrating various input numbers of
       ticks and the resulting clock string outputs for the Galileo
       spacecraft.

          TICKS                 CLKSTR
          ----------------      --------------------
          -1                    Error: Ticks must be a positive number
          0                     "0:00:0:0"
          1                     "0:00:0:1"
          1.3                   "0:00:0:1"
          1.5                   "0:00:0:2"
          2                     "0:00:0:2"
          7                     "0:00:0:7"
          8                     "0:00:1:0"
          80                    "0:01:0:0"
          88                    "0:01:1:0"
          7279                  "0:90:9:7"
          7280                  "1:00:0:0"
          1234567890            "169583:45:6:2"

       The following examples are for the Voyager 2 spacecraft.
       Note that the third component of the Voyager clock has an
       offset value of one.

          TICKS                 CLKSTR
          ----------------      --------------------
          -1                    Error: Ticks must be a positive number
          0                     "00000 00 001"
          1                     "00000 00 002"
          1.3                   "00000:00:002"
          1.5                   "00000.00.003"
          2                     "00000-00-003"
          799                   "00000,00,800"
          800                   "00000 01 001"
          47999                 "00000 59 800"
          48000                 "00001 00 001"
          3145727999            "65535 59 800"
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman   (JPL)
       J.M. Lynch     (JPL)
       R.E. Thurman   (JPL)
#### Version
       -CSPICE Version 1.1.4, 11-FEB-2008   (NJB)

          Header example was updated to reflect current
          MXPART value of 9999.

       -CSPICE Version 1.1.3, 14-AUG-2006   (EDW)

          Replace mention of ldpool_c with furnsh_c.

       -CSPICE Version 1.1.2, 01-OCT-2003 (EDW)

           Added description of the 'lenout' input in the
           Detailed_Input section.

       -CSPICE Version 1.1.1, 26-MAR-2003 (NJB)

           Fixed description of exception (6):  replaced "lenout-1"
           with "lenout."

       -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.0.1, 17-APR-1992 (JML) (WLT)
#### Index_Entries
       convert spacecraft_clock ticks to character clock format
#### Link to routine scfmt_c source file scfmt_c.c

    Thu Apr 16 08:59:04 2009