Table of contents
CSPICE_EKSSUM returns summary information for a specified segment in a
specified EK.
Given:
handle the scalar integer handle for the EK containing the segment to
be summarized.
help, handle
LONG = Scalar
segno the scalar integer segment number of the segment whose summary
is desired.
help, segno
LONG = Scalar
Segments are numbered from 0 to NSEG-1, where NSEG is the count
of segments in the file.
the call:
cspice_ekssum, handle, segno , nrows, ncols, tabnam, $
cnames, cclass, dtype, sizes, strlen, $
indexd, nullok
returns:
nrows the scalar integer count of rows in segment 'segno'.
help, nrows
LONG = Scalar
ncols the scalar integer count of columns in segment 'segno'.
help, ncols
LONG = Scalar
tabnam a string naming the table containing the segment.
help, tabnam
STRING = Scalar
cnames a string array of column names in the segment.
help, cnames
STRING = Array[N]
The following return arguments hold the summary information
for the columns named in 'cnames'. The ith entry
in each array corresponds to the ith column name in 'cnames'
cclass integer array of column class codes.
help, cclass
LONG = Array[N]
dtype integer array of column data type codes.
help, dtype
LONG = Array[N]
The correspondence between data type and integer codes:
SPICE_CHR = 0 (Character data)
SPICE_DP = 1 (Double precision data)
SPICE_INT = 2 (Integer data)
SPICE_TIME = 3 (SPICE representation of times)
sizes integer array of column entry sizes, i.e.
help, sizes
LONG = Array[N]
the count of array elements in a column entry.
strlen integer array containing the string length for columns of data
type SPICE_CHR.
help, strlen
LONG = Array[N]
indexd boolean array indicating whether a particular column is indexed
(TRUE) or not (FALSE).
help, indexd
BOOLEAN = Array[N]
nullok boolean array indicating whether a particular column may contain
null values (TRUE) or not (FALSE).
help, nullok
BOOLEAN = Array[N]
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) Open an EK and summarize each segment, and each column within,
providing the table name, the number of columns and rows, and
for each column, its class, name, data type, dimension, index
flag and whether nulls are allowed within.
Use the EK kernel below to load the Deep Impact spacecraft
subsystem commands dictionary, and provide its summary.
dif_cmdict_128_20050620.bdb
Example code begins here.
PRO ekssum_ex1
;;
;; Open the file named by EK, returning the file handle
;; associated with the open file to the variable named
;; 'handle'.
;;
EK = 'dif_cmdict_128_20050620.bdb'
cspice_ekopr, EK, handle
;;
;; Set the data type codes. A column of data in
;; an EK has one of four data types.
;;
;; Character
;;
SPICE_CHR = 0
;;
;; Double precision
;;
SPICE_DP = 1
;;
;; Integer
;;
SPICE_INT = 2
;;
;; Time
;;
SPICE_TIME = 3
;;
;; Return the number of segments in EK.
;;
nseg = cspice_eknseg ( handle )
;;
;; Loop over each segment, summarizing the segment as we go.
;;
for segno = 0, (nseg-1) do begin
;;
;; Retrieve the segment summary in the file identified by
;; file handle 'handle'.
;;
;;
cspice_ekssum, handle, segno, nrow, ncol, $
tabnam, cnames, cclass, dtype, $
size , strlen, indexd, nullok
print, 'Table name ', tabnam
print, 'Ncols ', ncol
print, 'Nnrows ', nrow
;;
;; Loop over each column found in the segment.
;;
for colno = 0, (ncol-1) do begin
print, ' Name and attributes of column: ', colno
print, ' column class ', cclass[colno]
print, ' column name ', cnames[colno]
print, ' data type ', dtype[colno]
;;
;; Respond as appropriate for the data type in the column
;;
case dtype[colno] of
SPICE_CHR : begin
print, ' String with length ', $
strlen[colno]
end
SPICE_INT : begin
print, ' Integer'
end
SPICE_DP : begin
print, ' Double precision'
end
SPICE_TIME : begin
print, ' Time value'
end
else: print, ' dtype value error'
endcase
print, ' dimension ', size[colno]
print, ' index flag ', indexd[colno]
print, ' nulls allowed flag ', nullok[colno]
print, ' '
endfor
endfor
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Table name DIF_COMMANDS
Ncols 7
Nnrows 5798
Name and attributes of column: 0
column class 3
column name SUBSYSTEM
data type 0
String with length 32
dimension 1
index flag 1
nulls allowed flag 0
Name and attributes of column: 1
column class 3
column name COMMAND
data type 0
String with length 32
dimension 1
index flag 1
nulls allowed flag 0
Name and attributes of column: 2
column class 3
column name PARAMETER_NAME
data type 0
String with length 32
dimension 1
index flag 1
nulls allowed flag 0
Name and attributes of column: 3
column class 1
column name PARAMETER_INDEX
data type 2
Integer
dimension 1
index flag 1
nulls allowed flag 0
Name and attributes of column: 4
column class 3
column name PARAMETER_TYPE
data type 0
String with length 32
dimension 1
index flag 0
nulls allowed flag 1
Name and attributes of column: 5
column class 6
column name PARAMETER_RANGE
data type 0
String with length 80
dimension -1
index flag 0
nulls allowed flag 1
Name and attributes of column: 6
column class 6
column name DESCRIPTION
data type 0
String with length 80
dimension -1
index flag 0
nulls allowed flag 0
This routine supports the function of summarizing a binary
EK file, allowing NAIF Toolkit users to determine whether it
contains data of interest. The routine also also provides
address information necessary to retrieve information from the
segment.
1) If `handle' is invalid, an error is signaled by a routine in the
call tree of this routine. The output arguments will not be
modified.
2) If `segno' is not the index of an existing segment in the
specified file, the error SPICE(INDEXOUTOFRANGE) is signaled by
a routine in the call tree of this routine. The output arguments
will not be modified.
3) If an I/O error occurs while attempting to obtain summary
information for the specified segment, the error is signaled
by a routine in the call tree of this routine. The output
arguments may be modified in this case.
4) If any of the input arguments, `handle' or `segno', is undefined,
an error is signaled by the IDL error handling system.
5) If any of the input arguments, `handle' or `segno', 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 any of the output arguments, `nrows', `ncols', `tabnam',
`cnames', `cclass', `dtype', `sizes', `strlen', `indexd' or
`nullok', is not a named variable, an error is signaled by the
Icy interface.
See the description of `handle' in -I/O.
None.
ICY.REQ
EK.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
example's problem statement and example's EK.
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 arguments' type and size information in the -I/O section.
-Icy Version 1.0.1, 22-FEB-2010 (EDW)
Updated header to list output of example code.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
return EK segment summary
|