0
# E-Kernels (Event Kernels)
1

2
Database-like functionality for storing, querying, and manipulating structured data in SPICE. E-kernels provide relational database capabilities within the SPICE system, allowing storage of mission events, instrument parameters, and other tabular data with full SQL-like query support.
3

4
## Capabilities
5

6
### Database Creation and Management
7

8
Create and manage E-kernel database files for storing structured mission data.
9

10
```python { .api }
11
def ekopn(fname: str, ifname: str) -> int:
12
    """
13
    Open new E-kernel file for writing.
14
    
15
    Parameters:
16
    - fname: str, E-kernel file name
17
    - ifname: str, internal file name
18
    
19
    Returns:
20
    int: file handle
21
    """
22

23
def ekcls(handle: int) -> None:
24
    """
25
    Close E-kernel file.
26
    
27
    Parameters:
28
    - handle: int, file handle
29
    
30
    Returns:
31
    None
32
    """
33
```
34

35
### Table and Segment Operations
36

37
Define table structures and manage data segments within E-kernels.
38

39
```python { .api }
40
def ekbseg(handle: int, tabnam: str, cnames: List[str], decls: List[str]) -> None:
41
    """
42
    Begin new E-kernel segment.
43
    
44
    Parameters:
45
    - handle: int, file handle
46
    - tabnam: str, table name
47
    - cnames: List[str], column names
48
    - decls: List[str], column declarations
49
    
50
    Returns:
51
    None
52
    """
53

54
def ekappr(handle: int, segno: int) -> None:
55
    """
56
    Append records to E-kernel segment.
57
    
58
    Parameters:
59
    - handle: int, file handle
60
    - segno: int, segment number
61
    
62
    Returns:
63
    None
64
    """
65
```
66

67
### Data Insertion
68

69
Insert various data types into E-kernel tables.
70

71
```python { .api }
72
def ekacec(handle: int, segno: int, recno: int, column: str, nvals: int, cdata: List[str], isnull: bool) -> None:
73
    """
74
    Add character data to E-kernel column.
75
    
76
    Parameters:
77
    - handle: int, file handle
78
    - segno: int, segment number
79
    - recno: int, record number
80
    - column: str, column name
81
    - nvals: int, number of values
82
    - cdata: List[str], character data array
83
    - isnull: bool, null flag
84
    
85
    Returns:
86
    None
87
    """
88

89
def ekaced(handle: int, segno: int, recno: int, column: str, nvals: int, ddata: ndarray, isnull: bool) -> None:
90
    """
91
    Add double precision data to E-kernel column.
92
    
93
    Parameters:
94
    - handle: int, file handle
95
    - segno: int, segment number  
96
    - recno: int, record number
97
    - column: str, column name
98
    - nvals: int, number of values
99
    - ddata: ndarray, double precision data array
100
    - isnull: bool, null flag
101
    
102
    Returns:
103
    None
104
    """
105

106
def ekacei(handle: int, segno: int, recno: int, column: str, nvals: int, idata: List[int], isnull: bool) -> None:
107
    """
108
    Add integer data to E-kernel column.
109
    
110
    Parameters:
111
    - handle: int, file handle
112
    - segno: int, segment number
113
    - recno: int, record number  
114
    - column: str, column name
115
    - nvals: int, number of values
116
    - idata: List[int], integer data array
117
    - isnull: bool, null flag
118
    
119
    Returns:
120
    None
121
    """
122
```
123

124
### Query Operations
125

126
Perform SQL-like queries on E-kernel data.
127

128
```python { .api }
129
def ekfind(query: str, lenout: int) -> Tuple[int, bool, str]:
130
    """
131
    Find E-kernel data satisfying query.
132
    
133
    Parameters:
134
    - query: str, SQL-like query string
135
    - lenout: int, maximum length of error message
136
    
137
    Returns:
138
    Tuple[int, bool, str]: (nmrows, error, errmsg)
139
    """
140

141
def eknelt(selidx: int, row: int) -> int:
142
    """
143
    Return number of elements in specified column entry.
144
    
145
    Parameters:
146
    - selidx: int, column selection index
147
    - row: int, row number
148
    
149
    Returns:
150
    int: number of elements
151
    """
152
```
153

154
### Data Retrieval
155

156
Extract data from E-kernel query results.
157

158
```python { .api }
159
def ekgc(selidx: int, row: int, lenout: int) -> Tuple[str, bool]:
160
    """
161
    Get character data from E-kernel query results.
162
    
163
    Parameters:
164
    - selidx: int, column selection index
165
    - row: int, row number
166
    - lenout: int, maximum string length
167
    
168
    Returns:
169
    Tuple[str, bool]: (cdata, null_flag)
170
    """
171

172
def ekgd(selidx: int, row: int) -> Tuple[float, bool]:
173
    """
174
    Get double precision data from E-kernel query results.
175
    
176
    Parameters:
177
    - selidx: int, column selection index
178
    - row: int, row number
179
    
180
    Returns:
181
    Tuple[float, bool]: (ddata, null_flag)
182
    """
183

184
def ekgi(selidx: int, row: int) -> Tuple[int, bool]:
185
    """
186
    Get integer data from E-kernel query results.
187
    
188
    Parameters:
189
    - selidx: int, column selection index
190
    - row: int, row number
191
    
192
    Returns:
193
    Tuple[int, bool]: (idata, null_flag)
194
    """
195
```
196

