Table of contents
CSPICE_EKCLS closes an EK file opened for a read or write.
This routine must close any EK file opened for write.
Given:
handle the file handle of an EK to be closed.
help, handle
LONG = Scalar
Note that EKs open for writing must be closed by this routine
in order to be valid.
the call:
cspice_ekcls, handle
closes the file. The close operation tests the file to
ensure the presence of data segments.
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.
The example shows the effect of the cspice_ekcls calls when the EK
file has been opened for write or read access.
Example code begins here.
PRO ekcls_ex1
;;
;; Constants
;;
EKNAME = "ekcls_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 should be used to close open EK files. EK files
open for writing *must* be closed by this routine in order to be
valid. EK files open for read access should also be closed using
this routine.
1) If the indicated file is not recognized, no error is
signaled.
2) 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.
3) If the input argument `handle' is undefined, an error is
signaled by the IDL error handling system.
4) If the input argument `handle' 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, 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.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added argument's type and size information in the -I/O section.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
close EK
|