| ekifld_c |
|
Table of contents
Procedure
ekifld_c ( EK, initialize segment for fast write )
void ekifld_c ( SpiceInt handle,
ConstSpiceChar * tabnam,
SpiceInt ncols,
SpiceInt nrows,
SpiceInt cnamln,
const void * cnames,
SpiceInt declen,
const void * decls,
SpiceInt * segno,
SpiceInt * rcptrs )
AbstractInitialize a new E-kernel segment to allow fast writing. Required_ReadingEK KeywordsEK Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- handle I File handle. tabnam I Table name. ncols I Number of columns in the segment. nrows I Number of rows in the segment. cnamln I Length of names 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. rcptrs O Array of record pointers. Detailed_Input
handle is the handle of an EK file open for write access.
A new segment is to be created in this file.
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
(see SpiceEK.h) characters 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.
nrows is the number of rows in a new segment. Each
column to be added to the segment must contain
the number of entries indicated by nrows.
cnamln,
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][cnamln]
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 SPICE_EK_CNAMSZ (see
SpiceEK.h) characters 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 assignment
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.
rcptrs is an array of record pointers for the input
segment. This array must not be modified by the
caller.
The array rcptrs must be passed as an input to
each column addition routine called while
writing the specified segment.
rcptrs must be declared with dimension nrows.
ParametersNone. Exceptions
1) If `handle' is invalid, an error is signaled by a routine in the
call tree of this routine.
2) If `tabnam' is more than SPICE_EK_TNAMSZ characters long, an error
is signaled by a routine in the call tree of this routine.
3) If `tabnam' contains any nonprintable characters, an error
is signaled by a routine in the call tree of this routine.
4) If `ncols' is non-positive or greater than the maximum allowed
number SPICE_EK_MXCLSG, an error is signaled by a routine in the call
tree of this routine.
5) If `nrows' is non-positive, the error SPICE(INVALIDCOUNT)
is signaled by a routine in the call tree of this routine.
6) If any column name exceeds SPICE_EK_CNAMSZ characters in length, an
error is signaled by a routine in the call tree of this
routine.
7) If any column name contains non-printable characters, an error
is signaled by a routine in the call tree of this routine.
8) If a declaration cannot be understood by this routine, an
error is signaled by a routine in the call tree of this
routine.
9) If an non-positive string length or element size is specified,
an error is signaled by a routine in the call tree of this
routine.
10) If an I/O error occurs while reading or writing the indicated
file, the error is signaled by a routine in the call tree of
this routine.
11) If the `tabnam' input string pointer is null, the error
SPICE(NULLPOINTER) is signaled.
12) If the `tabnam' input string has zero length, the error
SPICE(EMPTYSTRING) is signaled.
13) If any of the `cnames' or `decls' input array pointers is
null, the error SPICE(NULLPOINTER) is signaled.
14) If any of the `cnames' or `decls' input arrays' strings have
length less than two characters, the error
SPICE(STRINGTOOSHORT) is signaled.
FilesSee the EK Required Reading for a discussion of the EK file format. Particulars
This routine prepares an EK for the creation of a new segment via
the fast column writer routines. After this routine is called,
the columns of the segment are filled in by calls to the fast
column writer routines of the appropriate data types. The fast
column writer routines are:
ekaclc_c {EK, add column, character}
ekacld_c {EK, add column, double precision}
ekacli_c {EK, add column, integer}
When all of the columns have been added, the write operation is
completed by a call to ekffld_c {EK, finish fast write}.
The segment is not valid until ekffld_c has been called.
The EK system supports only one fast write at a time. It is
not possible use the fast write routines to simultaneously write
multiple segments, either in the same EK file or in different
files.
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) Suppose we want to create an Sequence Component E-kernel
named "ekifld_ex1.bdb" 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
The file "ekifld_ex1.bdb" will contain two segments, the first
containing the DATAORDERS table and the second containing the
DATAITEMS table.
This example demonstrates how to open a new EK file and create
the first of the segments described above.
Use the LSK kernel below to load the leap seconds and time
constants required for the conversions.
naif0012.tls
Example code begins here.
/.
Program ekifld_ex1
./
#include <stdio.h>
#include <string.h>
#include "SpiceUsr.h"
int main()
{
/.
Constants
./
#define CNMLEN ( SPICE_EK_CNAMSZ + 1 )
#define DECLEN 201
#define EKNAME "ekifld_ex1.bdb"
#define FNMLEN 50
#define IFNAME "Test EK/Created 03-JUL-2018"
#define LNMLEN 50
#define LSK "naif0012.tls"
#define NCOLS 6
#define NRESVC 0
#define NROWS 9
#define TABLE "DATAORDERS"
#define TNMLEN SPICE_EK_TNAMSZ
#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 rcptrs [ NROWS ];
SpiceInt segno;
SpiceInt sizes [ NROWS ];
SpiceInt wkindx [ 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. We presume the number of rows
of data is known in advance.
./
ekifld_c ( handle, TABLE, NCOLS, NROWS, CNMLEN,
cnames, DECLEN, cdecls, &segno, rcptrs );
/.
At this point, arrays containing data for the
segment's columns may be filled in. The names
of the data arrays are shown below.
Column Data array
"ORDER_ID" ordids
"CUSTOMER_ID" cstids
"LAST_NAME" lnames
"FIRST_NAME" fnames
"ORDER_DATE" ets
"COST" costs
The null flags array indicates which entries are null.
It is ignored for columns that don't allow null
values. In this case, only the COST column allows
nulls.
Fill in data arrays and null flag arrays here. This code
section would normally be replaced by calls to user functions
returning column values.
./
for ( i = 0; i < NROWS; i++ )
{
ordids[i] = i;
cstids[i] = i*100;
costs [i] = (SpiceDouble) 100*i;
sprintf ( fnames[i], "Order %d Customer first name", i );
sprintf ( lnames[i], "Order %d Customer last name", i );
sprintf ( dateStr, "1998 Mar %d", i );
utc2et_c ( dateStr, ets+i );
nlflgs[i] = SPICEFALSE;
}
nlflgs[1] = SPICETRUE;
/.
The sizes array shown below is ignored for scalar
and fixed-size array columns, so we need not
initialize it. For variable-size arrays, the
Ith element of the sizes array must contain the size
of the Ith column entry in the column being written.
Normally, the sizes array would be reset for each
variable-size column.
Add the columns of data to the segment. All of the
data for each column is written in one shot.
./
ekacli_c ( handle, segno, "order_id", ordids,
sizes, nlflgs, rcptrs, wkindx );
ekacli_c ( handle, segno, "customer_id", cstids,
sizes, nlflgs, rcptrs, wkindx );
ekaclc_c ( handle, segno, "last_name", LNMLEN,
lnames, sizes, nlflgs, rcptrs, wkindx );
ekaclc_c ( handle, segno, "first_name", FNMLEN,
fnames, sizes, nlflgs, rcptrs, wkindx );
ekacld_c ( handle, segno, "order_date", ets,
sizes, nlflgs, rcptrs, wkindx );
ekacld_c ( handle, segno, "cost", costs,
sizes, nlflgs, rcptrs, wkindx );
/.
Complete the segment. The `rcptrs' array is that
returned by ekifld_c.
./
ekffld_c ( handle, segno, rcptrs );
/.
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 );
return ( 0 );
}
When this program is executed, no output is presented on
screen. After run completion, a new EK file exists in the
output directory.
Restrictions
1) Only one segment can be created at a time using the fast
write routines.
2) No other EK operation may interrupt a fast write. For
example, it is not valid to issue a query while a fast write
is in progress.
Literature_ReferencesNone. Author_and_InstitutionN.J. Bachman (JPL) J. Diaz del Rio (ODC Space) E.D. Wright (JPL) Version
-CSPICE Version 2.4.0, 10-AUG-2021 (JDR)
Edited the -Examples section to comply with NAIF standard.
Updated code example to include the string.h file, and to
update EK parameter names to "SPICE_EK_CNAMSZ" and
"SPICE_EK_TNAMSZ".
Changed the input argument name "cnmlen" to "cnamln" for
consistency with other routines.
-CSPICE Version 2.3.1, 14-AUG-2006 (EDW)
Replace mention of ldpool_c with furnsh_c.
-CSPICE Version 2.3.0, 12-JUL-2002 (NJB)
Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.
-CSPICE Version 2.2.0, 10-JAN-2002 (NJB)
Const-qualified input arrays. Added casts to type (void *)
to expressions passed to free(), in order to suppress compilation
warnings under MS Visual C++/C.
Documentation change: instances of the phrase "fast load"
were replaced with "fast write."
Corrected parameter names giving maximum table and column name
lengths.
-CSPICE Version 2.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 2.0.0, 07-JUL-1999 (NJB)
Output segment number segno is now mapped to C range.
-CSPICE Version 1.0.0, 08-MAR-1999 (NJB)
Based on SPICELIB Version 1.0.0, 25-OCT-1995 (NJB)
Index_Entriesstart new E-kernel segment for fast writing start new EK segment for fast writing |
Fri Dec 31 18:41:05 2021