Procedure

     PCK03E ( PCK, end a type 3 segment )

     SUBROUTINE PCK03E ( HANDLE )

Abstract

     End the type 03 PCK segment currently being written to the binary
     PCK file associated with HANDLE. See also PCK03B and PCK03A.

Required_Reading

     PCK

Keywords

     PCK

Declarations

     IMPLICIT NONE

     INTEGER               HANDLE

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   The handle of a binary PCK file open for writing.

Detailed_Input

     HANDLE   is the file handle of a binary PCK file that has been
              opened for writing and to which a type 03 PCK segment is
              being written.

Detailed_Output

     None.

     The segment in the PCK file associated with HANDLE will
     be ended, making the addition of the data permanent.

     See the $Particulars section for details about the
     structure of a type 03 PCK segment.

Parameters

     None.

Exceptions

     1)  If there is no segment being written to the file associated
         with HANDLE, an error is signaled by a routine in the call
         tree of this routine.

Files

     See the argument HANDLE.

Particulars

     This routine ends a type 03 PCK segment that is being written to
     the binary PCK file associated with HANDLE. Ending the PCK segment
     is a necessary step in the process of making the data a permanent
     part of the binary PCK file.

     This routine is one of a set of three routines for creating and
     adding data to type 03 PCK segments. These routines are:

        PCK03B: Begin a type 03 PCK segment. This routine must be
                called before any data may be added to a type 03
                segment.

        PCK03A: Add data to a type 03 PCK segment. This routine may be
                called any number of times after a call to PCK03B to
                add type 03 records to the PCK segment that was
                started.

        PCK03E: End a type 03 PCK segment. This routine is called to
                make the type 03 segment a permanent addition to the
                PCK file. Once this routine is called, no further type
                03 records may be added to the segment. A new segment
                must be started.

     A type 03 PCK segment consists of coefficient sets for fixed order
     Chebyshev polynomials over consecutive time intervals, where the
     time intervals need not all be of the same length. The Chebyshev
     polynomials represent the orientation of a body specified relative
     to an inertial frame by the angles RA, DEC, W and body fixed
     angular rates for each axis of the body fixed coordinate system
     defined by RA, DEC, and W. All of the angles and the angular rates
     of the axes are given in degrees.

     The orientation data supplied to the type 03 PCK writer is packed
     into an array as a sequence of logical records,

        -----------------------------------------------------
        | Record 1 | Record 2 | ... | Record N-1 | Record N |
        -----------------------------------------------------

     with each record has the following format.

           ------------------------------------------------
           |  The midpoint of the approximation interval  |
           ------------------------------------------------
           |  The radius of the approximation interval    |
           ------------------------------------------------
           |  CHBDEG+1 coefficients for RA                |
           ------------------------------------------------
           |  CHBDEG+1 coefficients for DEC               |
           ------------------------------------------------
           |  CHBDEG+1 coefficients for W                 |
           ------------------------------------------------
           |  CHBDEG+1 coefficients for the X-axis rate   |
           ------------------------------------------------
           |  CHBDEG+1 coefficients for the Y-axis rate   |
           ------------------------------------------------
           |  CHBDEG+1 coefficients for the Z-axis rate   |
           ------------------------------------------------

