void gcpool_c ( ConstSpiceChar * name,
SpiceInt start,
SpiceInt room,
SpiceInt lenout,
SpiceInt * n,
void * cvals,
SpiceBoolean * found )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
name I Name of the variable whose value is to be returned.
start I Which component to start retrieving for name
room I The largest number of values to return.
lenout I The length of the output string.
n O Number of values returned for name.
cvals O Values associated with name.
found O True if variable is in pool.
-Detailed_Input
name is the name of the variable whose values are to be
returned. If the variable is not in the pool with
character type, found will be SPICEFALSE.
start is the index of the first component of name to return.
The index follows the C convention of being 0 based.
If start is less than 0, it will be treated as 0. If
start is greater than the total number of components
available for name, no values will be returned (n will
be set to zero). However, found will still be set to
SPICETRUE
room is the maximum number of components that should be
returned for this variable. (Usually it is the amount
of room available in the array cvals). If room is
less than 1 the error SPICE(BADARRAYSIZE) will be
signaled.
lenout The allowed length of the output string. This length
must large enough to hold the output string plus the
terminator. If the output string is expected to have x
characters, lenout needs to be x + 1.
-Detailed_Output
n is the number of values associated with name that
are returned. It will always be less than or equal
to room.
If name is not in the pool with character type, no
value is given to n.
cvals is the array of values associated with name.
If name is not in the pool with character type, no
values are given to the elements of cvals.
If the length of cvals is less than the length of
strings stored in the kernel pool (see MAXCHR) the
values returned will be truncated on the right.
found is SPICETRUE if the variable is in the pool and has
character type, SPICEFALSE if it is not.
-Parameters
None.
-Exceptions
1) If the value of room is less than one the error
SPICE(BADARRAYSIZE) is signaled.
2) If cvals has declared length less than the size of a
string to be returned, the value will be truncated on
the right. See MAXCHR in pool.c for the maximum stored size of
string variables.
3) If the input string pointer is null, the error SPICE(NULLPOINTER)
will be signaled.
4) If the input string has length zero, the error SPICE(EMPTYSTRING)
will be signaled.
5) If the output string has length less than two characters, it
is too short to contain one character of output data plus a null
terminator, so it cannot be passed to the underlying Fortran
routine. In this event, the error SPICE(STRINGTOOSHORT) is
signaled.
-Files
None.
-Particulars
This routine provides the user interface to retrieving
character data stored in the kernel pool. This interface
allows you to retrieve the data associated with a variable
in multiple accesses. Under some circumstances this alleviates
the problem of having to know in advance the maximum amount
of space needed to accommodate all kernel variables.
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 data in one call than it is to retrieve
it in sections.
C requires the length of the output character array to be defined
prior to calling the converted gcpool_c routine. The size of the
cvals output array is user defined and passed as the variable
lenout.
Also see the entry points gdpool_c and gipool_c.
-Examples
The following code fragment demonstrates how the data stored
in a kernel pool variable can be retrieved in pieces. Using the
kernel "test.ker" which contains
\begindata
CTEST_VAL = ('LARRY', 'MOE', 'CURLY' )
ITEST_VAL = ( 3141, 186, 282 )
DTEST_VAL = ( 3.1415, 186. , 282.397 )
The program...
#include <stdio.h>
#include <string.h>
#include "SpiceUsr.h"
#include "SpiceZmc.h"
#define LENOUT 20
#define NUMVALS 2
#define START 1
void main()
{
SpiceInt n;
SpiceChar cvals[NUMVALS][LENOUT];
SpiceBoolean found;
SpiceInt i;
ldpool_c ( "test.ker" );
/.
Get 2 values (NUMVALs) starting at the second value
in the list (START). Each value will be of length LENOUT.
./
gcpool_c ( "CTEST_VAL", START, NUMVALS, LENOUT, &n, cvals,
&found );
for ( i = 0; i < NUMVALS; i++ )
{
printf("%s\n", cvals[i] );
}
exit(0);
}
Will give output of
MOE
CURLY
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
W.L. Taber (JPL)
-Version
-CSPICE Version 2.2.1 07-SEP-2007 (EDW)
Edited the 'lenout' description in the Detailed_Input to
remove the recommendation of 32 as a general use value
for 'lenout'.
-CSPICE Version 2.2.0 18-MAY-2001 (WLT)
Added a cast to (char *) in the call to F2C_ConvertStrArr.
-CSPICE Version 2.1.0 22-JUN-1999 (EDW)
Added local variable to return boolean/logical values. This
fix allows the routine to function if int and long are different
sizes.
-CSPICE Version 2.0.3 09-FEB-1998 (EDW)
Removed the output dynamically allocated string. Conversion
of cval from string to array now accomplished via the
F2C_ConvertStrArray call.
-CSPICE Version 2.0.2 01-FEB-1998 (EDW)
Removed the input and work dynamically allocated strings.
-CSPICE Version 2.0.1 28-JAN-1998 (EDW)
The start parameter is now zero based as per C convention.
Adjusted the amount of memory for the strings to lenout-1.
-CSPICE Version 2.0.0 07-JAN-1998 (EDW)
The routine now function properly for room > 1. Previously
only a single value could be returned.
-CSPICE Version 1.0.0 23-OCT-1997 (EDW)
-Index_Entries
RETURN the character value of a pooled kernel variable
RETURN the string value of a pooled kernel variable
-&
*/
{ /* Begin gcpool_c */
/*
Local variables.
*/
logical yes;
/* The index is zero based here but not in gcpool_. */
start = start + 1;
/*
Participate in error tracing.
*/
chkin_c ( "gcpool_c");
/*
Check the input string utcstr to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "gcpool_c", name );
/*
Make sure the output string has at least enough room for one output
character and a null terminator. Also check for a null pointer.
*/
CHKOSTR ( CHK_STANDARD, "gcpool_c", cvals, lenout );
/*
Call the f2c'd routine
*/
gcpool_( ( char * ) name,
( integer * ) &start,
( integer * ) &room,
( integer * ) n,
( char * ) cvals,
( logical * ) &yes,
( ftnlen ) strlen(name),
( ftnlen ) lenout - 1 );
/* Cast back to a SpiceBoolean. */
*found = yes;
if ( *found )
{
/*
cvals now contains the requested data in a single string
lenout * n long. We need to reform cvals into an array
of n strings each lenout long.
*/
F2C_ConvertTrStrArr ( *n, lenout, (char *)cvals );
}
/* Done. Checkout. */
chkout_c ( "gcpool_c");
} /* End gcpool_c */
void dasec_c ( SpiceInt handle,
SpiceInt bufsiz,
SpiceInt buflen,
SpiceInt * n,
void * buffer,
SpiceBoolean * done )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I Handle of binary DAS file open with read access.
bufsiz I Maximum size, in lines, of buffer.
buflen I Line length associated with buffer.
n O Number of comments extracted from the DAS file.
buffer O Buffer in which extracted comments are placed.
done O Indicates whether all comments have been extracted.
-Detailed_Input
handle The file handle of a binary DAS file which has been
opened with read access.
bufsiz The maximum number of comments that may be placed into
buffer. This would typically be the declared array size
for the C character string array passed into this
routine.
buflen is the common length of the strings in buffer, including the
terminating nulls.
-Detailed_Output
n The number of comment lines extracted from the comment area
of the binary DAS file attached to handle. This number will
be <= bufsiz on output. If n == bufsiz and done !=
SPICETRUE then there are more comments left to extract. If
n == 0, then done == SPICETRUE, i.e., there were no
comments in the comment area. If there are comments in the
comment area, or comments remaining after the extraction
process has begun, n > 0, always.
buffer A list of at most bufsiz comments which have been
extracted from the comment area of the binary DAS
file attached to handle. buffer should be declared as
follows:
ConstSpiceChar buffer [bufsiz][buflen]
Each string in buffer is null-terminated.
done A boolean flag indicating whether or not all of the
comment lines from the comment area of the DAS file have
been read. This variable has the value SPICETRUE after the
last comment line has been read. It will have the value
SPICEFALSE otherwise.
If there are no comments in the comment area, this
variable will have the value SPICETRUE, and n == 0.
-Parameters
None.
-Exceptions
1) If the size of the output line buffer is is not positive,
the error SPICE(INVALIDARGUMENT) will be signaled.
2) If a comment line in a DAS file is longer than the length
of a character string array element of BUFFER, the error
SPICE(COMMENTTOOLONG) will be signaled.
3) If there is a mismatch between the number of comment
characters found and the number of comment characters
expected, the error SPICE(BADDASCOMMENTAREA) will be
signaled.
4) If the binary DAS file attached to HANDLE is not open for
reading, an error will be signaled by a routine called by
this routine.
5) If the input buffer pointer is null, the error SPICE(NULLPOINTER)
will be signaled.
6) If the input buffer string length buflen is not at least 2,
the error SPICE(STRINGTOOSHORT) will be signaled.
-Files
See argument handle in $ Detailed_Input.
-Particulars
Binary DAS files contain an area which is reserved for storing
annotations or descriptive textual information describing the data
contained in a file. This area is referred to as the "comment
area" of the file. The comment area of a DAS file is a line
oriented medium for storing textual information. The comment
area preserves any leading or embedded white space in the line(s)
of text which are stored, so that the appearance of the of
information will be unchanged when it is retrieved (extracted) at
some other time. Trailing blanks, however, are NOT preserved,
due to the way that character strings are represented in
standard Fortran 77.
This routine will read the comments from the comment area of
a binary DAS file, placing them into a line buffer. If the line
buffer is not large enough to hold the entire comment area,
the portion read will be returned to the caller, and the done
flag will be set to SPICEFALSE. This allows the comment area to be
read in "chunks," a buffer at a time. After all of the comment
lines have been read, the done flag will be set to SPICETRUE.
After all of the comments in DAS file have been read, the next
call to this routine will start reading comments at the start
of the comment area.
This routine can be used to "simultaneously" extract comments
from the comment areas of multiple binary DAS files.
-Examples
1) The following example will extract the entire comment area of a
binary DAS file attached to HANDLE, displaying the comments on
the terminal screen.
#include <stdio.h>
#include "SpiceUsr.h"
int main( int argc, char ** argv )
{
#define LNSIZE 81
#define MAXBUF 25
SpiceBoolean done;
SpiceChar buffer [MAXBUF][LNSIZE];
SpiceChar * filename;
SpiceInt handle;
SpiceInt i;
SpiceInt n;
filename = argv[1];
dasopr_ ( filename, &handle, (ftnlen)strlen(filename) );
done = SPICEFALSE;
while ( !done )
{
dasec_c( handle, MAXBUF, LNSIZE, &n, buffer, &done );
for ( i = 0; i < n; i++ )
{
printf ( "%s\n", buffer[i] );
}
}
return ( 0 );
}
-Restrictions
1) The comment area may consist only of printing ASCII characters,
decimal values 32 - 126.
2) There is NO maximum length imposed on the significant portion
of a text line that may be placed into the comment area of a
DAS file. The maximum length of a line stored in the comment
area should be kept reasonable, so that they may be easily
extracted. A good value for this would be 255 characters, as
this can easily accommodate "screen width" lines as well as
long lines which may contain some other form of information.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
-Version
-CSPICE Version 1.0.0, 24-FEB-2003 (NJB) (KRG)
-Index_Entries
extract comments from a das file
-&
*/
{ /* Begin dasec_c */
/*
Local variables
*/
logical locDone;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "dasec_c" );
/*
Make sure the output string has at least enough room for one output
character and a null terminator. Also check for a null pointer.
*/
CHKOSTR ( CHK_STANDARD, "dasec_c", buffer, buflen );
/*
Call the f2c'd routine.
*/
dasec_ ( (integer *) &handle,
(integer *) &bufsiz,
(integer *) n,
(char *) buffer,
(logical *) &locDone,
(ftnlen ) buflen-1 );
/*
Convert the output array from Fortran to C style.
*/
if ( *n > 0 );
{
F2C_ConvertTrStrArr ( *n, buflen, (SpiceChar *)buffer );
}
/*
Set the "done" flag.
*/
*done = (SpiceBoolean) locDone;
chkout_c ( "dasec_c" );
} /* End dasec_c */
