Abstract

   CSPICE_TPICTR creates a time format picture suitable for use by the
   routine cspice_timout from a given sample time string.

I/O

   Given:

      sample   a representative scalar time string to use as a model to format
               time strings (the string need not describe an actual date - only
               format matters).

               help, sample
                  STRING = Scalar

      pictln   the length in characters of output `pictur' (this argument
               should have a value of 1 plus the assumed output string length
               to accommodate the C null terminator).

               help, pictln
                  LONG = Scalar

   the call:

      cspice_tpictr, sample, pictln, pictur, ok, errmsg

   returns:

      pictur   a scalar format picture string suitable for use with the SPICE
               routine cspice_timout.

               help, pictur
                  STRING = Scalar

      ok       a scalar boolean indicating whether `sample' parsed without
               error (True) or some parse error occurred (False).

               help, ok
                  BOOLEAN = Scalar

      errmsg   a scalar string containing the explanation of the parse error.

               help, errmsg
                  STRING = Scalar

Parameters

   None.

Examples

   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

   1) Given a sample with the format of the UNIX date string,
      create a SPICE time picture for use in cspice_timout.


      Example code begins here.


      PRO tpictr_ex1

         ;;
         ;; Given a sample with the format of the UNIX date string,
         ;; create a SPICE time picture for use in cspice_timout.
         ;;
         sample = 'Thu Oct 1 11:11:11 PDT 1111'

         ;;
         ;; Assign a length for 'pictur' long enough to hold
         ;; the picture based on 'sample' - the length should
         ;; always be at least the string length of the
         ;; time string described by 'sample' plus one.
         ;;
         pictln = 64L

         ;;
         ;; Make the call. 'ok' returns false is an error occurred.
         ;; The error description returns in the err variable.
         ;;
         cspice_tpictr, sample, pictln, pictur, ok, errmsg

         ;;
         ;; If a false error flag, print the picture; if
         ;; a true error flag, print the error message.
         ;;
         if( ok ) then begin
            print, pictur
         endif else begin
            print, errmsg
         endelse

      END


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


      Wkd Mon DD HR:MN:SC PDT YYYY ::UTC-7

Particulars

   Although the routine cspice_timout provides SPICE 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 cspice_timout.

   This routine allows SPICE 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 cspice_timout.

   Note that cspice_timout can produce many time strings whose patterns
   can not be discerned by this routine. When such outputs are
   called for, the user must consult cspice_timout 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.

Exceptions

   1)  All problems with the inputs are reported 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.

   3)  If any of the input arguments, `sample' or `pictln', is
       undefined, an error is signaled by the IDL error handling
       system.

   4)  If any of the input arguments, `sample' or `pictln', is not of
       the expected type, or it does not have the expected dimensions
       and size, an error is signaled by the Icy interface.

   5)  If any of the output arguments, `pictur', `ok' or `errmsg', is
       not a named variable, an error is signaled by the Icy
       interface.

Files

   None.

Restrictions

   None.

Required_Reading

   ICY.REQ
   TIME.REQ

Literature_References

   None.

Author_and_Institution

   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version

   -Icy Version 1.1.0, 25-AUG-2021 (JDR)

       Changed the output argument name "lenout" to "pictln"
       for consistency with other routines.

       Edited the header to comply with NAIF standard. Added
       example's problem statement.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

   -Icy Version 1.0.0, 16-JUN-2003 (EDW)

Index_Entries

   Use a sample time string to produce a time format picture