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 dafac_c

Table of contents

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

       dafac_c ( DAF add comments )

       void dafac_c ( SpiceInt      handle,
                      SpiceInt      n,
                      SpiceInt      buflen,
                      const void  * buffer  )

#### Abstract

       Add comments from a buffer of character strings to the comment
       area of a binary DAF file, appending them to any comments which
       are already present in the file's comment area.

#### Required_Reading

       DAF

#### Keywords

       FILES
       UTILITY

#### Brief_I/O

       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       handle     I    handle of a DAF opened with write access.
       n          I    Number of comments to put into the comment area.
       buflen     I    Length of elements
       buffer     I    Buffer of comments to put into the comment area.

#### Detailed_Input

       handle      is the file handle of a binary DAF which has been opened
                   with write access.

       n           is the number of rows in the array `buffer'. This is
                   also the number of comment lines in `buffer' that are to
                   be added to the comment area of the binary DAF attached
                   to `handle'.

       buffer      is a string buffer containing comments which are to be
                   added to the comment area of the binary DAF attached to
                   `handle'.  `buffer' should be declared by the caller has
                   follows:

                      SpiceChar    buffer[n][buflen];

                   Each row of the buffer should contain one comment line.

#### Detailed_Output

       None.

#### Parameters

       None.

#### Exceptions

       1)  If the number of comments to be added is not positive, the
           error SPICE(INVALIDARGUMENT) is signaled by a routine in the
           call tree of this routine.

       2)  If a non printing ASCII character is encountered in the
           comments, the error SPICE(ILLEGALCHARACTER) is signaled by a
           routine in the call tree of this routine.

       3)  If the binary DAF file attached to `handle' is not open with
           write access, an error is signaled by a routine in the call
           tree of this routine.

       4)  If the end of the comments cannot be found, i.e., the end of
           comments marker is missing on the last comment record, the
           error SPICE(BADCOMMENTAREA) is signaled by a routine in the
           call tree of this routine.

       5)  If the `buffer' input array pointer is null, the error
           SPICE(NULLPOINTER) is signaled.

       6)  If the `buffer' input array strings have length less than two
           characters, the error SPICE(EMPTYSTRING) is signaled.

#### Files

       See argument `handle' in -Detailed_Input.

