Procedure

   void tpictr_c ( ConstSpiceChar * sample,
                   SpiceInt         lenout,
                   SpiceInt         lenerr,
                   SpiceChar      * pictur,
                   SpiceBoolean   * ok,
                   SpiceChar      * errmsg )

Abstract

   Given a sample time string, create a time format picture
   suitable for use by the routine timout_c.

Required_Reading

    None.

Keywords

    TIME

Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   sample     I   A sample time string.
   lenout     I   The length for the output picture string.
   lenerr     I   The length for the output error string.
   pictur     O   A format picture that describes sample.
   ok         O   Flag indicating whether sample parsed successfully.
   errmsg     O   Diagnostic returned if sample cannot be parsed.

Detailed_Input

   sample     is a representative time string to use as a model to
              format time strings.

   lenout     is the allowed length for the output picture.  This length
              must large enough to hold the output string plus the null
              terminator.  If the output string is expected to have x
              characters, lenout needs to be x + 1.  80 is a reasonable
              value for lenout (79 characters plus the null
              terminator).  

   lenerr     is the allowed length for the output error string.    
   
   

Detailed_Output

   pictur     is a format picture suitable for use with the SPICE
              routine timout_c.  This picture, when used to format an
              epoch via timout_c, will yield the same time components in
              the same order as the components in sample.

   ok         is a logical flag indicating whether the input format
              sample could be parsed. If all of the components of
              sample are recognizable, ok will be returned with the
              value SPICEFALSE.  If some part of pictur cannot be
              parsed, ok will be returned with the value SPICEFALSE.

   errmsg     is a diagnostic message that indicates what part of
              sample was not recognizable.  If sample was successfully
              parsed, ok will be SPICEFALSE and errmsg will be
              returned as an empty string.

Parameters

   None.

Exceptions

   Error free.

   1) All problems with the inputs are diagnosed via ok and errmsg.

   2) If a format picture can not be created from the sample
      time string, pictur is returned as a blank string.

Files

   None.

Particulars

   Although the routine timout_c provides CSPICE users with a great
   deal of flexibility in formatting time strings, users must
   master the means by which a time picture is constructed
   suitable for use by timout_c.

   This routine allows CSPICE users to supply a sample time string
   from which a corresponding time format picture can be created,
   freeing users from the task of mastering the intricacies of
   the routine timout_c.

   Note that timout_c can produce many time strings whose patterns
   can not be discerned by this routine.  When such outputs are
   called for, the user must consult timout_c and construct the
   appropriate format picture "by hand."  However, these exceptional
   formats are not widely used and are not generally recognizable
   to an uninitiated reader.

Examples

   Suppose you need to print epochs corresponding to some events and
   you wish the epochs to have the same arrangement of components as in
   the string "10:23 P.M. PDT January 3, 1993".

   The following subroutine call will construct the appropriate format
   picture for use with timout_c.

   tpictr_c ( "10:23 P.M. PDT January 3, 1993",
               lenout, lenerr, pictur, &ok, errmsg );

   The resulting picture is:

      "AP:MN AMPM PDT Month DD, YYYY ::UTC-7"

   This picture can be used with timout_c to format a sequence
   of epochs, et[0],...,et[n-1] (given as ephemeris seconds past J2000)
   as shown in the loop below:

      #include "SpiceUsr.h"
          .
          .
          .
      for ( i = 0; i < n; i++ )
      {
         timout_c ( et[i], pictur, string );
         printf ( "Epoch: %d --- %s\n", i, string );
      }

Restrictions

   None.

Literature_References

   None.

Author_and_Institution

   
   W.L. Taber      (JPL)
   E.D. Wright     (JPL)

Version

   -CSPICE Version 1.0.0, 23-JUL-1999   (EDW) (WLT)

Index_Entries

   Use a sample time string to produce a time format picture

Link to routine tpictr_c source file tpictr_c.c