spksub_c

Index Page spksub_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 spksub_c ( SpiceInt            handle,
                       SpiceDouble         descr[5],
                       ConstSpiceChar    * ident,
                       SpiceDouble         begin,
                       SpiceDouble         end,
                       SpiceInt            newh    )
#### Abstract
       Extract a subset of the data in an SPK segment into a
       separate segment.
#### Required_Reading
       SPK
       DAF
#### Keywords
       EPHEMERIS
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       handle     I   Handle of source segment.
       descr      I   Descriptor of source segment.
       ident      I   Identifier of source segment.
       begin      I   Beginning (initial epoch) of subset.
       end        I   End (final epoch) of subset.
       newh       I   Handle of new segment.
#### Detailed_Input
       handle,
       descr,
       ident       are the file handle assigned to a SPK file, the
                   descriptor for a segment within the file, and the
                   identifier for that segment. Together they determine
                   a complete set of ephemeris data, from which a
                   subset is to be extracted.

       begin,
       end         are the initial and final epochs (ephemeris time)
                   of the subset.

       newh        is the file handle assigned to the file in which
                   the new segment is to be written. The file must
                   be open for write access. newh and handle may refer
                   to the same file.
#### Detailed_Output
       See $Files section.
#### Parameters
       None.
#### Exceptions
       1) If the condition

             ALPHA  <  BEGIN  <  END  <  OMEGA
                    -         -       -

          is not satisfied (where ALPHA and OMEGA are the initial
          and final epochs of the segment respectively), the error
          SPICE(SPKNOTASUBSET) is signaled.

       2) If the segment type is not supported by the current
          version of spksub_c, the error SPICE(SPKTYPENOTSUPP)
          is signaled.

       3) If the segment ID string pointer is null, the error
          SPICE(NULLPOINTER) is signaled.

       4) If the segment ID string is empty, the error
          SPICE(EMPTYSTRING) is signaled.
#### Files
       A new segment, which contains a subset of the data in the
       segment specified by DESCR and HANDLE, is written to the SPK
       file attached to NEWH.
#### Particulars
       Sometimes, the segments in official source files---planetary
       Developmental Ephemeris (DE) files, archival spacecraft
       ephemeris files, and so on---contain more data than is needed
       by a particular user. spksub_c allows a user to extract from a
       segment the smallest amount of ephemeris data sufficient to
       cover a specific interval.

       The new segment is written with the same identifier as the
       original segment, and with the same descriptor, with the
       following components changed:

       1)  ALPHA and OMEGA (DCD(1) and DCD(2)) are assigned the values
           specified by BEGIN and END.

       2)  The beginning and ending segment addresses (ICD(5) and ICD(6))
           are, of course, changed to reflect the location of the new
           segment.
#### Examples
       In the following code fragment, the descriptor for each segment
       in a source SPK file is examined. For each segment that covers
       a target interval, the smallest possible subset is extracted into
       a custom SPK file.

       Assume that the source and custom files have been opened, for
       read and write access, with handles srchan and custhan respectively.

          #include "SpiceUsr.h"
               .
               .
               .
          dafbfs_c ( srchan );
          daffna_c ( &found );

          while ( found )
          {
             dafgs_c ( descr );
             dafus_c ( descr, 2, 6, dc, ic );

             if (  ( dc[0] <= begin ) && ( end <= dc[1] )  )
             {
                dafgn_c  ( ident );
                spksub_c ( srchan, descr, ident, begin, end, custhan );
             }

             daffna_c ( &found );
          }
#### Restrictions
       1) There is no way for spksub_c to verify that the descriptor and
          identifier are the original ones for the segment. Changing
          the descriptor can cause the data in the new segment to be
          evaluated incorrectly; changing the identifier can destroy
          the path from the data back to its original source.
#### Literature_References
       NAIF Document 168.0, "S- and P- Kernel (SPK) Specification and
       User's Guide"
#### Author_and_Institution
       K.R. Gehringer  (JPL)
       W.L. Taber      (JPL)
       N.J. Bachman    (JPL)
       J.M. Lynch      (JPL)
       R.E. Thurman    (JPL)
       I.M. Underwood  (JPL)
#### Version
       -CSPICE Version 1.0.0, 29-JUN-1999 (KRG)(WLT)(NJB)(JML)(RET)(IMU)
#### Index_Entries
       subset of spk file
#### Link to routine spksub_c source file spksub_c.c

    Thu Apr 16 08:59:15 2009