Procedure

     SCFM01 ( Convert ticks to a type 1 SCLK string. )

     ENTRY SCFM01 ( SC, TICKS, CLKSTR )

Abstract

     Convert a number of ticks to an equivalent type 1 spacecraft clock
     string.

Required_Reading

     SCLK

Keywords

     CONVERSION
     TIME

Declarations

    INTEGER               SC
    DOUBLE PRECISION      TICKS
    CHARACTER*(*)         CLKSTR

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     SC         I   NAIF spacecraft identification code.
     TICKS      I   Number of ticks represented by a clock count.
     CLKSTR     O   Character string representation of the clock count.

Detailed_Input

     SC       is a NAIF spacecraft identification code. See the
              $Examples section below, and also the KERNEL required
              reading file for a complete list of body ID codes.


     TICKS    is the number of ticks to be converted to a spacecraft
              clock string, where a tick is defined to be
              the smallest time increment expressible by the
              spacecraft clock.

              If TICKS contains a fractional part, the string that
              results is the same as if TICKS had been rounded to
              the nearest whole number.

              See $Examples below.

Detailed_Output

     CLKSTR   on output is the character string representation of
              the spacecraft clock count. The returned string has
              the form

                               'wwwwwwww:xx:y:z',

              where the number of components and the width of each
              one are different for each spacecraft. The delimiter
              used is determined by a kernel pool variable and is
              one of the five specified by the parameter DELIMS.
              See $Examples below.

              If CLKSTR is not long enough to accommodate the
              formatted tick value, the result will be truncated on
              the right.

Parameters

     None.

Exceptions

     1)  This routine assumes that 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, an
         error is signaled by a routine in the call tree of this
         routine. The output argument CLKSTR will not be modified.

         The variables that must be set by the SCLK kernel are:

            -  The number of fields in an (unabridged) SCLK string
            -  The output delimiter code
            -  The parallel time system code
            -  The moduli of the fields of an SCLK string
            -  The offsets for each clock field.
            -  The SCLK coefficients array
            -  The partition start times
            -  The partition end times

     2)  When using SCLK kernels that map 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, an error
         is signaled by a routine in the call tree of this routine. The
         output argument CLKSTR will not be modified.

         The time system that an SCLK kernel maps SCLK to 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 any of the following kernel variables have invalid values,
         the error will be diagnosed by routines called by this
         routine:

            -  The time system code
            -  The number of SCLK coefficients
            -  The number of partition start times
            -  The number of partition end times
            -  The number of fields of a SCLK string
            -  The number of moduli for a SCLK string

         If the number of values for any item read from the kernel
         pool exceeds the maximum allowed value, it is may not be
         possible to diagnose the error correctly, since overwriting
         of memory may occur. This particular type of error is not
         diagnosed by this routine.

     4)  If the input value for TICKS is negative, the error
         SPICE(VALUEOUTOFRANGE) is signaled. The output argument
         CLKSTR will not be modified.

     5)  If the output argument CLKSTR is too short to accommodate
         the output string produced by this routine, the error
         SPICE(SCLKTRUNCATED) is signaled. The output string
         CLKSTR will not be modified.

Files

     None.

Particulars

     The routine determines the values of the components of the
     spacecraft clock count that is equivalent to the number TICKS.
     The information needed to perform this operation, such as the
     number of clock components and their moduli, is provided by
     an SCLK kernel file. Normally, your program should load this
     file during initialization.

     This routine does not make use of any partition information.
     See SCDECD for details on how to make use of partition numbers.

Examples

     Below are some examples illustrating various inputs and the
      resulting 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

     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
         must be loaded at the time this routine is called.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     J.M. Lynch         (JPL)
     B.V. Semenov       (JPL)
     R.E. Thurman       (JPL)

Version

    SPICELIB Version 3.0.0, 01-DEC-2021 (NJB) (JDR)

        Updated to support buffering of data for multiple clocks.
        This entry point tracks kernel pool changes but no longer
        sets or uses watches.

        Edited the header to comply with NAIF standard.

    SPICELIB Version 2.3.0, 09-SEP-2013 (BVS)

        Updated to keep track of the POOL counter and call ZZCVPOOL.

    SPICELIB Version 2.2.0, 05-MAR-2009 (NJB)

        Bug fix: this routine now keeps track of whether its
        kernel pool look-up succeeded. If not, a kernel pool
        lookup is attempted on the next call to this routine.

    SPICELIB Version 2.1.0, 17-FEB-2008 (NJB)

        Bug fix: changed maximum value arguments to 1 in
        calls to SCLI01 to fetch NFIELD and DELCDE values.

        Bug fix: spaces between fields are now inserted
        correctly when the output field delimiter is blank.

    SPICELIB Version 2.0.1, 18-JUL-1996 (NJB)

        Misspelling in header fixed.

    SPICELIB Version 2.0.0, 17-APR-1992 (NJB)

        Error is now signaled if truncation of output string occurs.
        Header was updated, particularly $Exceptions and $Restrictions
        sections. Kernel pool watch is now set on required kernel
        variables. Comment section for permuted index source lines
        was added following the header.

    SPICELIB Version 1.0.0, 06-SEP-1990 (NJB) (JML) (RET)