1 /*
2 
3 -Procedure dafgh_c ( DAF, get handle )
4 
5 -Abstract
6 
7    Return (get) the handle of the DAF currently being searched.
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 
dafgh_c(SpiceInt * handle)48    void dafgh_c ( SpiceInt  * handle )
49 
50 /*
51 
52 -Brief_I/O
53 
54    Variable  I/O  Description
55    --------  ---  --------------------------------------------------
56    handle     O   Handle for current DAF.
57 
58 -Detailed_Input
59 
60    None.
61 
62 -Detailed_Output
63 
64    handle      is the handle for the current DAF (the handle
65                connected to the DAF that is currently being
66                actively searched).
67 
68 -Parameters
69 
70    None.
71 
72 -Exceptions
73 
74    1)  If this routine is called when no search is in progress in the
75        the current DAF, the error SPICE(DAFNOSEARCH) is signaled.
76 
77    2)  If the DAF whose handle is to be returned has actually been
78        closed, the error will be diagnosed by routines called by
79        this routine.
80 
81 -Files
82 
83    This function returns the handle of a DAF that is currently
84    being searched.
85 
86 -Particulars
87 
88    Under rare circumstances, it may be necessary to identify
89    the particular DAF that is being searched (such as when
90    the search is begun by one module and continued by another).
91 
92 -Examples
93 
94    Consider a program like the following, which examines the
95    individual arrays in a DAF and examines the contents of those
96    meeting certain criteria.
97 
98       #include "SpiceUsr.h"
99           ...
100       dafopw_c ( fname, &handle );
101       dafbfs_c ( handle );
102       daffna_c ( &found );
103 
104       while ( found )
105       {
106          check_segment ( status );
107 
108          if (  eqstr_c( status, "EXAMINE" )  )
109          {
110             examine_segment();
111          }
112 
113          daffna_c ( &found );
114       }
115 
116    The function check_segment, which assumes that a search is in
117    progress, gets the summary and name for the current array, and
118    uses them to decide whether the data in the array merit further
119    consideration.
120 
121       void check_segment ( status )
122         ...
123       dafgs_c ( sum  );
124       dafgn_c ( name );
125       dafus_c ( sum, nd, ni, dc, ic );
126         ...
127       [ set status ]
128         ...
129 
130 
131    The function examine_segment examines the data in
132    the array itself. In order to do do, it needs to have access
133    not only to the summary, but to the handle of the file
134    containing the array. This is provided by dafgh_c.
135 
136       void examine_segment()
137         ...
138       dafgs_c ( sum );
139       dafus_c ( sum, nd, ni, dc, ic );
140       dafgh_c ( &handle );
141 
142       dafgda_c ( handle, begin, end, data );
143         ...
144 
145 
146 -Restrictions
147 
148    None.
149 
150 -Literature_References
151 
152    NAIF Document 167.0, "Double Precision Array Files (DAF)
153    Specification and User's Guide"
154 
155 -Author_and_Institution
156 
157    N.J. Bachman    (JPL)
158    W.L. Taber      (JPL)
159    I.M. Underwood  (JPL)
160 
161 -Version
162 
163    -CSPICE Version 1.0.0, 19-JUL-2011 (NJB)
164 
165 -Index_Entries
166 
167    get daf handle
168 
169 -&
170 */
171 
172 { /* Begin dafgh_c */
173 
174 
175    /*
176    Participate in error tracing.
177    */
178    chkin_c ( "dafgh_c" );
179 
180 
181    dafgh_ ( (integer *) handle );
182 
183 
184    chkout_c ( "dafgh_c" );
185 
186 } /* End dafgh_c */
187