void gnpool_c ( ConstSpiceChar * name,
SpiceInt start,
SpiceInt room,
SpiceInt lenout,
SpiceInt * n,
void * kvars,
SpiceBoolean * found )
Return names of kernel variables matching a specified template.
KERNEL
CONSTANTS
FILES
VARIABLE 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.
lenout I Length of strings in output array kvars.
n O Number of values returned for name.
kvars O Kernel pool variables whose names match name.
found O True if there is at least one match.
name 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.
lenout is the length of strings in the output array kvars. This
length includes room for the terminating null in each
string. To ensure that the output names are not
truncated, lenout should be at least 33.
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.
kvars 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 kvars are
not sorted.
If no variables match name, no values are assigned to
the elements of kvars.
If the length of kvars is less than the length of the
variable names, the values returned will be truncated
on the right.
The declaration of kvars should be equivalent to
SpiceChar kvars [room][lenout];
found is SPICETRUE if the some variable name in the kernel pool
matches name, SPICEFALSE if it is not.
None.
1) If the value of room is less than one, the error
SPICE(BADARRAYSIZE) is signaled.
2) If kvars has declared length less than the size (including
terminating null character) of a name to be returned, the name
will be truncated on the right. The parameter MAXCHR sets
the maximum stored size of string variables.
3) If either the input or output string pointers are null, the error
SPICE(NULLPOINTER) will be signaled.
4) If the input string has length zero, the error SPICE(EMPTYSTRING)
will be signaled.
5) The caller must pass a value indicating the length of the output
string. If this value is not at least 2, the error
SPICE(STRINGTOOSHORT) will be signaled.
6) The error 'SPICE(BADVARNAME)' signals if the kernel pool
variable name length exceeds 32.
None.
This 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.
The following code demonstrates how the names of kernel pool
variables matching a template can be retrieved in pieces.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
#define ROOM 3
#define LNSIZE 81
#define TEMPLATE "BODY599*"
SpiceBoolean found;
SpiceChar kvars [ROOM][LNSIZE];
SpiceInt i;
SpiceInt n;
SpiceInt start;
/.
Load the data in the file "typical.ker" into the kernel pool.
./
ldpool_c ( "typical.ker" );
/.
Print the names of kernel variables that match TEMPLATE.
./
start = 0;
gnpool_c ( TEMPLATE, start, ROOM, LNSIZE, &n, kvars, &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", kvars[i] );
}
while ( n == ROOM )
{
start += n;
gnpool_c ( TEMPLATE, start, ROOM, LNSIZE,
&n, kvars, &found );
for ( i = 0; i < n; i++ )
{
printf ( " %s\n", kvars[i] );
}
}
}
/.
This is the end of the if block following the first gnpool_c
call.
./
return ( 0 );
}
None.
None.
N.J. Bachman (JPL)
W.L. Taber (JPL)
-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)
return names of kernel pool variables matching a template
Link to routine gnpool_c source file gnpool_c.c
|