#### Particulars

       A binary DAF contains a data area which is reserved for storing
       annotations or descriptive textual information about the data
       contained in a file. This area is referred to as the "comment
       area" of the file. The comment area of a DAF is a line oriented
       medium for storing textual information. The comment area preserves
       leading or embedded white space in the line(s) of text which are
       stored so that the appearance of the information will be unchanged
       when it is retrieved (extracted) at some other time. Trailing
       blanks, however, are NOT preserved, due to the way that character
       strings are represented in standard Fortran 77.

       This routine will take a buffer of text lines and add (append) them
       to the comment area of a binary DAF. If there are no comments in the
       comment area of the file, then space will be allocated and the text
       lines in `buffer' will be placed into the comment area. The text lines
       may contain only printable ASCII characters (decimal values 32 -
       126).

       There is NO maximum length imposed on the significant portion of a
       text line that may be placed into the comment area of a DAF. The
       maximum length of a line stored in the comment area should be
       reasonable, however, so that they may be easily extracted. A good
       maximum value for this would be 255 characters, as this can easily
       accommodate "screen width" lines as well as long lines which may
       contain some other form of information.

#### Examples

       The numerical results shown for this example 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 demonstrates how to append new comments to the
          comment area of a DAF file.

          Use the SPK kernel below as input DAF file for the program.

             earthstns_itrf93_201023.bsp

          Example code begins here.

          /.
             Program dafac_ex1
          ./
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main( )
          {

             /.
             Local parameters
             ./
             #define KERNEL       "earthstns_itrf93_201023.bsp"
             #define BUFFSZ       25
             #define CMTSIZ       7
             #define LINLEN       1000

             /.
             Local variables.
             ./
             SpiceChar            buffer [BUFFSZ][LINLEN];

             SpiceInt             handle;
             SpiceInt             i;
             SpiceInt             n;

             SpiceBoolean         done;

             /.
             Set the new comments to be added to the DAF file.
             ./
             SpiceChar            newcmt [CMTSIZ][LINLEN] = {
                "================== NEW COMMENTS ==================",
                "",
                "   New comments can be appended to the end of the",
                "   comment area of a DAF file, with a single",
                "   operation.",
                "",
                "================ END NEW COMMENTS ================" };

             /.
             Open a DAF for write. Return a `handle' referring to the
             file.
             ./
             dafopw_c ( KERNEL, &handle );

             /.
             Print the end of comment area from the DAF file.
             (Maximum 15 lines.)
             ./
             done = SPICEFALSE;

             while ( ! done )
             {
                dafec_c ( handle, 15, LINLEN, &n, buffer, &done );

                if ( done )
                {

                   printf( "End of comment area of input DAF file "
                           "(max. 15 lines):\n" );
                   printf( "-------------------------------"
                           "-------------------------------\n" );

                   for ( i = 0; i < n; i++ )
                   {
                      printf( "%s\n", buffer[i] );
                   }

                   printf( "-------------------------------"
                           "-------------------------------\n" );

                }
             }

             /.
             Append the new comments to the DAF file.
             ./
             dafac_c ( handle, CMTSIZ, LINLEN, newcmt );

             /.
             Safely close the DAF.
             ./
             dafcls_c ( handle );

             /.
             Check if the comments have indeed appended.

             Open a DAF for read.
             ./
             dafopr_c ( KERNEL, &handle );
             done = SPICEFALSE;

             while ( ! done )
             {
                dafec_c ( handle, BUFFSZ, LINLEN, &n, buffer, &done );

                if ( done )
                {

                   printf( "End of comment area of input DAF file "
                           "(max. 25 lines):\n" );
                   printf( "-------------------------------"
                           "-------------------------------\n" );

                   for ( i = 0; i < n; i++ )
                   {
                      printf( "%s\n", buffer[i] );
                   }

                   printf( "-------------------------------"
                           "-------------------------------\n" );

                }
             }

             /.
             Safely close the DAF.
             ./
             dafcls_c ( handle );

             return ( 0 );
          }

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

          End of comment area of input DAF file (max. 15 lines):
          --------------------------------------------------------------
             DSS-65_DXYZ       =    (    -0.0100          0.0242          0.0156***
             DSS-65_TOPO_EPOCH =       @2020-OCT-23/00:00
             DSS-65_UP         =       'Z'
             DSS-65_NORTH      =       'X'

          \begintext
          --------------------------------------------------------------
          End of comment area of input DAF file (max. 25 lines):
          --------------------------------------------------------------
             DSS-65_DXYZ       =    (    -0.0100          0.0242          0.0156***
             DSS-65_TOPO_EPOCH =       @2020-OCT-23/00:00
             DSS-65_UP         =       'Z'
             DSS-65_NORTH      =       'X'

          \begintext
          ================== NEW COMMENTS ==================

             New comments can be appended to the end of the
             comment area of a DAF file, with a single
             operation.

          ================ END NEW COMMENTS ================
          --------------------------------------------------------------

          Warning: incomplete output. 2 lines extended past the right
          margin of the header and have been truncated. These lines are
          marked by "***" at the end of each line.

#### Restrictions

       1)  This routine uses constants that are specific to the ASCII
           character sequence. The results of using this routine with
           a different character sequence are unpredictable.

       2)  This routine is only used to extract records on environments
           whose characters are a single byte in size. Updates to this
           routine and routines in its call tree may be required to
           properly handle other cases.

#### Literature_References

       None.

#### Author_and_Institution

       N.J. Bachman        (JPL)
       J. Diaz del Rio     (ODC Space)
       K.R. Gehringer      (JPL)

#### Version

       -CSPICE Version 1.1.0, 25-NOV-2021 (JDR)

           Edited the header to comply with NAIF standard. Added complete code
           example.

           Changed input argument name "lenvals" to "buflen" for
           consistency with other routines.

       -CSPICE Version 1.0.0, 16-NOV-2006 (NJB) (KRG)

#### Index_Entries

       add comments to a binary DAF file
       append comments to a DAF file comment area

#### Link to routine dafac_c source file dafac_c.c

    Fri Dec 31 18:41:03 2021