Table of contents
CSPICE_EKUCED updates a double precision 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 `dvals' to update.
help, nvals
LONG = Scalar
dvals an array of double values containing the data values to update
to the record in 'column'.
help, dvals
DOUBLE = Array[N]
Note: `nvals' specifies the number of `dvals' entries written
to the updated record.
isnull a scalar boolean flagging whether the entry is null.
help, isnull
BOOLEAN = Scalar
the call:
cspice_ekuced, handle, segno, recno, column, nvals, dvals, isnull
updates `nvals' of `dvals' 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 a double precision 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 ekuced_ex1
;;
;; Constants
;;
EKNAME = "ekuced_ex1.ek"
IFNAME = "Test EK"
NCOLS = 2
NROWS = 6
NRESVC = 0
TABLE = "DP_DATA"
CVLEN = 81
MAXVAL = 10
dvals = dblarr( MAXVAL )
;;
;; Provide a maximum size for the return array 'dvals'.
;;
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 DP_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] = "DP_COL_1"
cdecls[0] = "DATATYPE = DOUBLE PRECISION, INDEXED = TRUE,"+$
" NULLS_OK = TRUE"
cnames[1] = "DP_COL_2"
cdecls[1] = "DATATYPE = DOUBLE PRECISION, 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
isnull = ( i EQ 1 )
dvals[0] = double(i)
cspice_ekaced, handle, segno, recno, cnames[0], $
1, dvals, isnull
;;
;; Array-valued columns follow.
;;
dvals[0] = double( 10*i)
dvals[1] = double((10*i)+1 )
dvals[2] = double((10*i)+2 )
cspice_ekaced, handle, segno, recno, cnames[1], $
3, dvals, 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 )
dvals[0] = double(-i)
cspice_ekuced, handle, segno, recno, cnames[0], $
1, dvals, isnull
;;
;; Array-valued columns follow.
;;
dvals[0] = -double( 10*i)
dvals[1] = -double((10*i)+1 )
dvals[2] = -double((10*i)+2 )
cspice_ekuced, handle, segno, recno, cnames[1], $
3, dvals, 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_ekrced, handle, segno, i, cnames[0], nelts, $
dvals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[0],' record number: ',i
print, dvals
print
endif
;;
;; Array-valued columns follow.
;;
cspice_ekrced, handle, segno, i, cnames[1], nelts, $
dvals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[1], ' record number: ',i
print, dvals
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: DP_COL_1 record number: 0
0.0000000
Data from column: DP_COL_2 record number: 0
0.0000000 1.0000000 2.0000000
Data from column: DP_COL_1 record number: 2
2.0000000
Data from column: DP_COL_2 record number: 2
20.000000 21.000000 22.000000
Data from column: DP_COL_1 record number: 3
-3.0000000
Data from column: DP_COL_2 record number: 3
-30.000000 -31.000000 -32.000000
Data from column: DP_COL_1 record number: 4
4.0000000
Data from column: DP_COL_2 record number: 4
40.000000 41.000000 42.000000
Data from column: DP_COL_1 record number: 5
-5.0000000
Data from column: DP_COL_2 record number: 5
-50.000000 -51.000000 -52.000000
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.
Since columns of data type TIME are implemented using double
precision column classes, this routine may be used to update
columns of type TIME.
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 DOUBLE
PRECISION or TIME, 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 a double
precision 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', `dvals' 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', `dvals' 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_ekrced" 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 d.p. entry in an EK column
replace time entry in an EK column
|