Table of contents
CSPICE_EKUCEC updates a character 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 `cvals' to update.
help, nvals
LONG = Scalar
cvalen a scalar integer defining the maximum length of a string in
`cvals'.
help, cvalen
LONG = Scalar
cvals an array of strings containing the data values to update to the
record in 'column'.
help, cvals
STRING = Array[N]
Note: `nvals' specifies the number of `cvals'
entries written to the updated record.
isnull a scalar boolean flagging whether the entry is null.
help, isnull
BOOLEAN = Scalar
the call:
cspice_ekucec, handle, segno, recno, column, $
nvals , cvalen, cvals, isnull
updates `nvals' of `cvals' to with length `cvalen' 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 character 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 ekucec_ex1
;;
;; Constants
;;
EKNAME = "ekucec_ex1.bdb"
IFNAME = "Test EK"
NCOLS = 2
NROWS = 6
NRESVC = 0
TABLE = "CHR_DATA"
CVLEN = 10
MAXVAL = 10
cvals = strarr( MAXVAL )
;;
;; 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.
;;
cspice_ekopn, EKNAME, IFNAME, NRESVC, handle
;;
;; Set up the table and column names and declarations
;; for the CHR_DATA segment. We'll index all of
;; the columns.
;;
cdecls = strarr(NCOLS)
cnames = strarr(NCOLS)
cnames[0] = "CHR_COL_1"
cdecls[0] = "DATATYPE = CHARACTER*(*), INDEXED = TRUE,"+$
" NULLS_OK = TRUE"
cnames[1] = "CHR_COL_2"
cdecls[1] = "DATATYPE = CHARACTER*(9), 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 )
cvals[0] = string(i)
cspice_ekacec, handle, segno, recno, cnames[0], $
1 , CVLEN, cvals, isnull
;;
;; Array-valued columns follow.
;;
cvals[0] = string( 10*i )
cvals[1] = string((10*i) + 1)
cvals[2] = string((10*i) + 2)
cvals[3] = string((10*i) + 3)
cspice_ekacec, handle, segno, recno, cnames[1], $
4 , CVLEN, cvals, 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 )
cvals[0] = string(-i)
cspice_ekucec, handle, segno, recno, cnames[0], $
1 , CVLEN, cvals, isnull
;;
;; Array-valued columns follow.
;;
cvals[0] = string( -10*i )
cvals[1] = string(-((10*i) + 1))
cvals[2] = string(-((10*i) + 2))
cvals[3] = string(-((10*i) + 3))
cspice_ekucec, handle, segno, recno, cnames[1], $
4 , CVLEN, cvals, isnull
endfor
;;
;; Close 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_ekrcec, handle, segno, i, cnames[0], MAXVAL, $
CVLEN, cvals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[0],' record number: ',i
print, cvals
print
endif else begin
print, 'Record ', i, ' flag is NULL.'
print
endelse
;;
;; Array-valued columns follow.
;;
cspice_ekrcec, handle, segno, i, cnames[1], MAXVAL, $
CVLEN, cvals, isnull
if ( NOT isnull ) then begin
print, 'Data from column: ',cnames[1], ' record number: ',i
print, cvals
print
endif
endfor
;;
;; Close 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: CHR_COL_1 record number: 0
0
Data from column: CHR_COL_2 record number: 0
0 1 2 3
Record 1 flag is NULL.
Data from column: CHR_COL_1 record number: 2
2
Data from column: CHR_COL_2 record number: 2
20 21 22 23
Data from column: CHR_COL_1 record number: 3
-3
Data from column: CHR_COL_2 record number: 3
-30 -31 -32 -33
Data from column: CHR_COL_1 record number: 4
4
Data from column: CHR_COL_2 record number: 4
40 41 42 43
Data from column: CHR_COL_1 record number: 5
-5
Data from column: CHR_COL_2 record number: 5
-50 -51 -52 -53
Note that the second record does not appear due to setting the
`isnull' flag to true for that record. 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
CHARACTER, 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 character
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', `cvalen', `cvals' 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', `cvalen', `cvals' 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.1.0, 25-AUG-2021 (JDR)
Changed the input argument name "cvals_len" to "cvalen" for
consistency with other routines.
Edited the -Examples section to comply with NAIF standard. Added
example's problem statement, and a note after the example's
output.
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 character entry in an EK column
|