Table of contents
CSPICE_EKINSR inserts a new, empty record into specified EK
segment at a specified index.
Given:
handle a file handle of an EK open for write access.
help, handle
LONG = Scalar
segno the number of the segment to which the record is to be added.
help, segno
LONG = Scalar
recno the index of the new record.
help, recno
LONG = Scalar
`recno' must be in the range 0:nrec, where `nrec' is the number
of records in the segment prior to the insertion. If `recno' is
equal to `nrec', the new record is appended. Otherwise, the new
record has the ordinal position specified by `recno', and the
records previously occupying positions recno:nrec have their
indexes incremented by 1.
the call:
cspice_ekinsr, handle, segno, recno
inserts a new record at index `recno' in EK segment `segno' from
the EK 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 insert a new,
empty record into a given EK segment at a specified index.
The program creates a new EK, sets up the table, column names
and declarations for a segment, and adds 100 records of
simple integer data values. After closing and reopening the
file, every other record is deleted and then new data is
inserted right on the records that have been deleted.
Before and after deleting records, a summary of the EK is
produced.
Example code begins here.
PRO ekinsr_ex1
;;
;; Constants
;;
SPICETRUE = 1B
SPICEFALSE = 0B
SPICE_EK_CNAMSZ = 32
SPICE_EK_CSTRLN = SPICE_EK_CNAMSZ + 1
SPICE_EK_TNAMSZ = 64
SPICE_EK_TSTRLN = SPICE_EK_TNAMSZ + 1
EKNAME = 'ekinsr_ex.bdb'
IFNAME = 'Test EK'
NCOLS = 1
NROWS = 100
NRESVC = 0
TABLE = 'SCALAR_DATA'
MAXVAL = 10
;;
;; Declare memory for the column data.
;;
ivals = intarr( 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.
;;
if ( cspice_exists (EKNAME) ) then begin
file_delete, EKNAME
endif
;;
;; Create the new EK.
;;
cspice_ekopn, EKNAME, IFNAME, NRESVC, handle
;;
;; Set up the table and column names and declarations
;; for the SCALAR_DATA segment.
;;
cdecls = strarr(NCOLS)
cnames = strarr(NCOLS)
cnames[0] = "INT_COL_1"
cdecls[0] = "DATATYPE = INTEGER, INDEXED = TRUE, " +$
"NULLS_OK = TRUE"
;;
;; Start the segment.
;;
cspice_ekbseg, handle, TABLE, NCOLS, cnames, cdecls, segno
;;
;; Add NROWS simple data values.
;;
for i = 0, (NROWS-1) do begin
cspice_ekappr, handle, segno, recno
isnull = SPICEFALSE
ivals[0] = i
cspice_ekacei, handle, segno, recno, cnames[0], $
1, ivals, isnull
endfor
;;
;; Summarize the EK.
;;
cspice_ekssum, handle, segno, sum_nrow, sum_ncol, $
tabnam, cnames, cclass , dtype , $
size , strlen, indexd , nullok
;;
;; Display the number of rows in the EK.
;;
print, 'Number of rows before delete: ', sum_nrow
;; End the file.
;;
cspice_ekcls, handle
;;
;; Update the EK: delete half the records
;; via a cspice_ekdelr call. First, open the file for
;; write access.
;;
cspice_ekopw, EKNAME, handle
;;
;; Perform the delete. Delete every other record.
;;
for i = 0, ( (NROWS/2) - 1) do begin
cspice_ekdelr, handle, 0, i
endfor
;;
;; Summarize the EK.
;;
cspice_ekssum, handle, segno, sum_nrow, sum_ncol, $
tabnam, cnames, cclass , dtype , $
size , strlen, indexd , nullok
;;
;; Display the number of rows in the EK.
;;
print, 'Number of rows after delete : ', sum_nrow
;;
;; Insert new data into the deleted records.
;;
for i = 0, ( NROWS - 1 ), 2 do begin
recno = i;
cspice_ekinsr, handle, segno, recno
ivals[0] = i
isnull = 0
cspice_ekacei, handle, segno, recno, cnames[0], $
1, ivals, isnull
endfor
;;
;; Summarize the EK.
;;
cspice_ekssum, handle, segno, sum_nrow, sum_ncol, $
tabnam, cnames, cclass , dtype , $
size , strlen, indexd , nullok
;;
;; Display the number of rows in the EK.
;;
print, 'Number of rows after insert : ', sum_nrow
;;
;; End the file.
;;
cspice_ekcls, handle
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Number of rows before delete: 100
Number of rows after delete : 50
Number of rows after insert : 100
Note that after run completion, a new EK exists in the output
directory.
This routine operates by side effects: It adds a new, empty
record structure to an EK segment at a specified ordinal position.
After a record has been inserted into a segment by this routine,
the record must be populated with data using the cspice_ekaceX
routines. EKs are valid only when all of their column entries
are initialized.
To append a record to a segment, use the routine cspice_ekappr.
This routine cannot be used with the "fast write" suite of
routines. See the EK Required Reading ek.req for a discussion of
the fast writers.
When a record is inserted into an EK file that is not shadowed,
the status of the record starts out set to OLD. The status
does not change when data is added to the record.
If the target EK is shadowed, the new record will be given the
status NEW. Updating column values in the record does not change
its status. When changes are committed, the status is set to OLD.
If a rollback is performed before changes are committed, the
record is deleted. Closing the target file without committing
changes implies a rollback.
1) If `handle' is invalid, an error is signaled by a routine in the
call tree of this routine. The file will not be modified.
2) If `segno' is out of range, the error SPICE(INVALIDINDEX) is
signaled by a routine in the call tree of this routine. The
file will not be modified.
3) If `recno' is out of range, the error SPICE(INVALIDINDEX) is
signaled by a routine in the call tree of this routine. The
file will not be modified.
4) 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. The file may be corrupted.
5) If any of the input arguments, `handle', `segno' or `recno',
is undefined, an error is signaled by the IDL error handling
system.
6) If any of the input arguments, `handle', `segno' or `recno',
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.1, 24-NOV-2021 (JDR)
Edited the header 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.0, 16-JUN-2003 (EDW)
insert record into EK segment
|