1 /*
2 
3 -Procedure dafrfr_c ( DAF, read file record )
4 
5 -Abstract
6 
7    Read the contents of the file record of a DAF.
8 
9 -Disclaimer
10 
11    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
12    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
13    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
14    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
15    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
16    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
17    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
18    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
19    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
20    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
21 
22    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
23    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
24    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
25    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
26    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
27    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
28 
29    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
30    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
31    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
32    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
33 
34 -Required_Reading
35 
36    DAF
37 
38 -Keywords
39 
40    FILES
41 
42 */
43 
44    #include "SpiceUsr.h"
45    #include "SpiceZfc.h"
46    #include "SpiceZst.h"
47 
dafrfr_c(SpiceInt handle,SpiceInt lenout,SpiceInt * nd,SpiceInt * ni,SpiceChar * ifname,SpiceInt * fward,SpiceInt * bward,SpiceInt * free)48    void dafrfr_c ( SpiceInt     handle,
49                    SpiceInt     lenout,
50                    SpiceInt   * nd,
51                    SpiceInt   * ni,
52                    SpiceChar  * ifname,
53                    SpiceInt   * fward,
54                    SpiceInt   * bward,
55                    SpiceInt   * free    )
56 
57 /*
58 
59 -Brief_I/O
60 
61    Variable  I/O  Description
62    --------  ---  --------------------------------------------------
63    handle     I   Handle of an open DAF file.
64    lenout     I   Available room in the output string `ifname'.
65    nd         O   Number of double precision components in summaries.
66    ni         O   Number of integer components in summaries.
67    ifname     O   Internal file name.
68    fward      O   Forward list pointer.
69    bward      O   Backward list pointer.
70    free       O   Free address pointer.
71 
72 -Detailed_Input
73 
74    handle         is the handle assigned to a DAF file opened for
75                   reading.
76 
77    lenout         is the maximum number of characters that can be
78                   accommodated in the output string `ifname'. This count
79                   includes room for the terminating null character.
80                   DAF internal file names may contain up to 60
81                   characters, so lenout normally should be set to 61.
82 
83 -Detailed_Output
84 
85    nd,
86    ni          are the numbers of double precision and integer
87                components, respectively, in each array summary in
88                the specified file.
89 
90    ifname      is the internal file name stored in the first
91                (or file) record of the specified file. `ifname'
92                should be declared with the length specified by
93                `lenout'.
94 
95    fward       is the forward list pointer. This points to the
96                first summary record in the file. (Records between
97                the first record and the first summary record are
98                reserved when the file is created, and are invisible
99                to DAF routines.)
100 
101                DAF list pointers are actually Fortran record numbers,
102                and as such, start at one.
103 
104    bward       is the backward list pointer. This points
105                to the final summary record in the file.
106 
107 
108    free        is the free address pointer. This contains the
109                first free address in the file. (That is, the
110                initial address of the next array to be added
111                to the file.)
112 
113                `free' is a DAF address; for compatiblity with
114                SPICELIB, the range of DAF addresses starts at 1.
115 
116 -Parameters
117 
118    None.
119 
120 -Exceptions
121 
122    1) If the handle passed to this routine is not the handle of an
123       open DAF file, the error will be signaled by a routine called
124       by this routine.
125 
126    2) If the specified DAF file is not open for read access, the
127       error will be diagnosed by a routine called by this routine.
128 
129    3) If the specified record cannot (for some reason) be read,
130       the error SPICE(DAFFRNOTFOUND) is signaled.
131 
132 -Files
133 
134    The input `handle' should refer to a DAF file open for read
135    or write access.
136 
137 -Particulars
138 
139    The file record of a DAF is the only record that contains
140    any global information about the file. This record is created
141    when the file is created, and is updated only when new arrays
142    are added.
143 
144    Like character records, file records are not buffered.
145 
146 -Examples
147 
148    In the following example, the file record of a DAF is read
149    to determine the first free address in the file.
150 
151       #include <stdio.h>
152       #include "SpiceUsr.h"
153 
154       int main ()
155          {
156          #define IFNLEN   61
157 
158          SpiceChar               ifname[IFNLEN];
159 
160          SpiceInt                bward;
161          SpiceInt                free;
162          SpiceInt                fward;
163          SpiceInt                handle;
164          SpiceInt                nd;
165          SpiceInt                ni;
166          SpiceChar             * kernel = "/kernels/gen/spk/de421.bsp";
167 
168          dafopr_c ( kernel, &handle );
169 
170          dafrfr_c ( handle, IFNLEN, &nd, &ni, ifname, &fward, &bward, &free );
171 
172          printf ( "First free DAF address is %d.\n", (int)free );
173 
174         /.
175          Safely close the DAF.
176          ./
177          dafcls_c ( handle  );
178 
179          return ( 0 );
180          }
181 
182    The program outputs:
183 
184       First free DAF address is 2098645.
185 
186 -Restrictions
187 
188    None.
189 
190 -Literature_References
191 
192    None.
193 
194 -Author_and_Institution
195 
196 
197    N.J. Bachman    (JPL)
198    K.R. Gehringer  (JPL)
199    I.M. Underwood  (JPL)
200 
201 -Version
202 
203    -CSPICE Version 1.0.1, 28-JUN-2016 (EDW)
204 
205       Edit to Example code, SpiceInts output as ints using
206       explicit casting.
207 
208    -CSPICE Version 1.0.0, 17-JUN-2009 (NJB) (KRG) (IMU)
209 
210 -Index_Entries
211 
212    read daf file record
213 
214 -&
215 */
216 
217 { /* Begin dafrfr_c */
218 
219    /*
220    Participate in error tracing.
221    */
222    chkin_c ( "dafrfr_c" );
223 
224    dafrfr_ ( (integer *) &handle,
225              (integer *) nd,
226              (integer *) ni,
227              (char    *) ifname,
228              (integer *) fward,
229              (integer *) bward,
230              (integer *) free,
231              (ftnlen   ) lenout-1 );
232 
233    /*
234    Convert the internal file name to a C-style string.
235    */
236    F2C_ConvertStr ( lenout, ifname );
237 
238 
239    chkout_c ( "dafrfr_c" );
240 
241 } /* End dafrfr_c */
242 
243