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 dasrfr_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

       dasrfr_c ( DAS, read file record )

       void dasrfr_c ( SpiceInt            handle,
                       SpiceInt            idwlen,
                       SpiceInt            ifnlen,
                       SpiceChar         * idword,
                       SpiceChar         * ifname,
                       SpiceInt          * nresvr,
                       SpiceInt          * nresvc,
                       SpiceInt          * ncomr,
                       SpiceInt          * ncomc  )

#### Abstract

       Return the contents of the file record of a specified DAS
       file.

#### Required_Reading

       DAS

#### Keywords

       DAS
       FILES
       UTILITY

#### Brief_I/O

       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       handle     I   DAS file handle.
       idwlen     I   Length of ID word string.
       ifnlen     I   Length of internal file name string.
       idword     O   ID word.
       ifname     O   DAS internal file name.
       nresvr     O   Number of reserved records in file.
       nresvc     O   Number of characters in use in reserved rec. area.
       ncomr      O   Number of comment records in file.
       ncomc      O   Number of characters in use in comment area.

#### Detailed_Input

       handle      is a file handle for a previously opened DAS file.

       idwlen      is the number of characters available in the output
                   ID word string. Space for the null terminator is
                   included in this count.

       ifnlen      is the number of characters available in the output
                   internal file name string. Space for the null
                   terminator is included in this count.

#### Detailed_Output

       idword      is the "ID word" contained in the first eight
                   characters of the file record.

       ifname      is the internal file name of the DAS file. The
                   maximum length of the internal file name is 60
                   characters.

       nresvr      is the number of reserved records in the DAS file
                   specified by `handle'.

       nresvc      is the number of characters in use in the reserved
                   record area of the DAS file specified by `handle'.

       ncomr       is the number of comment records in the DAS file
                   specified by `handle'.

       ncomc       is the number of characters in use in the comment area
                   of the DAS file specified by `handle'.

#### Parameters

       None.

#### Exceptions

       1)  If the file read attempted by this routine fails, an error is
           signaled by a routine in the call tree of this routine.

       2)  If the input file handle is invalid, an error is signaled by
           a routine in the call tree of this routine.

       3)  If a logical unit cannot be obtained for the file designated
           by `handle', an error is signaled by a routine in the call tree
           of this routine.

       4)  If the file's binary format is unrecognized, an error is
           signaled by a routine in the call tree of this routine.

       5)  If the file designated by `handle' has non-native binary format,
           and if any numeric components of the file record cannot be
           translated to native format, an error is signaled by a routine
           in the call tree of this routine.

       6)  If any of the `idword' or `ifname' output string pointers is
           null, the error SPICE(NULLPOINTER) is signaled.

       7)  If any of the `idword' or `ifname' output strings has length
           less than two characters, the error SPICE(STRINGTOOSHORT) is
           signaled, since the output string is too short to contain one
           character of output data plus a null terminator.

#### Files

       See the description of `handle' under -Detailed_Input.

#### Particulars

       This routine provides a convenient way of retrieving the
       information contained in the file record of a DAS file.

#### 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) Obtain the internal file name, comment record count, and comment
          character count of an existing DAS file.

          Example code begins here.

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

          int main()
          {
             /.
             Local constants
             ./
             #define IDWLEN         9
             #define IFNLEN         61
             #define FILSIZ         256

             /.
             Local variables
             ./
             SpiceChar               fname [FILSIZ];
             SpiceChar               idword[IDWLEN];
             SpiceChar               ifname[IFNLEN];

             SpiceInt                handle;
             SpiceInt                nresvr;
             SpiceInt                nresvc;
             SpiceInt                ncomr;
             SpiceInt                ncomc;

             /.
             Obtain the file name.
             ./
             prompt_c ( "Enter DAS file name > ", FILSIZ, fname );

             /.
             Open the file for reading.
             ./
             dasopr_c ( fname, &handle  );

             /.
             Retrieve the internal file name and print it.
             ./

             dasrfr_c ( handle, IDWLEN, IFNLEN, idword,
                        ifname, &nresvr, &nresvc, &ncomr, &ncomc );

             printf ( "Internal file name is:           %s\n", ifname     );
             printf ( "Number of comment records is:    %d\n", (int)ncomr );
             printf ( "Number of comment characters is: %d\n", (int)ncomc );

             return(0);
          }

          When this program was executed on a Mac/Intel/cc/64-bit
          platform, using the DSK file named phobos512.bds as input
          DAS file, the output was:

          Enter DAS file name > phobos512.bds
          Internal file name is:           phobos512.bds
          Number of comment records is:    10
          Number of comment characters is: 1390

#### Restrictions

       None.

#### Literature_References

       None.

#### Author_and_Institution

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

#### Version

       -CSPICE Version 1.0.1, 10-AUG-2021 (JDR)

           Updated -Exceptions section.

           Edited the header to comply with NAIF standard. Added example's
           solution.

       -CSPICE Version 1.0.0, 11-NOV-2016 (NJB) (KRG) (WLT)

#### Index_Entries

       read DAS file record
       read DAS internal file name

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

    Fri Dec 31 18:41:04 2021