197
### Record Management
198

199
Insert, update, and delete records in E-kernel tables.
200

201
```python { .api }
202
def ekinsr(handle: int, segno: int, recno: int) -> None:
203
    """
204
    Insert new record into E-kernel segment.
205
    
206
    Parameters:
207
    - handle: int, file handle
208
    - segno: int, segment number
209
    - recno: int, record number
210
    
211
    Returns:
212
    None
213
    """
214

215
def ekdelr(handle: int, segno: int, recno: int) -> None:
216
    """
217
    Delete record from E-kernel segment.
218
    
219
    Parameters:
220
    - handle: int, file handle
221
    - segno: int, segment number
222
    - recno: int, record number
223
    
224
    Returns:
225
    None
226
    """
227
```
228

229
### Schema Information
230

231
Query E-kernel table structure and metadata.
232

233
```python { .api }
234
def ekccnt(table: str) -> int:
235
    """
236
    Return count of columns in E-kernel table.
237
    
238
    Parameters:
239
    - table: str, table name
240
    
241
    Returns:
242
    int: number of columns
243
    """
244

245
def ekcii(table: str, cindex: int, lenout: int) -> Tuple[str, SpiceEKAttDsc]:
246
    """
247
    Get column information from E-kernel table.
248
    
249
    Parameters:
250
    - table: str, table name
251
    - cindex: int, column index
252
    - lenout: int, maximum column name length
253
    
254
    Returns:
255
    Tuple[str, SpiceEKAttDsc]: (column_name, attribute_descriptor)
256
    """
257
```
258

259
### File Loading and Management
260

261
Load and unload E-kernel files for querying.
262

263
```python { .api }
264
def eklef(fname: str) -> int:
265
    """
266
    Load E-kernel file for read access.
267
    
268
    Parameters:
269
    - fname: str, E-kernel file name
270
    
271
    Returns:
272
    int: file handle
273
    """
274

275
def ekuef(handle: int) -> None:
276
    """
277
    Unload E-kernel file.
278
    
279
    Parameters:
280
    - handle: int, file handle
281
    
282
    Returns:
283
    None
284
    """
285
```
286

287
## Common Usage Patterns
288

289
### Creating and Populating E-Kernel
290
```python
291
import spiceypy as spice
292
import numpy as np
293

294
# Create new E-kernel file
295
handle = spice.ekopn("mission_events.ek", "Mission Events Database")
296

297
# Define table structure
298
table_name = "EVENTS"
299
column_names = ["TIME", "EVENT_TYPE", "DESCRIPTION", "DURATION"]
300
column_decls = [
301
    "TIME DOUBLE PRECISION",
302
    "EVENT_TYPE CHARACTER*(20)",  
303
    "DESCRIPTION CHARACTER*(100)",
304
    "DURATION DOUBLE PRECISION"
305
]
306

307
# Begin new segment
308
spice.ekbseg(handle, table_name, column_names, column_decls)
309

310
# Insert event records
311
for i, event in enumerate(events):
312
    # Insert new record
313
    spice.ekinsr(handle, 0, i)
314
    
315
    # Add data to columns
316
    spice.ekaced(handle, 0, i, "TIME", 1, np.array([event.time]), False)
317
    spice.ekacec(handle, 0, i, "EVENT_TYPE", 1, [event.type], False)
318
    spice.ekacec(handle, 0, i, "DESCRIPTION", 1, [event.description], False)
319
    spice.ekaced(handle, 0, i, "DURATION", 1, np.array([event.duration]), False)
320

321
# Close file
322
spice.ekcls(handle)
323
```
324

325
### Querying E-Kernel Data
326
```python
327
# Load E-kernel for querying
328
handle = spice.eklef("mission_events.ek")
329

330
# Perform SQL-like query
331
query = "SELECT TIME, EVENT_TYPE FROM EVENTS WHERE DURATION > 3600.0"
332
nmrows, error, errmsg = spice.ekfind(query, 1000)
333

334
if not error:
335
    print(f"Found {nmrows} matching records")
336
    
337
    # Extract results
338
    for row in range(nmrows):
339
        # Get time (column 0)
340
        time_val, null_flag = spice.ekgd(0, row)
341
        
342
        # Get event type (column 1)  
343
        event_type, null_flag = spice.ekgc(1, row, 50)
344
        
345
        print(f"Row {row}: Time={time_val}, Type={event_type}")
346
else:
347
    print(f"Query error: {errmsg}")
348

349
# Unload file
350
spice.ekuef(handle)
351
```
352

353
### Schema Inspection
354
```python
355
# Load E-kernel
356
handle = spice.eklef("mission_events.ek")
357

358
# Get table column information
359
table_name = "EVENTS"
360
num_columns = spice.ekccnt(table_name)
361

362
print(f"Table '{table_name}' has {num_columns} columns:")
363

364
for i in range(num_columns):
365
    col_name, attr_desc = spice.ekcii(table_name, i, 50)
366
    print(f"  Column {i}: {col_name}")
367

368
spice.ekuef(handle)
369
```