1 /* 2 3 -Procedure gnpool_c (Get names of kernel pool variables) 4 5 -Abstract 6 7 Return names of kernel variables matching a specified template. 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 KERNEL 37 38 -Keywords 39 40 CONSTANTS 41 FILES 42 43 */ 44 45 #include <stdlib.h> 46 #include "SpiceUsr.h" 47 #include "SpiceZfc.h" 48 #include "SpiceZst.h" 49 #include "SpiceZmc.h" 50 51 gnpool_c(ConstSpiceChar * name,SpiceInt start,SpiceInt room,SpiceInt lenout,SpiceInt * n,void * kvars,SpiceBoolean * found)52 void gnpool_c ( ConstSpiceChar * name, 53 SpiceInt start, 54 SpiceInt room, 55 SpiceInt lenout, 56 SpiceInt * n, 57 void * kvars, 58 SpiceBoolean * found ) 59 /* 60 61 -Brief_I/O 62 63 VARIABLE I/O DESCRIPTION 64 -------- --- -------------------------------------------------- 65 name I Template that names should match. 66 start I Index of first matching name to retrieve. 67 room I The largest number of values to return. 68 lenout I Length of strings in output array kvars. 69 n O Number of values returned for name. 70 kvars O Kernel pool variables whose names match name. 71 found O True if there is at least one match. 72 73 -Detailed_Input 74 75 name is a matchi_c template which will be used when searching 76 for variable names in the kernel pool. The characters 77 '*' and '%' are used for the wild string and wild 78 characters respectively. For details of string 79 pattern matching see the header of the routine matchi_c. 80 'name' is restricted to a length of 32 characters or less. 81 82 start is the index of the first variable name to return that 83 matches the name template. The matching names are 84 assigned indices ranging from 0 to NVAR-1, where NVAR is 85 the number of matching names. The index of a name does 86 not indicate how it compares alphabetically to another 87 name. 88 89 If start is less than 0, it will be treated as 0. If 90 start is greater than the total number of matching 91 variable names, no values will be returned and N will 92 be set to zero. However, found will still be set to 93 SPICETRUE. 94 95 96 room is the maximum number of variable names that should 97 be returned for this template. If room is less than 1 98 the error SPICE(BADARRAYSIZE) will be signaled. 99 100 lenout is the length of strings in the output array kvars. This 101 length includes room for the terminating null in each 102 string. To ensure that the output names are not 103 truncated, lenout should be at least 33. 104 105 106 -Detailed_Output 107 108 n is the number of variable names matching name that are 109 returned. It will always be less than or equal to 110 room. 111 112 If no variable names match name, n is set to zero. 113 114 115 kvars is an array of kernel pool variables whose names match 116 the template name and which have indices ranging from 117 start to start+n-1. 118 119 Note that in general the names returned in kvars are 120 not sorted. 121 122 If no variables match name, no values are assigned to 123 the elements of kvars. 124 125 If the length of kvars is less than the length of the 126 variable names, the values returned will be truncated 127 on the right. 128 129 The declaration of kvars should be equivalent to 130 131 SpiceChar kvars [room][lenout]; 132 133 134 found is SPICETRUE if the some variable name in the kernel pool 135 matches name, SPICEFALSE if it is not. 136 137 -Parameters 138 139 None. 140 141 -Exceptions 142 143 1) If the value of room is less than one, the error 144 SPICE(BADARRAYSIZE) is signaled. 145 146 2) If kvars has declared length less than the size (including 147 terminating null character) of a name to be returned, the name 148 will be truncated on the right. The parameter MAXCHR sets 149 the maximum stored size of string variables. 150 151 3) If either the input or output string pointers are null, the error 152 SPICE(NULLPOINTER) will be signaled. 153 154 4) If the input string has length zero, the error SPICE(EMPTYSTRING) 155 will be signaled. 156 157 5) The caller must pass a value indicating the length of the output 158 string. If this value is not at least 2, the error 159 SPICE(STRINGTOOSHORT) will be signaled. 160 161 6) The error 'SPICE(BADVARNAME)' signals if the kernel pool 162 variable name length exceeds 32. 163 164 -Files 165 166 None. 167 168 -Particulars 169 170 This routine provides the user interface for retrieving the names 171 of kernel pool variables. This interface allows you to retrieve 172 the names matching a template via multiple accesses. Under some 173 circumstances this alleviates the problem of having to know in 174 advance the maximum amount of space needed to accommodate all 175 matching names. 176 177 However, this method of access does come with a price. It is 178 always more efficient to retrieve all of the data associated with 179 a kernel pool variable in one call than it is to retrieve it in 180 sections. The parameter MAXVAR defines the upper bound on the 181 number of possible matching names. 182 183 -Examples 184 185 186 The following code demonstrates how the names of kernel pool 187 variables matching a template can be retrieved in pieces. 188 189 #include <stdio.h> 190 #include "SpiceUsr.h" 191 192 int main() 193 { 194 195 #define ROOM 3 196 #define LNSIZE 81 197 #define TEMPLATE "BODY599*" 198 199 SpiceBoolean found; 200 201 SpiceChar kvars [ROOM][LNSIZE]; 202 203 SpiceInt i; 204 SpiceInt n; 205 SpiceInt start; 206 207 /. 208 Load the data in the file "typical.ker" into the kernel pool. 209 ./ 210 ldpool_c ( "typical.ker" ); 211 212 /. 213 Print the names of kernel variables that match TEMPLATE. 214 ./ 215 216 start = 0; 217 218 gnpool_c ( TEMPLATE, start, ROOM, LNSIZE, &n, kvars, &found ); 219 220 if ( !found ) 221 { 222 printf ( "There are no matching variables in the " 223 "kernel pool\n" ); 224 } 225 else 226 { 227 printf ( "Kernel pool variables:\n" 228 "\n" ); 229 230 for ( i = 0; i < n; i++ ) 231 { 232 printf ( " %s\n", kvars[i] ); 233 } 234 235 while ( n == ROOM ) 236 { 237 start += n; 238 239 gnpool_c ( TEMPLATE, start, ROOM, LNSIZE, 240 &n, kvars, &found ); 241 242 for ( i = 0; i < n; i++ ) 243 { 244 printf ( " %s\n", kvars[i] ); 245 } 246 } 247 } 248 /. 249 This is the end of the if block following the first gnpool_c 250 call. 251 ./ 252 253 return ( 0 ); 254 } 255 256 257 -Restrictions 258 259 None. 260 261 -Literature_References 262 263 None. 264 265 -Author_and_Institution 266 267 N.J. Bachman (JPL) 268 W.L. Taber (JPL) 269 270 -Version 271 272 -CSPICE Version 1.1.1, 10-FEB-2010 (EDW) 273 274 Added mention of the restriction on kernel pool variable 275 names to 32 characters or less. 276 277 -CSPICE Version 1.1.0, 18-MAY-2001 (WLT) 278 279 Added a cast to (char *) in the call to F2C_ConvertStrArr 280 281 -CSPICE Version 1.0.0, 08-JUN-1999 (NJB) (WLT) 282 283 -Index_Entries 284 285 return names of kernel pool variables matching a template 286 287 -& 288 */ 289 290 { /* Begin gnpool_c */ 291 292 293 294 /* 295 Local variables 296 */ 297 SpiceChar * endptr; 298 SpiceChar * strptr; 299 300 SpiceInt fstart; 301 SpiceInt i; 302 303 logical fnd; 304 305 306 307 /* 308 Participate in error tracing. 309 */ 310 chkin_c ( "gnpool_c" ); 311 312 313 /* 314 Check the input string to make sure the pointer is non-null and 315 the string is non-empty. 316 */ 317 CHKFSTR ( CHK_STANDARD, "gnpool_c", name ); 318 319 320 /* 321 Check the output string array to make sure the pointer is non-null 322 and that each string has room for at least one character plus a null 323 terminator. 324 */ 325 CHKOSTR ( CHK_STANDARD, "gnpool_c", kvars, lenout ); 326 327 328 /* 329 Call the f2c'd routine. First map the start index to the Fortran 330 style range of 1 : #of matching strings. 331 */ 332 333 fstart = start + 1; 334 335 gnpool_ ( ( char * ) name, 336 ( integer * ) &fstart, 337 ( integer * ) &room, 338 ( integer * ) n, 339 ( char * ) kvars, 340 ( logical * ) &fnd, 341 ( ftnlen ) strlen(name), 342 ( ftnlen ) lenout-1 ); 343 344 /* 345 Convert the output array from Fortran to C style. 346 */ 347 F2C_ConvertStrArr ( *n, lenout, (char * ) kvars ); 348 349 /* 350 Eliminate any trailing white space left by F2C_ConvertStrArr. 351 */ 352 353 for ( i = 0; i < *n; i++ ) 354 { 355 strptr = ( (SpiceChar *) kvars ) + i*lenout; 356 endptr = strptr + lenout - 2; 357 358 if ( *endptr == BLANK ) 359 { 360 /* 361 The last data character in this string is blank, so there is 362 trailing white space to remove. Treat the first lenout-1 363 characters of the string as a Fortran string to be converted. 364 The length expected by F2C_ConvertStr is the C string length, 365 so we pass in lenout. 366 */ 367 F2C_ConvertStr ( lenout, strptr ); 368 } 369 } 370 371 /* 372 Set the SpiceBoolean found flag. 373 */ 374 375 *found = fnd; 376 377 378 chkout_c ( "gnpool_c" ); 379 380 } /* End gnpool_c */ 381