void swpool_c ( ConstSpiceChar * agent,
SpiceInt nnames,
SpiceInt lenvals,
const void * names )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
agent I The name of an agent to be notified after updates.
nnames I The number of variables to associate with agent.
lenvals I Length of strings in the names array.
names I Variable names whose update causes the notice.
-Detailed_Input
agent is the name of a routine or entry point (agency) that
will want to know when a some variables in the kernel
pool have been updated.
nnames is the number of kernel pool variable names that will
be associated with agent.
lenvals is the length of the strings in the array names,
including the null terminators.
names is an array of names of variables in the kernel pool.
Whenever any of these is updated, a notice will be
posted for agent so that one can quickly check
whether needed data has been modified.
-Detailed_Output
None.
-Parameters
None.
-Files
None.
-Exceptions
1) If sufficient room is not available to hold a name or new agent,
a routine in the call tree for this routine will signal an error.
2) If either of the input string pointers are null, the error
SPICE(NULLPOINTER) will be signaled.
3) If any input string agent has length zero, the error
SPICE(EMPTYSTRING) will be signaled.
4) The caller must pass a value indicating the length of the strings
in the names array. If this value is not at least 2, the error
SPICE(STRINGTOOSHORT) will be signaled.
-Particulars
The kernel pool is a convenient place to store a wide variety of
data needed by routines in CSPICE and routines that interface with
CSPICE routines. However, when a single name has a large quantity
of data associated with it, it becomes inefficient to constantly
query the kernel pool for values that are not updated on a frequent
basis.
This entry point allows a routine to instruct the kernel pool to
post a message whenever a particular value gets updated. In this
way, a routine can quickly determine whether or not data it requires
has been updated since the last time the data was accessed. This
makes it reasonable to buffer the data in local storage and update
it only when a variable in the kernel pool that affects this data
has been updated.
Note that swpool_c has a side effect. Whenever a call to swpool_c
is made, the agent specified in the calling sequence is added to the
list of agents that should be notified that an update of its
variables has occurred. In other words the code
swpool_c ( agent, nnames, lenvals, names );
cvpool_c ( agent, &update );
will always return update as SPICETRUE.
This feature allows for a slightly cleaner use of swpool_c and
cvpool_c as shown in the example below. Because swpool_c
automatically loads agent into the list of agents to notify of a
kernel pool update, you do not have to include the code for fetching
the initial values of the kernel variables in the initialization
portion of a subroutine. Instead, the code for the first fetch from
the pool is the same as the code for fetching when the pool is
updated.
-Examples
Suppose that you have an application subroutine, MYTASK, that
needs to access a large data set in the kernel pool. If this
data could be kept in local storage and kernel pool queries
performed only when the data in the kernel pool has been
updated, the routine can perform much more efficiently.
The code fragment below illustrates how you might make use of this
feature.
#include "SpiceUsr.h"
.
.
.
/.
On the first call to this routine establish those variables
that we will want to read from the kernel pool only when
new values have been assigned.
./
if ( first )
{
first = SPICEFALSE;
swpool_c ( "MYTASK", nnames, lenvals, names );
}
/.
If any of the variables has been updated, fetch them from the
kernel pool.
./
cvpool_c ( "MYTASK", &update );
if ( update )
{
for ( i = 0; i < NVAR; i++ )
{
gdpool_c( MYTASK_VAR[i], 1, NMAX, n[i], val[i], &found[i] );
}
}
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.3.0, 27-AUG-2002 (NJB)
Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.
-CSPICE Version 1.2.0, 28-AUG-2001 (NJB)
Const-qualified input array names.
-CSPICE Version 1.1.0, 14-FEB-2000 (NJB)
Calls to C2F_CreateStrArr replaced with calls to error-signaling
version of this routine: C2F_CreateStrArr_Sig.
-CSPICE Version 1.0.0, 05-JUN-1999 (NJB) (WLT)
-Index_Entries
Watch for an update to a kernel pool variable
Notify a routine of an update to a kernel pool variable
-&
*/
{ /* Begin swpool_c */
/*
Local variables
*/
SpiceChar * fCvalsArr;
SpiceInt fCvalsLen;
/*
Participate in error tracing.
*/
chkin_c ( "swpool_c" );
/*
Make sure the input string pointer for agent is non-null
and that the length is sufficient.
*/
CHKFSTR ( CHK_STANDARD, "swpool_c", agent );
/*
Make sure the input string pointer for the names array is non-null
and that the length lenvals is sufficient.
*/
CHKOSTR ( CHK_STANDARD, "swpool_c", names, lenvals );
/*
Create a Fortran-style string array.
*/
C2F_MapStrArr ( "swpool_c",
nnames, lenvals, names, &fCvalsLen, &fCvalsArr );
if ( failed_c() )
{
chkout_c ( "swpool_c" );
return;
}
/*
Call the f2c'd routine.
*/
swpool_ ( ( char * ) agent,
( integer * ) &nnames,
( char * ) fCvalsArr,
( ftnlen ) strlen(agent),
( ftnlen ) fCvalsLen );
/*
Free the dynamically allocated array.
*/
free ( fCvalsArr );
chkout_c ( "swpool_c" );
} /* End swpool_c */
void pcpool_c ( ConstSpiceChar * name,
SpiceInt n,
SpiceInt lenvals,
const void * cvals )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
name I The kernel pool name to associate with cvals.
n I The number of values to insert.
lenvals I The lengths of the strings in the array cvals.
cvals I An array of strings to insert into the kernel pool.
-Detailed_Input
name is the name of the kernel pool variable to associate
with the values supplied in the array cvals. 'name' is
restricted to a length of 32 characters or less.
n is the number of values to insert into the kernel pool.
lenvals is the length of the strings in the array cvals,
including the null terminators.
cvals is an array of strings to insert into the kernel
pool. cvals should be declared as follows:
char cvals[n][lenvals];
-Detailed_Output
None.
-Parameters
None.
-Exceptions
1) If name is already present in the kernel pool and there
is sufficient room to hold all values supplied in values,
the old values associated with name will be overwritten.
2) If there is not sufficient room to insert a new variable
into the kernel pool and name is not already present in
the kernel pool, the error SPICE(KERNELPOOLFULL) is
signaled by a routine in the call tree to this routine.
3) If there is not sufficient room to insert the values associated
with name, the error SPICE(NOMOREROOM) will be signaled.
4) If either input string pointer is null, the error
SPICE(NULLPOINTER) will be signaled.
5) If the input string name has length zero, the error
SPICE(EMPTYSTRING) will be signaled.
6) If the input cvals string length is less than 2, the error
SPICE(STRINGTOOSHORT) will be signaled.
7) The error 'SPICE(BADVARNAME)' signals if the kernel pool
variable name length exceeds 32.
-Files
None.
-Particulars
This entry point provides a programmatic interface for inserting
character data into the SPICE kernel pool without reading an
external file.
-Examples
The following example program shows how a topocentric frame for a
point on the surface of the earth may be defined at run time using
pcpool_c, pdpool_c, and pipool_c. In this example, the surface
point is associated with the body code 300000. To facilitate
testing, the location of the surface point coincides with that of
the DSN station DSS-12; the reference frame MYTOPO defined here
coincides with the reference frame DSS-12_TOPO.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
The first angle is the negative of the longitude of the
surface point; the second angle is the negative of the
point's colatitude.
./
SpiceDouble angles [3] = { -243.1945102442646,
-54.7000629043147,
180.0 };
SpiceDouble et = 0.0;
SpiceDouble rmat [3][3];
SpiceInt axes [3] = { 3, 2, 3 };
SpiceInt center = 300000;
SpiceInt frclass = 4;
SpiceInt frclsid = 1500000;
SpiceInt frcode = 1500000;
/.
Define the MYTOPO reference frame.
Note that the third argument in the pcpool_c calls is
the length of the final string argument, including the
terminating null character.
./
pipool_c ( "FRAME_MYTOPO", 1, &frcode );
pcpool_c ( "FRAME_1500000_NAME", 1, 7, "MYTOPO" );
pipool_c ( "FRAME_1500000_CLASS", 1, &frclass );
pipool_c ( "FRAME_1500000_CLASS_ID", 1, &frclsid );
pipool_c ( "FRAME_1500000_CENTER", 1, ¢er );
pcpool_c ( "OBJECT_300000_FRAME", 1, 7, "MYTOPO" );
pcpool_c ( "TKFRAME_MYTOPO_RELATIVE", 1, 7, "ITRF93" );
pcpool_c ( "TKFRAME_MYTOPO_SPEC", 1, 7, "ANGLES" );
pcpool_c ( "TKFRAME_MYTOPO_UNITS", 1, 8, "DEGREES" );
pipool_c ( "TKFRAME_MYTOPO_AXES", 3, axes );
pdpool_c ( "TKFRAME_MYTOPO_ANGLES", 3, angles );
/.
Load a high precision binary earth PCK. Also load a
topocentric frame kernel for DSN stations. The file names
shown here are simply examples; users should replace these
with the names of appropriate kernels.
./
furnsh_c ( "earth_000101_060207_051116.bpc" );
furnsh_c ( "earth_topo_050714.tf" );
/.
Look up transformation from DSS-12_TOPO frame to MYTOPO frame.
This transformation should differ by round-off error from
the identity matrix.
./
pxform_c ( "DSS-12_TOPO", "MYTOPO", et, rmat );
printf ( "\n"
"DSS-12_TOPO to MYTOPO transformation at "
"et %23.16e = \n"
"\n"
" %25.16f %25.16f %25.16f\n"
" %25.16f %25.16f %25.16f\n"
" %25.16f %25.16f %25.16f\n",
et,
rmat[0][0], rmat[0][1], rmat[0][2],
rmat[1][0], rmat[1][1], rmat[1][2],
rmat[2][0], rmat[2][1], rmat[2][2] );
return ( 0 );
}
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.3.3, 17-JAN-2014 (NJB)
Updated Index_Entries section.
-CSPICE Version 1.3.2, 10-FEB-2010 (EDW)
Added mention of the restriction on kernel pool variable
names to 32 characters or less.
Reordered header sections to conform to SPICE convention.
-CSPICE Version 1.3.1, 17-NOV-2005 (NJB)
Replaced code fragment in Examples section of header with
smaller, complete program.
-CSPICE Version 1.3.0, 12-JUL-2002 (NJB)
Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.
-CSPICE Version 1.2.0, 28-AUG-2001 (NJB)
Const-qualified input array cvals.
-CSPICE Version 1.1.0, 14-FEB-2000 (NJB)
Calls to C2F_CreateStrArr replaced with calls to error-signaling
version of this routine: C2F_CreateStrArr_Sig.
-CSPICE Version 1.0.0, 18-JUN-1999 (NJB) (WLT)
-Index_Entries
Set the value of a character_variable in the kernel_pool
-&
*/
{ /* Begin pcpool_c */
/*
Local variables
*/
SpiceChar * fCvalsArr;
SpiceInt fCvalsLen;
/*
Participate in error tracing.
*/
chkin_c ( "pcpool_c" );
/*
Check the input kernel variable name to make sure the pointer is
non-null and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "pcpool_c", name );
/*
Make sure the input string pointer for the cvals array is non-null
and that the length lenvals is sufficient.
*/
CHKOSTR ( CHK_STANDARD, "pcpool_c", cvals, lenvals );
/*
Create a Fortran-style string array.
*/
C2F_MapStrArr ( "pcpool_c",
n, lenvals, cvals, &fCvalsLen, &fCvalsArr );
if ( failed_c() )
{
chkout_c ( "pcpool_c" );
return;
}
/*
Call the f2c'd routine.
*/
pcpool_ ( ( char * ) name,
( integer * ) &n,
( char * ) fCvalsArr,
( ftnlen ) strlen(name),
( ftnlen ) fCvalsLen );
/*
Free the dynamically allocated array.
*/
free ( fCvalsArr );
chkout_c ( "pcpool_c" );
} /* End pcpool_c */
void dafac_c ( SpiceInt handle,
SpiceInt n,
SpiceInt lenvals,
const void * buffer )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I handle of a DAF opened with write access.
n I Number of comments to put into the comment area.
lenvals I Length of elements
buffer I Buffer of comments to put into the comment area.
-Detailed_Input
handle is the file handle of a binary DAF which has been opened
with write access.
n is the number of rows in the array `buffer'. This is
also the number of comment lines in `buffer' that are to be
added to the comment area of the binary DAF attached to
`handle'.
buffer A string buffer containing comments which are to be added
to the comment area of the binary DAF attached to `handle'.
buffer should be declared by the caller has follows:
SpiceChar buffer[n][lenvals];
Each row of the buffer should contain one comment line.
-Detailed_Output
None.
-Parameters
None.
-Exceptions
1) If the number of comments to be added is not positive, the
error SPICE(INVALIDARGUMENT) will be signaled.
2) If a non printing ASCII character is encountered in the
comments, the error SPICE(ILLEGALCHARACTER) will be signaled.
3) If the binary DAF file attached to HANDLE is not open with
write access an error will be signalled by a routine called by
this routine.
4) If the end of the comments cannot be found, i.e., the end of
comments marker is missing on the last comment record, the error
SPICE(BADCOMMENTAREA) will be signaled.
5) If the input pointer `buffer' is null, the error
SPICE(NULLPOINTER) will be signaled.
6) If the input buffer string length indicated by `lenvals'
is less than 2, the error SPICE(STRINGTOOSHORT) will be signaled.
-Files
See argument `handle' in $ Detailed_Input.
-Particulars
A binary DAF contains a data area which is reserved for storing
annotations or descriptive textual information about the data
contained in a file. This area is referred to as the ``comment
area'' of the file. The comment area of a DAF is a line oriented
medium for storing textual information. The comment area preserves
leading or embedded white space in the line(s) of text which are
stored so that the appearance of the 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 take a buffer of text lines and add (append) them
to the comment area of a binary DAF. If there are no comments in the
comment area of the file, then space will be allocated and the text
lines in `buffer' will be placed into the comment area. The text lines
may contain only printable ASCII characters (decimal values 32 -
126).
There is NO maximum length imposed on the significant portion of a
text line that may be placed into the comment area of a DAF. The
maximum length of a line stored in the comment area should be
reasonable, however, so that they may be easily extracted. A good
maximum 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.
-Examples
1) Let
handle be the handle for a DAF which has been opened with
write access.
n be the number of lines of text to be added to the
comment area of the binary DAF attached to handle.
lenvals be the length of the rows of a string buffer.
buffer is an array of text lines to be added to the comment
area of the binary DAF attached to handle. `buffer'
normally is declared
SpiceChar buffer [n][lenvals];
The call
dafac_c ( handle, n, lenvals, buffer );
will append the first n line(s) in `buffer' to the comment area
of the binary DAF attached to `handle'.
-Restrictions
1) This routine uses constants that are specific to the ASCII
character sequence. The results of using this routine with
a different character sequence are unpredictable.
2) This routine is only used to extract records on environments
whose characters are a single byte in size. Updates to this
routine and routines in its call tree may be required to
properly handle other cases.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
-Version
-CSPICE Version 1.0.0, 16-NOV-2006 (NJB) (KRG)
-Index_Entries
add comments to a binary daf file
append comments to a daf file comment area
-&
*/
{ /* Begin dafac_c */
/*
Local variables
*/
SpiceChar * fCvalsArr;
SpiceInt fCvalsLen;
/*
Participate in error tracing.
*/
chkin_c ( "dafac_c" );
/*
Make sure the input string pointer for the `buffer' array is non-null
and that the length lenvals is sufficient.
*/
CHKOSTR ( CHK_STANDARD, "dafac_c", buffer, lenvals );
/*
The input buffer contains C-style strings; we must pass a
Fortran-style buffer to dafac_.
*/
C2F_MapStrArr ( "dafac_c",
n, lenvals, buffer, &fCvalsLen, &fCvalsArr );
if ( failed_c() )
{
chkout_c ( "dafac_c" );
return;
}
/*
Call the f2c'd routine.
*/
dafac_ ( ( integer * ) &handle,
( integer * ) &n,
( char * ) fCvalsArr,
( ftnlen ) fCvalsLen );
/*
Free the dynamically allocated array.
*/
free ( fCvalsArr );
chkout_c ( "dafac_c" );
} /* End dafac_c */
void ekbseg_c ( SpiceInt handle,
ConstSpiceChar * tabnam,
SpiceInt ncols,
SpiceInt cnmlen,
const void * cnames,
SpiceInt declen,
const void * decls,
SpiceInt * segno )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I File handle.
tabnam I Table name.
ncols I Number of columns in the segment.
cnmlen I Length of names in in column name array.
cnames I Names of columns.
declen I Length of declaration strings in declaration array.
decls I Declarations of columns.
segno O Segment number.
-Detailed_Input
handle the handle of an EK file that is open for writing.
tabnam is the name of the EK table to which the current
segment belongs. All segments in the EK file
designated by handle must have identical column
attributes. tabnam must not exceed SPICE_EK_TNAMSZ
characters (see SpiceEK.h) in length. Case is not
significant. Table names must start with a letter and
contain only characters from the set
{A-Z,a-z,0-9,$,_}.
ncols is the number of columns in a new segment.
cnmlen,
cnames are, respectively, the length of the column name
strings in the column name array, and the base
address of the array itself. The array should have
dimensions
[ncols][cnmlen]
declen,
decls are, respectively, the length of the declaration
strings in the declaration array, and the base
address of the array itself. The array should have
dimensions
[ncols][declen]
The Ith element of cnames and the Ith element of decls
apply to the Ith column in the segment.
Column names must not exceed CSPICE_EK_CNAMSZ
characters (see SpiceEK.h) in length. Case is not
significant. Column names must start with a letter
and contain only characters from the set
{A-Z,a-z,0-9,$,_}.
The declarations are strings that contain
"keyword=value" assignments that define the
attributes of the columns to which they apply. The
column attributes that are defined by a column
declaration are:
DATATYPE
SIZE
<is the column indexed?>
<does the column allow null values?>
The form of a declaration is
"DATATYPE = <type>,
SIZE = <size>,
INDEXED = <boolean>,
NULLS_OK = <boolean>"
For example, an indexed, scalar, integer column
that allows null values would have the declaration
"DATATYPE = INTEGER,
SIZE = 1,
INDEXED = TRUE,
NULLS_OK = TRUE"
Commas are required to separate the assignments
within declarations; white space is optional;
case is not significant.
The order in which the attribute keywords are
listed in declaration is not significant.
Every column in a segment must be declared.
Each column entry is effectively an array, each
element of which has the declared data type. The
SIZE keyword indicates how many elements are in
each entry of the column in whose declaration the
keyword appears. Note that only scalar-valued
columns (those for which SIZE = 1) may be
referenced in query constraints. A size
assignment has the syntax
SIZE = <integer>
or
SIZE = VARIABLE
The size value defaults to 1 if omitted.
The DATATYPE keyword defines the data type of
column entries. The DATATYPE assignment syntax
has any of the forms
DATATYPE = CHARACTER*(<length>)
DATATYPE = CHARACTER*(*)
DATATYPE = DOUBLE PRECISION
DATATYPE = INTEGER
DATATYPE = TIME
As the datatype declaration syntax suggests,
character strings may have fixed or variable
length. Variable-length strings are allowed only
in columns of size 1.
Optionally, scalar-valued columns may be indexed.
To create an index for a column, use the assignment
INDEXED = TRUE
By default, columns are not indexed.
Optionally, any column can allow null values. To
indicate that a column may allow null values, use
the assigment
NULLS_OK = TRUE
in the column declaration. By default, null
values are not allowed in column entries.
-Detailed_Output
segno is the number of the segment to which data is to be
added. Segments are numbered from 0 to nseg-1, where
nseg is the count of segments in the file. Segment
numbers are used as unique identifiers by other EK
access routines.
-Parameters
None.
-Exceptions
1) If handle is invalid, the error will be diagnosed by routines
called by this routine.
2) If tabnam is more than SPICE_EK_TNAMSZ characters long, the
error is diagnosed by routines called by this routine.
3) If tabnam contains any nonprintable characters, the error
is diagnosed by routines called by this routine.
4) If ncols is non-positive or greater than the maximum allowed
number SPICE_EK_MXCLSG, the error SPICE(INVALIDCOUNT) is
signaled.
5) If any column name exceeds SPICE_EK_CNAMSZ characters in
length, the error is diagnosed by routines called by this
routine.
6) If any column name contains non-printable characters, the
error is diagnosed by routines called by this routine.
7) If a declaration cannot be understood by this routine, the
error is diagnosed by routines called by this routine.
8) If an non-positive string length or element size is specified,
the error is diagnosed by routines called by this routine.
9) If an I/O error occurs while reading or writing the indicated
file, the error will be diagnosed by routines called by this
routine.
10) If the input string pointer for the table name is null, the
error SPICE(NULLPOINTER) will be signaled.
12) If the input tablen name string has length zero, the error
SPICE(EMPTYSTRING) will be signaled.
13) If the string pointer for cnames is null, the error
SPICE(NULLPOINTER) will be signaled.
14) If the string length cnmlen is less than 2, the error
SPICE(STRINGTOOSHORT) will be signaled.
15) If the string pointer for decls is null, the error
SPICE(NULLPOINTER) will be signaled.
16) If the string length declen is less than 2, the error
SPICE(STRINGTOOSHORT) will be signaled.
-Files
See the EK Required Reading for a discussion of the EK file
format.
-Particulars
This routine operates by side effects: it prepares an EK for
the addition of a new segment. It is not necessary to take
any special action to `complete' a segment; segments are readable
after the completion of any record insertion, deletion, write,
or update operation.
-Examples
1) Suppose we have an E-kernel named ORDER_DB.EK which contains
records of orders for data products. The E-kernel has a
table called DATAORDERS that consists of the set of columns
listed below:
DATAORDERS
Column Name Data Type
----------- ---------
ORDER_ID INTEGER
CUSTOMER_ID INTEGER
LAST_NAME CHARACTER*(*)
FIRST_NAME CHARACTER*(*)
ORDER_DATE TIME
COST DOUBLE PRECISION
The order database also has a table of items that have been
ordered. The columns of this table are shown below:
DATAITEMS
Column Name Data Type
----------- ---------
ITEM_ID INTEGER
ORDER_ID INTEGER
ITEM_NAME CHARACTER*(*)
DESCRIPTION CHARACTER*(*)
PRICE DOUBLE PRECISION
We'll suppose that the file ORDER_DB.EK contains two segments,
the first containing the DATAORDERS table and the second
containing the DATAITEMS table.
Below, we show how we'd open a new EK file and start the
first of the segments described above.
#include "SpiceUsr.h"
#include <stdio.h>
void main()
{
/.
Constants
./
#define CNMLEN SPICE_EK_CSTRLN
#define DECLEN 201
#define EKNAME "order_db.ek"
#define FNMLEN 50
#define IFNAME "Test EK/Created 20-SEP-1995"
#define LNMLEN 50
#define LSK "leapseconds.ker"
#define NCOLS 6
#define NRESVC 0
#define TABLE "DATAORDERS"
#define TNMLEN CSPICE_EK_TAB_NAM_LEN
#define UTCLEN 30
/.
Local variables
./
SpiceBoolean nlflgs [ NROWS ];
SpiceChar cdecls [ NCOLS ] [ DECLEN ];
SpiceChar cnames [ NCOLS ] [ CNMLEN ];
SpiceChar fnames [ NROWS ] [ FNMLEN ];
SpiceChar lnames [ NROWS ] [ LNMLEN ];
SpiceChar dateStr [ UTCLEN ];
SpiceDouble costs [ NROWS ];
SpiceDouble ets [ NROWS ];
SpiceInt cstids [ NROWS ];
SpiceInt ordids [ NROWS ];
SpiceInt handle;
SpiceInt i;
SpiceInt segno;
SpiceInt sizes [ NROWS ];
/.
Load a leapseconds kernel for UTC/ET conversion.
./
furnsh_c ( LSK );
/.
Open a new EK file. For simplicity, we will not
reserve any space for the comment area, so the
number of reserved comment characters is zero.
The constant IFNAME is the internal file name.
./
ekopn_c ( EKNAME, IFNAME, NRESVC, &handle );
/.
Set up the table and column names and declarations
for the DATAORDERS segment. We'll index all of
the columns. All columns are scalar, so we omit
the size declaration. Only the COST column may take
null values.
./
strcpy ( cnames[0], "ORDER_ID" );
strcpy ( cdecls[0], "DATATYPE = INTEGER, INDEXED = TRUE" );
strcpy ( cnames[1], "CUSTOMER_ID" );
strcpy ( cdecls[1], "DATATYPE = INTEGER, INDEXED = TRUE" );
strcpy ( cnames[2], "LAST_NAME" );
strcpy ( cdecls[2], "DATATYPE = CHARACTER*(*),"
"INDEXED = TRUE" );
strcpy ( cnames[3], "FIRST_NAME" );
strcpy ( cdecls[3], "DATATYPE = CHARACTER*(*),"
"INDEXED = TRUE" );
strcpy ( cnames[4], "ORDER_DATE" );
strcpy ( cdecls[4], "DATATYPE = TIME, INDEXED = TRUE" );
strcpy ( cnames[5], "COST" );
strcpy ( cdecls[5], "DATATYPE = DOUBLE PRECISION,"
"INDEXED = TRUE,"
"NULLS_OK = TRUE" );
/.
Start the segment.
./
ekbseg_c ( handle, TABLE, NCOLS, CNMLEN,
cnames, DECLEN, cdecls, &segno );
/.
Add data to the segment. No special action
is required to finish the segment.
./
[Data are added via calls to ekappr_c and the
ekacec_c, ekaced_c, and ekacei_c routines. See any
of these routines for examples.]
/.
At this point, the second segment could be
created by an analogous process. In fact, the
second segment could be created at any time; it is
not necessary to populate the first segment with
data before starting the second segment.
./
/.
The file must be closed by a call to ekcls_c.
./
ekcls_c ( handle );
}
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
-Version
-CSPICE Version 1.1.0, 12-JUL-2002 (NJB)
Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.
-CSPICE Version 1.0.0, 17-NOV-2001 (NJB)
-Index_Entries
start new E-kernel segment
start new EK segment
-&
*/
{ /* Begin ekbseg_c */
/*
Local variables
*/
SpiceChar * fCnameArr;
SpiceChar * fCdeclArr;
SpiceInt fCnameLen;
SpiceInt fCdeclLen;
/*
Participate in error tracing.
*/
chkin_c ( "ekbseg_c" );
/*
Check the table name to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKFSTR ( CHK_STANDARD, "ekbseg_c", tabnam );
/*
Check the column name array to make sure the pointer is non-null
and the string length is non-zero. Note: this check is normally
done for output strings: CHKOSTR is the macro that does the job.
*/
CHKOSTR ( CHK_STANDARD, "ekbseg_c", cnames, cnmlen );
/*
Check the declaration array to make sure the pointer is non-null
and the string length is non-zero.
*/
CHKOSTR ( CHK_STANDARD, "ekbseg_c", decls, declen );
C2F_MapStrArr ( "ekbseg_c",
ncols, cnmlen, cnames, &fCnameLen, &fCnameArr );
if ( failed_c() )
{
chkout_c ( "ekbseg_c" );
return;
}
C2F_MapStrArr ( "ekbseg_c",
ncols, declen, decls, &fCdeclLen, &fCdeclArr );
if ( failed_c() )
{
free ( fCnameArr );
chkout_c ( "ekbseg_c" );
return;
}
/*
Call the f2c'd Fortran routine. Use explicit type casts for every
type defined by f2c.
*/
ekbseg_ ( ( integer * ) &handle,
( char * ) tabnam,
( integer * ) &ncols,
( char * ) fCnameArr,
( char * ) fCdeclArr,
( integer * ) segno,
( ftnlen ) strlen(tabnam),
( ftnlen ) fCnameLen,
( ftnlen ) fCdeclLen );
/*
Clean up all of our dynamically allocated arrays.
*/
free ( fCnameArr );
free ( fCdeclArr );
/*
Map segno to C style range.
*/
(*segno)--;
chkout_c ( "ekbseg_c" );
} /* End ekbseg_c */
void dasac_c ( SpiceInt handle,
SpiceInt n,
SpiceInt buflen,
const void * buffer )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I DAS handle of a file opened with write access.
n I Number of comments to put into the comment area.
buflen I Line length associated with buffer.
buffer I Buffer of lines to be put into the comment area.
-Detailed_Input
handle The file handle of a binary DAS file which has been
opened with write access.
n The number of strings in buffer that are to be
appended to the comment area of the binary DAS file
attached to handle.
buflen is the common length of the strings in buffer, including the
terminating nulls.
buffer A buffer containing comments which are to be added
to the comment area of the binary DAS file attached
to handle. buffer should be declared as follows:
ConstSpiceChar buffer [n][buflen]
Each string in buffer is null-terminated.
-Detailed_Output
None.
-Parameters
None.
-Exceptions
1) If the number of comments to be added is not positive, the
error SPICE(INVALIDARGUMENT) will be signaled.
2) If a non-null, non printing ASCII character is encountered in the
comments, the error SPICE(ILLEGALCHARACTER) will be
signaled.
3) If the binary DAS file attached to handle is not open for
write access, an error will be signaled by a routine called
by this routine.
4) If the input buffer pointer is null, the error SPICE(NULLPOINTER)
will be signaled.
5) 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 a data area which is reserved for storing
annotations or descriptive textual information about 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
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 take a buffer of text lines and add (append)
them to the comment area of a binary DAS file. If there are no
comments in the comment area of the file, then space will be
allocated and the text lines in buffer will then placed into the
comment area. The text lines may contain only printable ASCII
characters (decimal values 32 - 126).
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 reasonable, however, 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.
-Examples
Let
handle be the handle for a DAS file which has been opened
with write access.
n be the number of lines of text to be added to the
comment area of the binary DAS file attached to
handle.
BUFLEN be the declared line length of the buffer.
buffer is a list of text lines to be added to the comment
area of the binary DAS file attached to handle.
The call
dasac_c ( handle, n, BUFLEN, buffer );
will append the first n line(s) in buffer to the comment area
of the binary DAS file attached to handle.
-Restrictions
1) This routine uses constants that are specific to the ASCII
character sequence. The results of using this routine with
a different character sequence are unpredictable.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
-Version
-CSPICE Version 1.1.0, 02-MAR-2003 (NJB)
Added error check in wrapper for non-positive
buffer line count.
-CSPICE Version 1.0.0, 25-FEB-2003 (NJB) (KRG)
-Index_Entries
add comments to a binary das file
append comments to a das file comment area
-&
*/
{ /* Begin dasac_c */
/*
Local variables
*/
SpiceChar * fCvalsArr;
SpiceInt fCvalsLen;
/*
Participate in error tracing.
*/
if ( return_c() )
{
return;
}
chkin_c ( "dasac_c" );
/*
Check the line count of the input buffer.
*/
if ( n < 1 )
{
setmsg_c ( "Comment buffer line count n = #; must be positive." );
errint_c ( "#", n );
sigerr_c ( "SPICE(INVALIDARGUMENT)" );
chkout_c ( "dasac_c" );
return;
}
/*
Check the input buffer for null pointer or short lines.
*/
CHKOSTR ( CHK_STANDARD, "dasac_c", buffer, buflen );
/*
Map the input buffer to a Fortran-style buffer.
*/
C2F_MapStrArr ( "dasac_c", n, buflen, buffer, &fCvalsLen, &fCvalsArr );
if ( failed_c() )
{
chkout_c ( "dasac_c" );
return;
}
/*
Call the f2c'd routine.
*/
dasac_ ( ( integer * ) &handle,
( integer * ) &n,
( char * ) fCvalsArr,
( ftnlen ) fCvalsLen );
/*
Free the dynamically allocated array.
*/
free ( fCvalsArr );
chkout_c ( "dasac_c" );
} /* End dasac_c */
void lmpool_c ( const void * cvals,
SpiceInt lenvals,
SpiceInt n )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
cvals I An array that contains a SPICE text kernel.
lenvals I Length of strings in cvals.
n I The number of entries in cvals.
-Detailed_Input
cvals is an array of strings that contains lines of text
that could serve as a SPICE text kernel. cvals is
declared as follows:
ConstSpiceChar cvals [n][lenvals]
Each string in cvals is null-terminated.
lenvals is the common length of the strings in cvals,
including the terminating nulls.
n is the number of strings in cvals.
-Detailed_Output
None.
-Parameters
None.
-Exceptions
1) If the input string pointer is null, the error SPICE(NULLPOINTER)
will be signaled.
2) If the input string length lenvals is not at least 2, the error
SPICE(STRINGTOOLSHORT) will be signaled.
3) The error 'SPICE(BADVARNAME)' signals if a kernel pool
variable name length exceeds 32.
4) Other exceptions are diagnosed by routines in the call tree of
this routine.
-Files
None.
-Particulars
This routine allows you to store a text kernel in an internal
array of your program and load this array into the kernel pool
without first storing its contents as a text kernel.
Kernel pool variable names are restricted to a length of 32
characters or less.
-Examples
Suppose that your application is not particularly sensitive
to the current number of leapseconds but that you would
still like to use a relatively recent leapseconds kernel
without requiring users to load a leapseconds kernel into
the program. The example below shows how you might set up
the initialization portion of your program.
#include "SpiceUsr.h"
#define LNSIZE 81
#define NLINES 27
SpiceChar textbuf[NLINES][LNSIZE] =
{
"DELTET/DELTA_T_A = 32.184",
"DELTET/K = 1.657D-3",
"DELTET/EB = 1.671D-2",
"DELTET/M = ( 6.239996 1.99096871D-7 )",
"DELTET/DELTA_AT = ( 10, @1972-JAN-1",
" 11, @1972-JUL-1",
" 12, @1973-JAN-1",
" 13, @1974-JAN-1",
" 14, @1975-JAN-1",
" 15, @1976-JAN-1",
" 16, @1977-JAN-1",
" 17, @1978-JAN-1",
" 18, @1979-JAN-1",
" 19, @1980-JAN-1",
" 20, @1981-JUL-1",
" 21, @1982-JUL-1",
" 22, @1983-JUL-1",
" 23, @1985-JUL-1",
" 24, @1988-JAN-1",
" 25, @1990-JAN-1",
" 26, @1991-JAN-1",
" 27, @1992-JUL-1",
" 28, @1993-JUL-1",
" 29, @1994-JUL-1",
" 30, @1996-JAN-1",
" 31, @1997-JUL-1",
" 32, @1999-JAN-1 )"
};
lmpool_c ( textbuf, LNSIZE, NLINES );
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
W.L. Taber (JPL)
-Version
-CSPICE Version 1.3.1, 10-FEB-2010 (EDW)
Added mention of the restriction on kernel pool variable
names to 32 characters or less.
-CSPICE Version 1.3.0, 12-JUL-2002 (NJB)
Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.
-CSPICE Version 1.2.0, 28-AUG-2001 (NJB)
Const-qualified input array.
-CSPICE Version 1.1.0, 14-FEB-2000 (NJB)
Calls to C2F_CreateStrArr replaced with calls to error-signaling
version of this routine: C2F_CreateStrArr_Sig.
-CSPICE Version 1.0.0, 08-JUN-1999 (NJB) (WLT)
-Index_Entries
Load the kernel pool from an internal text buffer
-&
*/
{ /* Begin lmpool_c */
/*
Local variables
*/
SpiceChar * fCvalsArr;
SpiceInt fCvalsLen;
/*
Participate in error tracing.
*/
chkin_c ( "lmpool_c" );
/*
Make sure the input string pointer is non-null and that the
length lenvals is sufficient.
*/
CHKOSTR ( CHK_STANDARD, "lmpool_c", cvals, lenvals );
/*
Create a Fortran-style string array.
*/
C2F_MapStrArr ( "lmpool_c", n, lenvals, cvals, &fCvalsLen, &fCvalsArr );
if ( failed_c() )
{
chkout_c ( "lmpool_c" );
return;
}
/*
Call the f2c'd routine.
*/
lmpool_ ( ( char * ) fCvalsArr,
( integer * ) &n,
( ftnlen ) fCvalsLen );
/*
Free the dynamically allocated array.
*/
free ( fCvalsArr );
chkout_c ( "lmpool_c" );
} /* End lmpool_c */