Examples

     Assume we have the following for each of the examples that
     follow.

        HANDLE   is the handle of a PCK file opened with write
                 access.

        SEGID    is a character string of no more than 40 characters
                 which provides a pedigree for the data in the PCK
                 segment.

        BODY     is the SPICE ID code for the body whose orientation
                 data is to be placed into the file.

        REFFRM   is the name of the SPICE inertial reference frame
                 the orientation data is relative to.

        FIRST    is the starting epoch, in seconds past J2000, for
                 the orientation data to be placed into the segment.

        LAST     is the ending epoch, in seconds past J2000, for
                 the orientation data to be placed into the segment.

     Example 1:

        For this example, we also assume that:

           N        is the number of type 03 records that we want to
                    put into a segment in PCK file.

           RECRDS   contains N type 03 records packaged for the PCK
                    file.

           ETSTRT   contains the initial epochs for each of the
                    records contained in RECRDS, where

                       ETSTRT(I) < ETSTRT(I+1), I = 1, N-1

                       ETSTRT(1) <= FIRST, ETSTRT(N) < LAST

                       ETSTRT(I+1), I = 1, N-1, is the ending epoch for
                       record I as well as the initial epoch for record
                       I+1.

        Then the following code fragment demonstrates how to create a
        type 03 PCK segment if all of the data for the segment is
        available at one time.

        C
        C     Begin the segment.
        C
              CALL PCK03B ( HANDLE, SEGID, BODY, REFFRM,
             .              FIRST,  LAST,  CHBDEG        )
        C
        C     Add the data to the segment all at once.
        C
              CALL PCK03A ( HANDLE, N, RECRDS, ETSTRT )
        C
        C     End the segment, making the segment a permanent addition
        C     to the PCK file.
        C
              CALL PCK03E ( HANDLE )

     Example 2:

        In this example we want to add type O3 PCK records, as
        described above in the $Particulars section, to the segment
        being written as they are generated. The ability to write the
        records in this way is useful if computer memory is limited. It
        may also be convenient from a programming perspective to write
        the records one at a time.

        For this example, assume that we want to generate N type 03 PCK
        records, one for each of N time intervals, writing them all to
        the same segment in a PCK file. Let

           N        be the number of type 03 records that we want to
                    generate and put into a segment in an PCK file.

           RECORD   be an array with enough room to hold a single type
                    03 record, i.e. RECORD should have dimension at
                    least 6 * (CHBDEG + 1 ) + 2.

           START    be an array of N times that are the beginning
                    epochs for each of the intervals of interest. The
                    times should be in increasing order and the start
                    time for the first interval should equal the
                    starting time for the segment.

                       START(I) < START(I+1), I = 1, N-1

                       START(1) = FIRST

           STOP     be an array of N times that are the ending epochs
                    for each of the intervals of interest. The times
                    should be in increasing order and the stop time for
                    interval I should equal the start time for interval
                    I+1, i.e., we want to have continuous coverage in
                    time across all of the records. Also, the stop time
                    for the last interval should equal the ending time
                    for the segment.

                       STOP(I) < STOP(I+1), I = 1, N-1

                       STOP(I) = START(I+1), I = 1, N-1

                       STOP(N) = LAST

           GENREC( TIME1, TIME2, RECORD )

                    be a subroutine that generates a type 03 PCK record
                    for a time interval specified by TIME1 and TIME2.

        Then the following code fragment demonstrates how to create a
        type 03 PCK segment if all of the data for the segment is not
        available at one time.

        C
        C     Begin the segment.
        C
              CALL PCK03B ( HANDLE, SEGID, DESCR, CHBDEG )

        C
        C     Generate the records and write them to the segment in the
        C     PCK file one at at time.
        C
              DO I = 1, N

                 CALL GENREC ( START(I), STOP(I), RECORD )
                 CALL PCK03A ( HANDLE, 1, RECORD, START(I) )

              END DO

        C
        C     End the segment, making the segment a permanent addition
        C     to the PCK file.
        C
              CALL PCK03E ( HANDLE )

Restrictions

     1)  The type 03 binary PCK segment being closed must have been
         started by the routine PCK03B, the routine which begins a type
         03 PCK segment.

Literature_References

     None.

Author_and_Institution

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

Version

    SPICELIB Version 1.0.2, 03-JUN-2021 (JDR)

        Edited the header to comply with NAIF standard. Added entry #1
        to $Exceptions section.

    SPICELIB Version 1.0.1, 03-JAN-2014 (EDW)

        Minor edits to $Procedure; clean trailing whitespace.
        Corrected order of header sections to conform to NAIF
        standard.

    SPICELIB Version 1.0.0, 06-MAR-1995 (KRG)