Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page scfmt_c
Table of contents
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
       scfmt_c ( Convert SCLK "ticks" to character clock format )

       void scfmt_c  ( SpiceInt            sc,
                       SpiceDouble         ticks,
                       SpiceInt            clklen,
                       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   Spacecraft clock count encoded representation.
       clklen     I   Maximum length of output string `clkstr'.
       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.

       clklen      is the maximum allowed length of the output string
                   `clkstr'. This length must be large enough to hold the
                   output string plus the null-terminator character. If the
                   output string is expected to have N characters, `clklen'
                   should be at least N+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, the
           error SPICE(NOTSUPPORTED) is signaled by a routine in the call
           tree of this routine.

       2)  If the value for `ticks' is negative, an error is signaled
           by a routine in the call tree of this routine.

       3)  If the SCLK kernel file does not contain data for the
           spacecraft specified by `sc', an error is signaled by a routine
           in the call tree of this routine.

       4)  If the declared length of `clkstr' is not large enough to
           contain the output clock string, an error is signaled by a
           routine in the call tree of this routine.

       5)  If the `clkstr' output string pointer is null, the error
           SPICE(NULLPOINTER) is signaled.

       6)  If the `clkstr' output string has length less than two
           characters, the error SPICE(STRINGTOOSHORT) is signaled, since
           the output string is too short to contain one character of
           output data plus a null terminator.
#### 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 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) The following code example finds partition start and stop
          times for the Stardust spacecraft from a spacecraft clock
          kernel file. Since those times are always returned in units
          of ticks, the program uses scfmt_c to print the times in
          Stardust clock format.

          Use the SCLK kernel below to load the Stardust time
          correlation data and spacecraft clock partition information.

             sdu_sclkscet_00074.tsc

          Example code begins here.

          /.
             Program scfmt_ex1
          ./
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main()
          {
             /.
             Local parameters.
             ./
             #define                CLKLEN   31
             #define                MXPART   9999

             /.
             Local variables.
             ./
             SpiceChar              start  [ CLKLEN ];
             SpiceChar              stop   [ CLKLEN ];

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

             SpiceInt               sc;
             SpiceInt               i;
             SpiceInt               nparts;

             /.
             Assign the value for the Stardust spacecraft ID.
             ./
             sc = -29;

             /.
             Load the SCLK file.
             ./
             furnsh_c ( "sdu_sclkscet_00074.tsc" );

             /.
             Retrieve the arrays for `pstart' and `pstop' and the
             number of partitions within the SCLK.
             ./
             scpart_c ( sc, &nparts, pstart, pstop );

             /.
             Loop over each array value.
             ./
             for ( i = 0;  i < nparts;  i++ )
             {
                scfmt_c ( sc, pstart[ i ], CLKLEN, start );
                scfmt_c ( sc, pstop [ i ], CLKLEN, stop  );

                printf ( "\n"
                         "Partition: %d\n"
                         "   Start : %s\n"
                         "   Stop  : %s\n",
                          (int)i,
                          start,
                          stop                );
             }

             return ( 0 );
          }

          When this program was executed on a Mac/Intel/cc/64-bit
          platform, the output was:

          Partition: 0
             Start : 0000000000.000
             Stop  : 0602741011.080

          Partition: 1
             Start : 0602741014.217
             Stop  : 0605660648.173

          Partition: 2
             Start : 0605660649.000
             Stop  : 0631375256.224

          Partition: 3
             Start : 0631375257.000
             Stop  : 0633545577.218

          Partition: 4
             Start : 0633545578.000
             Stop  : 0644853954.043

          Partition: 5
             Start : 0644853954.000
             Stop  : 0655316480.089

          Partition: 6
             Start : 0655316480.000
             Stop  : 0660405279.066

          Partition: 7
             Start : 0660405279.000
             Stop  : 0670256568.229

          Partition: 8
             Start : 0670256569.000
             Stop  : 0674564039.091

          Partition: 9
             Start : 0674564040.000
             Stop  : 4294537252.255

       2) 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                    "00000000:00:0:0"
             1                    "00000000:00:0:1"
             1.3                  "00000000:00:0:1"
             1.5                  "00000000:00:0:2"
             2                    "00000000:00:0:2"
             7                    "00000000:00:0:7"
             8                    "00000000:00:1:0"
             80                   "00000000:01:0:0"
             88                   "00000000:01:1:0"
             7279                 "00000000:90:9:7"
             7280                 "00000001:00:0:0"
             1234567890           "00169583: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. Diaz del Rio     (ODC Space)
       E.D. Wright         (JPL)
#### Version
       -CSPICE Version 1.2.0, 10-AUG-2021 (JDR)

           Changed the input argument name "lenout" to "clklen" for consistency
           with other routines.

           Edited the header to comply with NAIF standard. Added
           reference to required SCLK and created complete example from
           existing code fragment using Stardust PDS archived data.

       -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

    Fri Dec 31 18:41:11 2021