1 /* 2 3 -Procedure dlabbs_c ( DLA, begin backward search ) 4 5 -Abstract 6 7 Begin a backward segment search in a DLA file. 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 DAS 37 DLA 38 39 -Keywords 40 41 DAS 42 DLA 43 FILES 44 45 */ 46 47 #include "SpiceUsr.h" 48 #include "SpiceZfc.h" 49 50 dlabbs_c(SpiceInt handle,SpiceDLADescr * descr,SpiceBoolean * found)51 void dlabbs_c ( SpiceInt handle, 52 SpiceDLADescr * descr, 53 SpiceBoolean * found ) 54 /* 55 56 -Brief_I/O 57 58 Variable I/O Description 59 -------- --- -------------------------------------------------- 60 handle I Handle of open DLA file. 61 descr O Descriptor of last segment in DLA file. 62 found O Flag indicating whether a segment was found. 63 64 -Detailed_Input 65 66 handle is the integer handle associated with the file to be 67 searched. This handle is used to identify the file in 68 subsequent calls to other DLA or DAS routines. 69 70 -Detailed_Output 71 72 descr is the descriptor of the last DLA segment in the 73 file associated with `handle'. 74 75 `descr' is valid only if the output argument `found' is 76 SPICETRUE. 77 78 79 found is a logical flag indicating whether a segment was 80 found. `found' has the value SPICETRUE if the file 81 contains at least one segment; otherwise `found' is 82 SPICEFALSE. 83 84 -Parameters 85 86 None. 87 88 -Exceptions 89 90 1) If the input file handle is invalid, the error will be 91 diagnosed by routines in the call tree of this routine. 92 93 2) If an error occurs while reading the DLA file, the error 94 will be diagnosed by routines in the call tree of this 95 routine. 96 97 3) If the input descriptor is invalid, this routine will 98 fail in an unpredictable manner. 99 100 -Files 101 102 See description of input argument `handle'. 103 104 -Particulars 105 106 DLA files are built using the DAS low-level format; DLA files are 107 a specialized type of DAS file in which data are organized as a 108 doubly linked list of segments. Each segment's data belong to 109 contiguous components of character, double precision, and integer 110 type. 111 112 This routine supports backward traversal of a DLA file's segment 113 list. Note that it is not necessary to call this routine to 114 conduct a backward traversal; all that is necessary is to have 115 access to the last descriptor in the file, which this routine 116 provides. 117 118 -Examples 119 120 1) Open a DLA file for read access, traverse the segment 121 list from back to front, and display segment address 122 and size attributes. 123 124 125 #include "SpiceUsr.h" 126 #include "SpiceDLA.h" 127 #include <stdio.h> 128 129 int main() 130 { 131 /. 132 Local parameters 133 ./ 134 #define FILSIZ 256 135 136 /. 137 Local variables 138 ./ 139 SpiceBoolean found; 140 SpiceChar fname [ FILSIZ ]; 141 SpiceDLADescr current; 142 SpiceDLADescr descr; 143 SpiceInt handle; 144 SpiceInt segno; 145 146 /. 147 Prompt for the name of the file to search. 148 ./ 149 prompt_c ( "Name of DLA file > ", FILSIZ, fname ); 150 151 /. 152 Open the DLA file for read access. Since DLA 153 files use the DAS architecture, we can use DAS 154 routines to open and close the file. 155 ./ 156 dasopr_c ( fname, &handle ); 157 158 /. 159 Begin a backward search. Let `descr' contain 160 the descriptor of the last segment. 161 ./ 162 segno = 0; 163 164 dlabbs_c ( handle, &descr, &found ); 165 166 while ( found ) 167 { 168 /. 169 Display the contents of the current segment 170 descriptor. 171 ./ 172 173 ++segno; 174 175 printf ( "\n" 176 "Segment number (offset from end of file) = %d\n" 177 "\n" 178 " Backward segment pointer = %d\n" 179 " Forward segment pointer = %d\n" 180 " Integer component base address = %d\n" 181 " Integer component size = %d\n" 182 " D.p. component base address = %d\n" 183 " D.p. component size = %d\n" 184 " Character component base address = %d\n" 185 " Character component size = %d\n" 186 "\n", 187 (int)(segno), 188 (int)(descr.bwdptr), 189 (int)(descr.fwdptr), 190 (int)(descr.ibase), 191 (int)(descr.isize), 192 (int)(descr.dbase), 193 (int)(descr.dsize), 194 (int)(descr.cbase), 195 (int)(descr.csize) ); 196 197 /. 198 Find the previous segment. 199 ./ 200 current = descr; 201 202 dlafps_c ( handle, ¤t, &descr, &found ); 203 } 204 205 /. 206 Close the file using the DAS close routine. 207 ./ 208 dascls_c ( handle ); 209 210 return ( 0 ); 211 } 212 213 214 -Restrictions 215 216 None. 217 218 -Literature_References 219 220 None. 221 222 -Author_and_Institution 223 224 N.J. Bachman (JPL) 225 226 -Version 227 228 -CSPICE Version 1.0.0, 10-JAN-2017 (NJB) 229 230 -Index_Entries 231 232 begin backward search in dla file 233 234 -& 235 */ 236 237 { /* Begin dlabbs_c */ 238 239 240 /* 241 Local variables 242 */ 243 integer fDLADescr [ SPICE_DLA_DSCSIZ ]; 244 245 logical fnd; 246 247 248 /* 249 Participate in error tracing. 250 */ 251 chkin_c ( "dlabbs_c" ); 252 253 254 dlabbs_ ( (integer *) &handle, 255 (integer *) fDLADescr, 256 (logical *) &fnd ); 257 258 /* 259 Set the output SpiceBoolean found flag. 260 */ 261 262 *found = (SpiceBoolean) fnd; 263 264 265 /* 266 If a segment was found, set the output descriptor. 267 */ 268 if ( *found ) 269 { 270 /* 271 Assign values to the members of the output descriptor. 272 */ 273 descr->bwdptr = fDLADescr[SPICE_DLA_BWDIDX]; 274 descr->fwdptr = fDLADescr[SPICE_DLA_FWDIDX]; 275 descr->ibase = fDLADescr[SPICE_DLA_IBSIDX]; 276 descr->isize = fDLADescr[SPICE_DLA_ISZIDX]; 277 descr->dbase = fDLADescr[SPICE_DLA_DBSIDX]; 278 descr->dsize = fDLADescr[SPICE_DLA_DSZIDX]; 279 descr->cbase = fDLADescr[SPICE_DLA_CBSIDX]; 280 descr->csize = fDLADescr[SPICE_DLA_CSZIDX]; 281 } 282 283 chkout_c ( "dlabbs_c" ); 284 285 } /* End dlabbs_c */ 286