| ekbseg_c |
|
Table of contents
Procedure
ekbseg_c ( EK, start new segment )
void ekbseg_c ( SpiceInt handle,
ConstSpiceChar * tabnam,
SpiceInt ncols,
SpiceInt cnamln,
const void * cnames,
SpiceInt declen,
const void * decls,
SpiceInt * segno )
AbstractStart a new segment in an E-kernel. 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. 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. Detailed_Input
handle is 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.
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 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 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.
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, the error SPICE(INVALIDCOUNT) is signaled by a
routine in the call tree of this routine.
5) 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.
6) If any column name contains non-printable characters, an error
is signaled by a routine in the call tree of this routine.
7) If a declaration cannot be understood by this routine, an
error is signaled by a routine in the call tree of this
routine.
8) 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.
9) 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.
10) If the `tabnam' input string pointer is null, the error
SPICE(NULLPOINTER) is signaled.
11) If the `tabnam' input string has zero length, the error
SPICE(EMPTYSTRING) is signaled.
12) If any of the `cnames' or `decls' input array pointers is
null, the error SPICE(NULLPOINTER) is signaled.
13) 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. ParticularsThis 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
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 E-kernel which contains 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
This EK file will have one segment containing the DATAITEMS
table.
This examples demonstrates how to open a new EK file; create
the segment described above and how to insert a new record
into it.
Example code begins here.
/.
Program ekbseg_ex1
./
#include <string.h>
#include "SpiceUsr.h"
int main( )
{
/.
Local parameters
./
#define EKNAME "ekbseg_ex1.bdb"
#define TABLE "DATAITEMS"
#define DECLEN 201
#define DESCLN 81
#define NAMLEN 41
#define NCOLS 5
/.
Local variables
./
SpiceChar cdecls [NCOLS][DECLEN];
SpiceChar cnames [NCOLS][SPICE_EK_CSTRLN];
SpiceChar * descrp;
SpiceChar * ifname;
SpiceChar * itemnm;
SpiceDouble price;
SpiceInt esize;
SpiceInt handle;
SpiceInt itemid;
SpiceInt nresvc;
SpiceInt ordid;
SpiceInt recno;
SpiceInt segno;
SpiceBoolean isnull;
/.
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 variable `ifname' is the internal file name.
./
nresvc = 0;
ifname = "Test EK;Created 21-JUN-2019";
ekopn_c ( EKNAME, ifname, nresvc, &handle );
/.
Set up the table and column names and declarations
for the DATAITEMS segment. We'll index all of
the columns. All columns are scalar, so we omit
the size declaration.
./
strcpy( cnames[0], "ITEM_ID" );
strcpy( cdecls[0], "DATATYPE = INTEGER, INDEXED = TRUE" );
strcpy( cnames[1], "ORDER_ID" );
strcpy( cdecls[1], "DATATYPE = INTEGER, INDEXED = TRUE" );
strcpy( cnames[2], "ITEM_NAME" );
strcpy( cdecls[2], "DATATYPE = CHARACTER*(*), INDEXED = TRUE" );
strcpy( cnames[3], "DESCRIPTION" );
strcpy( cdecls[3], "DATATYPE = CHARACTER*(*), INDEXED = TRUE" );
strcpy( cnames[4], "PRICE" );
strcpy( cdecls[4], "DATATYPE = DOUBLE PRECISION, INDEXED = TRUE" );
/.
Start the segment. Since we have no data for this
segment, start the segment by just defining the new
segment's schema.
./
ekbseg_c ( handle, TABLE, NCOLS, SPICE_EK_CSTRLN,
cnames, DECLEN, cdecls, &segno );
/.
Append a new, empty record to the DATAITEMS
table. Recall that the DATAITEMS table
is in segment number 0. The call will return
the number of the new, empty record.
./
segno = 0;
ekappr_c ( handle, segno, &recno );
/.
At this point, the new record is empty. A valid EK
cannot contain empty records. We fill in the data
here. Data items are filled in one column at a time.
The order in which the columns are filled in is not
important. We use the ekaceX_c (add column entry)
routines to fill in column entries. We'll assume
that no entries are null. All entries are scalar,
so the entry size is 0.
./
isnull = SPICEFALSE;
esize = 0;
/.
The following variables will contain the data for
the new record.
./
ordid = 10011;
itemid = 531;
itemnm = "Sample item";
descrp = "This sample item is used only in tests.";
price = 1345.678;
/.
Note that the names of the routines called
correspond to the data types of the columns: the
last letter of the routine name is C, I, or D,
depending on the data type.
./
ekacei_c ( handle, segno, recno, "ORDER_ID", esize, &ordid, isnull );
ekacei_c ( handle, segno, recno, "ITEM_ID", esize, &itemid, isnull );
ekacec_c ( handle, segno, recno, "ITEM_NAME",
esize, NAMLEN, itemnm, isnull );
ekacec_c ( handle, segno, recno, "DESCRIPTION",
esize, DESCLN, descrp, isnull );
ekaced_c ( handle, segno, recno, "PRICE", esize, &price, isnull );
/.
Close the file to make the update permanent.
./
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.
RestrictionsNone. Literature_ReferencesNone. Author_and_InstitutionN.J. Bachman (JPL) J. Diaz del Rio (ODC Space) Version
-CSPICE Version 1.2.0, 13-AUG-2021 (JDR)
Changed input argument name "cnmlen" to "cnamln" for consistency
with other functions.
Edited the header to comply with NAIF standard. Added
complete code example.
-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_Entriesstart new E-kernel segment start new EK segment |
Fri Dec 31 18:41:05 2021