Table of contents
CSPICE_EKUCEI updates an integer column entry in a
specified EK record.
Given:
handle the scalar integer referring to an EK file open for write
access.
help, handle
LONG = Scalar
segno the scalar integer indicating EK segment number of the record of
interest.
help, segno
LONG = Scalar
recno the scalar integer identifying the index for record of interest.
help, recno
LONG = Scalar
column the string scalar name of the column for the record of interest.
help, column
STRING = Scalar
nvals the integer number of entries from `ivals' to update.
help, nvals
LONG = Scalar
ivals an array of integer values containing the data values to update
to the record in `column'.
help, ivals
LONG = Array[N]
Note: `nvals' specifies the number of `ivals' entries written
to the updated record.
isnull a scalar boolean flagging whether the entry is null.
help, isnull
BOOLEAN = Scalar
the call:
cspice_ekucei, handle, segno, recno, column, nvals, ivals, isnull
updates `nvals' of `ivals' to column `column' in segment `segno',
record `recno', of the EK file referred to by `handle'.
None.
Any numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) The following program demonstrates how to create a new EK and
add data to an integer column in a given record within the
file, how to update the data in this record, and how to read
the data from it.
Example code begins here.
PRO ekucei_ex1
;;
;; Constants
;;
EKNAME = "ekucei.ek"
IFNAME = "Test EK"
NCOLS = 2
NROWS = 6
NRESVC = 0
TABLE = "MIXED_DATA"
CVLEN = 81
MAXVAL = 10
ivals = intarr( MAXVAL )
;;
;; Provide a maximum size for the return array 'ivals'.
;;
nelts = 20l
;;
;; Open a new EK file. For simplicity, we won't
;; reserve space for the comment area, so the
;; number of reserved comment characters is zero.
;; The constant IFNAME is the internal file name.
;;
if ( cspice_exists (EKNAME) ) then begin
file_delete, EKNAME
endif
cspice_ekopn, EKNAME, IFNAME, NRESVC, handle
;;
;; Set up the table and column names and declarations
;; for the MIXED_DATA segment. We'll index all of
;; the columns. All columns are scalar, so we omit
;; the size declaration.
;;
cdecls = strarr(NCOLS)
cnames = strarr(NCOLS)
cnames[0] = "INT_COL_1"
cdecls[0] = "DATATYPE = INTEGER, INDEXED = TRUE,"+$
" NULLS_OK = TRUE"
cnames[1] = "INT_COL_2"
cdecls[1] = "DATATYPE = INTEGER, SIZE = VARIABLE,"+$
" NULLS_OK = TRUE"
;;
;; Start the segment.
;;
cspice_ekbseg, handle, TABLE, NCOLS, cnames, cdecls, segno
for i = 0, (NROWS-1) do begin
cspice_ekappr, handle, segno, recno
ivals[0] = i
isnull = ( i EQ 1 )
cspice_ekacei, handle, segno, recno, cnames[0], $
1, ivals, isnull
;;
;; Array-valued columns follow.
;;
ivals[0] = 10*i
ivals[1] = (10*i) + 1
cspice_ekacei, handle, segno, recno, cnames[1], $
2, ivals, isnull
endfor
;;
;; End the file.
;;
cspice_ekcls, handle
;;
;; Open the EK for write access.
;;
cspice_ekopw, EKNAME, handle
;;
;; Negate the values in the odd-numbered records
;; using the update routines."
;;
for i = 1, (NROWS-1), 2 do begin
recno = i
isnull = ( i EQ 1 )
ivals[0] = -i
cspice_ekucei, handle, segno, recno, cnames[0], $
1, ivals, isnull
;;
;; Array-valued columns follow.
;;
ivals[0] = -(10*i)
ivals[1] = -((10*i) + 1)
cspice_ekucei, handle, segno, recno, cnames[1], $
2, ivals, isnull
endfor
;;
;; End the file.
;;
cspice_ekcls, handle
;;
;; Open the created file. Show the values added.
;;
cspice_ekopr, EKNAME, handle
for i = 0, (NROWS-1) do begin
cspice_ekrcei, handle, segno, i, cnames[0], nelts, $
ivals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[0],' record number: ',i
print, ivals
print
endif
;;
;; Array-valued columns follow.
;;
cspice_ekrcei, handle, segno, i, cnames[1], nelts, $
ivals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[1], ' record number: ',i
print, ivals
print
endif
endfor
;;
;; End the file.
;;
cspice_ekcls, handle
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Data from column: INT_COL_1 record number: 0
0
Data from column: INT_COL_2 record number: 0
0 1
Data from column: INT_COL_1 record number: 2
2
Data from column: INT_COL_2 record number: 2
20 21
Data from column: INT_COL_1 record number: 3
-3
Data from column: INT_COL_2 record number: 3
-30 -31
Data from column: INT_COL_1 record number: 4
4
Data from column: INT_COL_2 record number: 4
40 41
Data from column: INT_COL_1 record number: 5
-5
Data from column: INT_COL_2 record number: 5
-50 -51
Note that the record 1 does not appear due to setting the
'isnull' flag to true for that record.
Notice the odd value record numbers have negative values
as a result of the update calls.
After run completion, a new EK exists in the output directory.
This routine operates by side effects: it modifies the named
EK file by adding data to the specified record in the specified
column. Data may be added to a segment in random order; it is not
necessary to fill in columns or rows sequentially. Data may only
be added one logical element at a time. Partial assignments of
logical elements are not supported.
1) If `handle' is invalid, an error is signaled by a routine in the
call tree of this routine.
2) If `segno' is out of range, an error is signaled by a routine in
the call tree of this routine.
3) If `column' is not the name of a declared column, an error
is signaled by a routine in the call tree of this routine.
4) If `column' specifies a column of whose data type is not
integer, the error SPICE(WRONGDATATYPE) is signaled by a
routine in the call tree of this routine.
5) If `recno' is out of range, an error is signaled by a routine in
the call tree of this routine.
6) If the specified column has fixed-size entries and `nvals' does
not match this size, an error is signaled by a routine in the
call tree of this routine.
7) If the specified column has variable-size entries and `nvals' is
non-positive, an error is signaled by a routine in the call
tree of this routine.
8) If an attempt is made to add a null value to a column that
doesn't take null values, an error is signaled by a routine in
the call tree of this routine.
9) If `column' specifies a column of whose class is not an integer
class known to this routine, the error SPICE(NOCLASS) 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 any of the input arguments, `handle', `segno', `recno',
`column', `nvals', `ivals' or `isnull', is undefined, an error
is signaled by the IDL error handling system.
12) If any of the input arguments, `handle', `segno', `recno',
`column', `nvals', `ivals' or `isnull', is not of the expected
type, or it does not have the expected dimensions and size, an
error is signaled by the Icy interface.
See the EK Required Reading ek.req for a discussion of the EK file
format.
None.
ICY.REQ
EK.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.2, 25-AUG-2021 (JDR)
Edited the header to comply with NAIF standard. Added
example's problem statement, and a note after the example's
output.
Fixed a bug in code example: corrected "cspice_ekrcei" argument
list.
Added -Parameters, -Particulars, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.0.1, 13-JUN-2010 (EDW)
Minor edit to code comments eliminating typo.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
replace integer entry in an EK column
|