| gnpool_c |
|
Table of contents
Procedure
gnpool_c (Get names of kernel pool variables)
void gnpool_c ( ConstSpiceChar * name,
SpiceInt start,
SpiceInt room,
SpiceInt cvalen,
SpiceInt * n,
void * cvals,
SpiceBoolean * found )
AbstractReturn names of kernel variables matching a specified template. Required_ReadingKERNEL KeywordsCONSTANTS FILES Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- name I Template that names should match. start I Index of first matching name to retrieve. room I The largest number of values to return. cvalen I Length of strings in output array cvals. n O Number of values returned for name. cvals O Kernel pool variables whose names match name. found O SPICETRUE if there is at least one match. Detailed_Inputname is a matchi_c template which will be used when searching for variable names in the kernel pool. The characters '*' and '%' are used for the wild string and wild characters respectively. For details of string pattern matching see the header of the routine matchi_c. 'name' is restricted to a length of 32 characters or less. start is the index of the first variable name to return that matches the name template. The matching names are assigned indices ranging from 0 to NVAR-1, where NVAR is the number of matching names. The index of a name does not indicate how it compares alphabetically to another name. If start is less than 0, it will be treated as 0. If start is greater than the total number of matching variable names, no values will be returned and N will be set to zero. However, found will still be set to SPICETRUE. room is the maximum number of variable names that should be returned for this template. If room is less than 1 the error SPICE(BADARRAYSIZE) will be signaled. cvalen is the length of strings in the output array cvals. This length includes room for the terminating null in each string. To ensure that the output names are not truncated, cvalen should be at least 33. Detailed_Output
n is the number of variable names matching name that are
returned. It will always be less than or equal to
room.
If no variable names match name, n is set to zero.
cvals is an array of kernel pool variables whose names match
the template name and which have indices ranging from
start to start+n-1.
Note that in general the names returned in cvals are
not sorted.
If no variables match name, no values are assigned to
the elements of cvals.
If the length of cvals is less than the length of the
variable names, the values returned will be truncated
on the right.
The declaration of cvals should be equivalent to
SpiceChar cvals [room][cvalen];
found is SPICETRUE if the some variable name in the kernel pool
matches name, SPICEFALSE if it is not.
Parameters
MAXLEN is the maximum length of the variable names that
can be stored in the kernel pool. This value is
currently 32.
Exceptions
1) If the value of `room' is less than one, the error
SPICE(BADARRAYSIZE) is signaled by a routine in the call tree
of this routine.
2) If `cvals' has declared length less than the size of a variable
name to be returned, the name will be truncated on the right.
See MAXLEN for the maximum size of variable names.
3) If the `name' input string pointer is null, the error
SPICE(NULLPOINTER) is signaled.
4) If the `name' input string has zero length, the error
SPICE(EMPTYSTRING) is signaled.
5) If the `cvals' output string pointer is null, the error
SPICE(NULLPOINTER) is signaled.
6) If the `cvals' output string has length less than two
characters, the error SPICE(STRINGTOOSHORT) is signaled, since
the output string is too short to contain one character of
output data plus a null terminator.
FilesNone. ParticularsThis routine provides the user interface for retrieving the names of kernel pool variables. This interface allows you to retrieve the names matching a template via multiple accesses. Under some circumstances this alleviates the problem of having to know in advance the maximum amount of space needed to accommodate all matching names. However, this method of access does come with a price. It is always more efficient to retrieve all of the data associated with a kernel pool variable in one call than it is to retrieve it in sections. The parameter MAXVAR defines the upper bound on the number of possible matching names. Examples
The numerical results shown for this example may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, and the machine
specific arithmetic implementation.
1) Load a PCK kernel, create a template for Jupiter kernel
variables, and after performing a query for them, output all the
variable names found in the kernel pool that match that template.
Use the PCK kernel below to load the triaxial ellipsoidal shape
model and orientation data for Jupiter.
pck00010.tpc
Example code begins here.
/.
Program gnpool_ex1
./
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
#define ROOM 3
#define LNSIZE 33
#define TEMPLATE "BODY599*"
SpiceBoolean found;
SpiceChar cvals [ROOM][LNSIZE];
SpiceInt i;
SpiceInt n;
SpiceInt start;
/.
Load a PCK kernel.
./
furnsh_c ( "pck00010.tpc" );
/.
Print the names of kernel variables that match TEMPLATE.
./
start = 0;
gnpool_c ( TEMPLATE, start, ROOM, LNSIZE, &n, cvals, &found );
if ( !found )
{
printf ( "There are no matching variables in the "
"kernel pool\n" );
}
else
{
printf ( "Kernel pool variables:\n"
"\n" );
for ( i = 0; i < n; i++ )
{
printf ( " %s\n", cvals[i] );
}
while ( n == ROOM )
{
start += n;
gnpool_c ( TEMPLATE, start, ROOM, LNSIZE,
&n, cvals, &found );
for ( i = 0; i < n; i++ )
{
printf ( " %s\n", cvals[i] );
}
}
}
return ( 0 );
}
When this program was executed on a Mac/Intel/cc/64-bit
platform, the output was:
Kernel pool variables:
BODY599_PM
BODY599_LONG_AXIS
BODY599_RADII
BODY599_NUT_PREC_DEC
BODY599_NUT_PREC_PM
BODY599_POLE_RA
BODY599_POLE_DEC
BODY599_NUT_PREC_RA
RestrictionsNone. Literature_ReferencesNone. Author_and_InstitutionN.J. Bachman (JPL) J. Diaz del Rio (ODC Space) W.L. Taber (JPL) E.D. Wright (JPL) Version
-CSPICE Version 1.2.0, 10-AUG-2021 (JDR)
Changed the argument names "lenout" and "kvars" to "cvalen" and
"cvals" for consistency with other routines.
Edited the header to comply with NAIF standard.
Replaced "ldpool_c" by "furnsh_c" in the code example. Added
example's problem statement and solution.
Added MAXLEN parameter description, corrected entry #2 in
-Exceptions section, added entry #5, and removed non-applicable
entry, which indicated that an error is signaled if a kernel
pool variable name exceeds MAXLEN.
-CSPICE Version 1.1.1, 10-FEB-2010 (EDW)
Added mention of the restriction on kernel pool variable
names to 32 characters or less.
-CSPICE Version 1.1.0, 18-MAY-2001 (WLT)
Added a cast to (char *) in the call to F2C_ConvertStrArr
-CSPICE Version 1.0.0, 08-JUN-1999 (NJB) (WLT)
Index_Entriesreturn names of kernel pool variables matching a template |
Fri Dec 31 18:41:08 2021