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
gfrprt

Table of contents
Procedure
Abstract
Required_Reading
Keywords
Declarations
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version

Procedure

     GFRPRT ( GF, progress reporting package )

     SUBROUTINE GFRPRT ( WINDOW, BEGMSS, ENDMSS, IVBEG, IVEND, TIME )

Abstract

     The entry points contained under this routine provide users
     information regarding the status of a GF search in progress.

Required_Reading

     GF

Keywords

     SEARCH
     UTILITY

Declarations

     IMPLICIT NONE

     INCLUDE               'zzgf.inc'

     INTEGER               LBCELL
     PARAMETER           ( LBCELL = -5 )

     DOUBLE PRECISION      WINDOW ( LBCELL : * )
     CHARACTER*(*)         BEGMSS
     CHARACTER*(*)         ENDMSS
     DOUBLE PRECISION      IVBEG
     DOUBLE PRECISION      IVEND
     DOUBLE PRECISION      TIME

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     LBCELL     P   The SPICE cell lower bound.
     MXBEGM     P   Maximum progress report message prefix length.
     MXENDM     P   Maximum progress report message suffix length.
     WINDOW     I   A window over which a job is to be performed.
     BEGMSS     I   Beginning of the text portion of the output message
     ENDMSS     I   End of the text portion of the output message
     IVBEG      I   Current confinement window interval start time.
     IVEND      I   Current confinement window interval stop time.
     TIME       I   Input to the reporting routine.

Detailed_Input

     See the individual entry points.

Detailed_Output

     See the individual entry points.

Parameters

     LBCELL   is the SPICE cell lower bound.

     MXBEGM,
     MXENDM   are, respectively, the maximum lengths of the progress
              report message prefix and suffix.

Exceptions

     1)  See the individual entry points.

Files

     None.

