Index Page gfrepu_c
A B C D E F G H I J K L M N O P Q R S T U V W X
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
       void gfrepu_c ( SpiceDouble ivbeg,
                       SpiceDouble ivend,
                       SpiceDouble time  )
#### Abstract
       This function tells the progress reporting system
       how far a search has progressed.
#### Required_Reading
       None.
#### Keywords
       UTILITY
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       ivbeg      I   Start time of work interval.
       ivend      I   End time of work interval.
       time       I   Current time being examined in the search process.
#### Detailed_Input
       ivbeg,
       ivend    are the bounds of a time interval. Normally this interval
                is contained within the confinement window `cnfine' passed to
                gfrepi_c on the latest call to that function, but this is
                not a requirement.

                In order for a meaningful progress report to be displayed,
                `ivbeg' and `ivend' must satisfy the following constraints:

                   - `ivbeg' must be less than or equal to `ivend'.

                   - Over a search pass, the sum of the differences

                        ivend - ivbeg

                     for all calls to this routine made during the pass
                     must equal the measure (that is, the sum of the
                     lengths of the intervals) of the confinement window
                     `cnfine'.

       time     is the current time reached in the search for an event.
                `time' must lie in the interval

                   ivbeg : ivend

                inclusive. The input values of `time' for a given interval
                need not form an increasing sequence.
#### Detailed_Output
       None. This routine does perform console I/O when progress
       reporting is enabled.
#### Parameters
       None.
#### Exceptions
       1)  If `ivbeg' and `ivend' are in decreasing order, the error
           SPICE(BADENDPOINTS) is signaled.

       2)  If `time' is not in the closed interval [ivbeg, ivend], the
           error SPICE(VALUEOUTOFRANGE) is signaled.

       3)  Any I/O errors resulting from writing to standard output will be
           diagnosed by routines in the call tree of this routine.
#### Files
       None.
#### Particulars
       This is one of three GF progress reporting routines that cooperate
       in order to display a report via console I/O. These routines may
       be used by SPICE-based applications as inputs to mid-level GF
       search 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 those of these routines.

       The GF progress reporting API routines are written to simplify
       reporting of work (such as searching for a geometric event) over a
       particular window. 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 routines constituting the GF progress reporting API
       are:

          gfrepi_c  is used to prepare the reporting mechanism for a search
                    pass. It is used to store the confinement window and
                    progress report message prefix and suffix, and to
                    initialize parameters associated with the reporting of
                    the job in progress.

          gfrepu_c  is used to notify the progress reporting system that
                    a specified increment of work has been completed
                    since the last call to gfrepu_c or gfrepi_c, whichever
                    occurred most recently.

          gfrepf_c  is used to "finish" the reporting of work (set the
                    completion value to 100%.
#### Examples
       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_c, gfrepu_c, and gfrepf_c in any GF API calls.

           The code fragment below is from the first code example in the
           header of

              gfocce_c.c

           Only the portions of that program relevant to use of the
           progress reporting routines are copied here.

              /.
              Select a twenty-second step. We'll ignore any occultations
              lasting less than 20 seconds.
              ./
              gfsstp_c ( 20.0 );

              /.
              Perform the search.
              ./
              gfocce_c ( "ANY",
                         "MOON",     "ellipsoid",  "IAU_MOON",
                         "SUN",      "ellipsoid",  "IAU_SUN",
                         "LT",       "EARTH",      CNVTOL,
                         gfstep_c,   gfrefn_c,     rpt,
                         gfrepi_c,   gfrepu_c,     gfrepf_c,
                         bail,       gfbail_c,     &cnfine,
                         &result                              );
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman   (JPL)
       W.L. Taber     (JPL)
       I.M. Underwood (JPL)
       L.S. Elson     (JPL)
       E.D. Wright    (JPL)
#### Version
       -CSPICE Version 1.0.0, 28-FEB-2009 (NJB) (LSE) (WLT) (IMU) (EDW)
#### Index_Entries
       GF update progress report
#### Link to routine gfrepu_c source file gfrepu_c.c

    Wed Jun  9 13:05:24 2010