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