Table of contents
CSPICE_EKOPW opens an existing E-kernel file for writing.
Given:
fname the scalar string holding the name of an existing E-kernel file
to be opened for write access.
help, fname
STRING = Scalar
the call:
cspice_ekopw, fname, handle
returns:
handle a scalar integer DAS file handle of the EK designate by `fname'.
help, handle
LONG = Scalar
This handle is used to identify the file to other EK routines.
SPICE_DAS_FTSIZE
is the maximum number of DAS files that a user can
have open simultaneously. This includes any files used
by the DAS system.
See the parameter definitions file IcyDAS.pro for the actual
value of this parameter.
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 re-open the file for write access and update the
data, and how to read the data from it.
Example code begins here.
PRO ekopw_ex1
;;
;; Local parameters.
;;
EKNAME = "ekopw_ex1.bdb"
IFNAME = "Test EK"
NCOLS = 2
NROWS = 6
NRESVC = 0
TABLE = "CHR_DATA"
CVLEN = 10
MAXVAL = 10
;;
;; Local variables.
;;
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 should be used to open an EK existing file for write
access.
Opening an EK file with this routine makes the EK accessible to
the following Icy EK access routines, all of which modify
the target EK file:
Begin segment:
cspice_ekbseg
Append, insert, delete records:
cspice_ekappr
cspice_ekinsr
cspice_ekdelr
Add column entries:
cspice_ekacec
cspice_ekaced
cspice_ekacei
Update existing column entries:
cspice_ekucec
cspice_ekuced
cspice_ekucei
Execute fast write:
cspice_ekifld
cspice_ekffld
cspice_ekaclc
cspice_ekacld
cspice_ekacli
An EK opened for write access is also accessible for reading.
The file may be accessed by the Icy EK readers
cspice_ekrcec
cspice_ekrced
cspice_ekrcei
and summary routines:
cspice_eknseg
cspice_ekssum
An EK opened for write access cannot be queried. To make an EK available
to the EK query system, the file must be loaded via cspice_furnsh or
cspice_eklef, rather than by this routine. See the EK Required Reading
for further information.
1) If the indicated file cannot be opened, an error is signaled
by a routine in the call tree of this routine.
2) If the indicated file has the wrong architecture version, an
error is signaled by a routine in the call tree of this
routine.
3) 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.
4) If the input argument `fname' is undefined, an error is
signaled by the IDL error handling system.
5) If the input argument `fname' is not of the expected type, or
it does not have the expected dimensions and size, an error is
signaled by the Icy interface.
6) If the output argument `handle' is not a named variable, an
error is signaled by the Icy interface.
See the EK Required Reading ek.req for a discussion of the EK file
format.
1) No more than SPICE_DAS_FTSIZE DAS files may be opened simultaneously.
See the parameter definitions file IcyDAS.pro for the value of
SPICE_DAS_FTSIZE.
EK.REQ
ICY.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.2, 31-MAY-2021 (JDR)
Edited the header to comply with NAIF standard. Added complete
code example.
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections, and
completed -Particulars section. Updated index entry.
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-2013 (EDW)
Edits to comply with NAIF standard for Icy headers.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
open existing EK for writing
|