Particulars

     This umbrella routine contains default progress reporting entry
     points that display a report via console I/O. These routines may
     be used by SPICE-based applications as inputs to mid-level GF
     search routines. These routines may be useful even when progress
     reporting is not desired, since the mid-level search routines
     provide some capabilities that aren't supported by the top-level
     GF routines.

     Developers wishing to use their own GF progress reporting
     routines must design them with the same interfaces and should
     assign them the same progress reporting roles as the entry points
     of these routines.

     The entry points contained in this routine are written to
     make reporting of work (such as searching for a geometric event)
     over a particular window easy. This is an important feature for
     interactive programs that may "go away" from the user's control
     for a considerable length of time. It allows the user to see that
     something is still going on (although maybe not too quickly).

     The three entry points contained under this module are:

        GFREPI  used to set up the reporting mechanism. It lets GFRPRT
                know that some task is about to begin that involves
                interaction with some window of times. It is used
                only to set up and store the constants associated with
                the reporting of the job in progress.

        GFREPU  is used to notify the reporter that work has
                progressed to a given point with respect to the start
                of the confinement window.

        GFREPF  is used to "finish" the reporting of work (set the
                completion value to 100%.

     The progress reporting utilities are called by GF search routines
     as follows:

        1) Given a window over which some work is to be performed,
           CALL GFREPI with the appropriate inputs, to let the routine
           know the intervals over which some work is to be done.

        2) Each time some "good" amount of work has been done, call
           GFREPU so that the total amount of work done can be updated
           and can be reported.

        3) When work is complete call GFREPF to "clean up" the end of
           the progress report.

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) This example shows how to call a mid-level GF search API that
        requires as input progress reporting routines.

        If custom progress reporting routines are available, they
        can replace GFREPI, GFREPU, and GFREPF in any GF API calls.

        The code example below is the first example in the header of
        GFOCCE.


        Conduct a search using the default GF progress reporting
        capability.

        The program will use console I/O to display a simple
        ASCII-based progress report.

        The program will find occultations of the Sun by the Moon as
        seen from the center of the Earth over the month December,
        2001.

        We use light time corrections to model apparent positions of
        Sun and Moon. Stellar aberration corrections are not specified
        because they don't affect occultation computations.

        Use the meta-kernel shown below to load the required SPICE
        kernels.


           KPL/MK

           File name: gfrprt_ex1.tm

           This meta-kernel is intended to support operation of SPICE
           example programs. The kernels shown here should not be
           assumed to contain adequate or correct versions of data
           required by SPICE-based user applications.

           In order for an application to use this meta-kernel, the
           kernels referenced here must be present in the user's
           current working directory.

           The names and contents of the kernels referenced
           by this meta-kernel are as follows:

              File name                     Contents
              ---------                     --------
              de421.bsp                     Planetary ephemeris
              pck00008.tpc                  Planet orientation and
                                            radii
              naif0009.tls                  Leapseconds


           \begindata

              KERNELS_TO_LOAD = ( 'de421.bsp',
                                  'pck00008.tpc',
                                  'naif0009.tls'  )

           \begintext

           End of meta-kernel


        Example code begins here.


              PROGRAM GFRPRT_EX1
              IMPLICIT NONE

        C
        C     SPICELIB functions
        C
              INTEGER               WNCARD

        C
        C     SPICELIB default functions for
        C
        C        - Interrupt handling (no-op function):   GFBAIL
        C        - Search refinement:                     GFREFN
        C        - Progress report termination:           GFREPF
        C        - Progress report initialization:        GFREPI
        C        - Progress report update:                GFREPU
        C        - Search step size "get" function:       GFSTEP
        C
              LOGICAL               GFBAIL
              EXTERNAL              GFBAIL

              EXTERNAL              GFREFN
              EXTERNAL              GFREPI
              EXTERNAL              GFREPU
              EXTERNAL              GFREPF
              EXTERNAL              GFSTEP

        C
        C     Local parameters
        C
              CHARACTER*(*)         TIMFMT
              PARAMETER           ( TIMFMT =
             .   'YYYY MON DD HR:MN:SC.###### ::TDB (TDB)' )

              DOUBLE PRECISION      CNVTOL
              PARAMETER           ( CNVTOL = 1.D-6 )

              INTEGER               MAXWIN
              PARAMETER           ( MAXWIN = 2 * 100 )

              INTEGER               TIMLEN
              PARAMETER           ( TIMLEN = 40 )

              INTEGER               LBCELL
              PARAMETER           ( LBCELL = -5 )

        C
        C     Local variables
        C
              CHARACTER*(TIMLEN)    WIN0
              CHARACTER*(TIMLEN)    WIN1
              CHARACTER*(TIMLEN)    BEGSTR
              CHARACTER*(TIMLEN)    ENDSTR

              DOUBLE PRECISION      CNFINE ( LBCELL : 2 )
              DOUBLE PRECISION      ET0
              DOUBLE PRECISION      ET1
              DOUBLE PRECISION      LEFT
              DOUBLE PRECISION      RESULT ( LBCELL : MAXWIN )
              DOUBLE PRECISION      RIGHT

              INTEGER               I

              LOGICAL               BAIL
              LOGICAL               RPT

        C
        C     Saved variables
        C
        C     The confinement and result windows CNFINE and RESULT are
        C     saved because this practice helps to prevent stack
        C     overflow.
        C
              SAVE                  CNFINE
              SAVE                  RESULT

        C
        C     Load kernels.
        C
              CALL FURNSH ( 'gfrprt_ex1.tm' )

        C
        C     Initialize the confinement and result windows.
        C
              CALL SSIZED ( 2,      CNFINE )
              CALL SSIZED ( MAXWIN, RESULT )

        C
        C     Obtain the TDB time bounds of the confinement
        C     window, which is a single interval in this case.
        C
              WIN0 = '2001 DEC 01 00:00:00 TDB'
              WIN1 = '2002 JAN 01 00:00:00 TDB'

              CALL STR2ET ( WIN0, ET0 )
              CALL STR2ET ( WIN1, ET1 )

        C
        C     Insert the time bounds into the confinement
        C     window.
        C
              CALL WNINSD ( ET0, ET1, CNFINE )

        C
        C     Select a 20 second step. We'll ignore any occultations
        C     lasting less than 20 seconds.
        C
              CALL GFSSTP ( 20.D0 )

        C
        C     Turn on progress reporting; turn off interrupt
        C     handling.
        C
              RPT  = .TRUE.
              BAIL = .FALSE.

        C
        C     Perform the search.
        C
              CALL GFOCCE ( 'ANY',
             .              'MOON',   'ellipsoid',  'IAU_MOON',
             .              'SUN',    'ellipsoid',  'IAU_SUN',
             .              'LT',     'EARTH',      CNVTOL,
             .              GFSTEP,   GFREFN,       RPT,
             .              GFREPI,   GFREPU,       GFREPF,
             .              BAIL,     GFBAIL,       CNFINE,  RESULT )


              IF ( WNCARD(RESULT) .EQ. 0 ) THEN

                 WRITE (*,*) 'No occultation was found.'

              ELSE

                 DO I = 1, WNCARD(RESULT)

        C
        C           Fetch and display each occultation interval.
        C
                    CALL WNFETD ( RESULT, I, LEFT, RIGHT )

                    CALL TIMOUT ( LEFT,  TIMFMT, BEGSTR )
                    CALL TIMOUT ( RIGHT, TIMFMT, ENDSTR )

                    WRITE (*,*) 'Interval ', I
                    WRITE (*,*) '   Start time: '//BEGSTR
                    WRITE (*,*) '   Stop time:  '//ENDSTR

                 END DO

              END IF

              END


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


        Occultation/transit search 100.00% done.

         Interval            1
            Start time: 2001 DEC 14 20:10:14.195952  (TDB)
            Stop time:  2001 DEC 14 21:35:50.317994  (TDB)


        Note that the progress report has the format shown below:

           Occultation/transit search   6.02% done.

        The completion percentage was updated approximately once per
        second.


     2) The following piece of code provides a more concrete example
        of how these routines might be used. It is part of code that
        performs a search for the time of an occultation of one body
        by another. It is intended only for illustration and is not
        recommended for use in code that has to do real work.

        C
        C     Prepare the progress reporter if appropriate.
        C
              IF ( RPT ) THEN
                 CALL UDREPI ( CNFINE, 'Occultation/transit search ',
             .                         'done.'                      )
              END IF

        C
        C     Cycle over the intervals in the confining window.
        C
              COUNT = WNCARD(CNFINE)

              DO I = 1, COUNT
        C
        C        Retrieve the bounds for the Ith interval of the
        C        confinement window. Search this interval for
        C        occultation events. Union the result with the
        C        contents of the RESULT window.
        C
                 CALL WNFETD ( CNFINE, I, START, FINISH  )

                 CALL ZZGFSOLV ( ZZGFOCST, UDSTEP, UDREFN, BAIL,
             .                   UDBAIL,   CSTEP,  STEP,   START,
             .                   FINISH,   TOL,    RPT,    UDREPU,
             .                   RESULT                          )


                 IF (  FAILED()  ) THEN
                    CALL CHKOUT ( 'GFOCCE'  )
                    RETURN
                 END IF

                 IF ( BAIL ) THEN
        C
        C           Interrupt handling is enabled.
        C
                    IF ( UDBAIL () ) THEN
        C
        C              An interrupt has been issued. Return now
        C              regardless of whether the search has been
        C              completed.
        C
                       CALL CHKOUT ( 'GFOCCE' )
                       RETURN

                    END IF

                 END IF

              END DO

        C
        C     End the progress report.
        C
              IF ( RPT ) THEN
                 CALL UDREPF
              END IF


     3) For more concrete examples of how these routines are used in
        SPICELIB, please refer to the actual code of any of the GF API
        calls.

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     L.S. Elson         (JPL)
     B.V. Semenov       (JPL)
     W.L. Taber         (JPL)
     I.M. Underwood     (JPL)

Version

    SPICELIB Version 1.0.2, 27-AUG-2021 (JDR)

        Edited the header of all entry points and GFRPRT to comply with
        NAIF standard.

        Added complete example code to GFRPRT.

    SPICELIB Version 1.0.1, 10-FEB-2014 (BVS)

        Added declarations of IVBEG and IVEND to the $Declarations
        section of the GFREPU header.

        Corrected declaration of WINDOW in the $Declarations
        section and added descriptions of LBCELL to the GFREPI
        header.

    SPICELIB Version 1.0.0, 06-MAR-2009 (NJB) (LSE) (WLT) (IMU)
Fri Dec 31 18:36:25 2021