| ekgd |
|
Table of contents
Procedure
EKGD ( EK, get event data, double precision )
ENTRY EKGD ( SELIDX, ROW, ELMENT, DDATA, NULL, FOUND )
Abstract
Return an element of an entry in a column of double precision
or `time' type in a specified row.
Required_Reading
EK
Keywords
ASSIGNMENT
EK
Declarations
INTEGER SELIDX
INTEGER ROW
INTEGER ELMENT
DOUBLE PRECISION DDATA
LOGICAL NULL
LOGICAL FOUND
Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
SELIDX I Index of parent column in SELECT clause.
ROW I Row to fetch from.
ELMENT I Index of element, within column entry, to fetch.
DDATA O D.p. element of column entry.
NULL O Flag indicating whether column entry was null.
FOUND O Flag indicating whether column was present in row.
Detailed_Input
SELIDX is the SELECT clause index of the column to
fetch from.
ROW is the output row containing the entry to fetch
from.
ELMENT is the index of the element of the column entry
to fetch. The normal range of ELMENT is from 1 to
the size of the column's entry, but ELMENT is
allowed to exceed the number of elements in the
column entry; if it does, FOUND is returned .FALSE.
This allows the caller to read data from the column
entry in a loop without checking the number of
available elements first.
Null values in variable-sized columns are
considered to have size 1.
Detailed_Output
DDATA is the requested element of the specified column
entry. If the entry is null, DDATA is undefined.
NULL is a logical flag indicating whether the entry
belonging to the specified column in the specified
row is null.
FOUND is a logical flag indicating whether the specified
element was found. If the element does not exist,
FOUND is returned .FALSE.
Parameters
None.
Exceptions
1) If the input argument ELMENT is less than 1, the error
SPICE(INVALIDINDEX) is signaled and FOUND is returned .FALSE.
However, ELMENT is allowed to be greater than the number of
elements in the specified column entry; this allows the caller
to read data from the column entry in a loop without checking
the number of available elements first. If ELMENT is greater
than the number of available elements, FOUND is returned
.FALSE.
2) If SELIDX is outside of the range established by the
last query passed to EKSRCH, the error SPICE(INVALIDINDEX)
is signaled and FOUND is returned .FALSE.
3) If the input argument ROW is less than 1 or greater than the
number of rows matching the query, the error
SPICE(INVALIDINDEX) is signaled and FOUND is returned .FALSE.
4) If the specified column does not have DP or TIME type, the
error SPICE(INVALIDTYPE) is signaled.
5) If this routine is called when no E-kernels have been loaded,
the error SPICE(NOLOADEDFILES) is signaled.
Files
See the header of EKQMGR for a description of files used
by this routine.
Particulars
This routine allows retrieval of data from double precision or
`time' columns.
This routine returns one element at a time in order to save the
caller from imposing a limit on the size of the column entries
that can be handled.
Examples
The numerical results shown for these examples may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, and the machine
specific arithmetic implementation.
1) Perform a query on an EK file that contains a database with
the Supplementary Engineering Data Records of the Viking
Project in order to retrieve the PLATFORM_CLOCK values (double
precision) that correspond to the images with IMAGE_NUMBER
smaller than a given value, ordered by IMAGE_NUMBER.
Use the EK kernel below to load the information from the
original Supplementary Engineering Data Record (SEDR) data
set generated by the Viking Project.
vo_sedr.bdb
Example code begins here.
PROGRAM EKGD_EX1
IMPLICIT NONE
C
C Include the EK Maximum length of an input query,
C MAXQRY, and the maximum length of literal string
C values, MAXSTR, from eklimit.inc.
C
INCLUDE 'ekqlimit.inc'
C
C Local parameters
C
CHARACTER*(*) EKNAME
PARAMETER ( EKNAME = 'vo_sedr.bdb' )
INTEGER ERRLEN
PARAMETER ( ERRLEN = 1840 )
C
C Local variables
C
CHARACTER*(ERRLEN) ERRMSG
CHARACTER*(MAXQRY) QUERY
DOUBLE PRECISION DDATA
INTEGER ELTIDX
INTEGER NMROWS
INTEGER ROWNO
INTEGER SELIDX
LOGICAL ERROR
LOGICAL FOUND
LOGICAL ISNULL
C
C Open an EK file.
C
CALL FURNSH ( EKNAME )
C
C The table 'VIKING_SEDR_DATA' has a column
C 'PLATFORM_CLOCK' of double precision values.
C
C Define a set of constraints to perform a query on
C all loaded EK files (the SELECT clause). In this
C case select the column 'PLATFORM_CLOCK' from table
C 'VIKING_SEDR_DATA' sorted by 'IMAGE_NUMBER'.
C
QUERY = 'Select PLATFORM_CLOCK from VIKING_SEDR_DATA '
. // 'where IMAGE_NUMBER < 25860000 '
. // 'order by IMAGE_NUMBER'
C
C Query the EK system for data rows matching the
C SELECT constraints.
C
CALL EKFIND ( QUERY, NMROWS, ERROR, ERRMSG )
C
C Check whether an error occurred while processing the
C SELECT clause. If so, output the error message.
C
IF ( ERROR ) THEN
WRITE(*,*) 'SELECT clause error: ', ERRMSG
ELSE
C
C Fetch the character data. We know the query returned
C one column and the column contains only scalar data,
C so the index of all elements is 1.
C
SELIDX = 1
ELTIDX = 1
C
C Loop over each row found matching the query.
C
DO ROWNO = 1, NMROWS
C
C Use EKGD to retrieve the string from
C
CALL EKGD ( SELIDX, ROWNO, ELTIDX,
. DDATA, ISNULL, FOUND )
IF ( ISNULL ) THEN
WRITE (*,'(A,I3,A)') 'Row ', ROWNO,
. ': Double precision data: <Null>'
ELSE
WRITE (*,'(A,I3,A,F10.6)') 'Row ', ROWNO,
. ': Double precision data: ', DDATA
END IF
END DO
END IF
END
When this program was executed on a Mac/Intel/gfortran/64-bit
platform, the output was:
Row 1: Double precision data: 119.880000
Row 2: Double precision data: 119.270000
Row 3: Double precision data: 119.880000
Row 4: Double precision data: 119.270000
Row 5: Double precision data: 119.880000
Row 6: Double precision data: 119.270000
Row 7: Double precision data: 120.140000
Row 8: Double precision data: 119.520000
Row 9: Double precision data: 120.140000
Row 10: Double precision data: 120.140000
Row 11: Double precision data: 120.140000
Row 12: Double precision data: 221.920000
Row 13: Double precision data: 221.920000
Row 14: Double precision data: 221.920000
Row 15: Double precision data: 120.140000
Row 16: Double precision data: 120.140000
Row 17: Double precision data: 120.140000
Row 18: Double precision data: 120.220000
Row 19: Double precision data: 120.220000
Row 20: Double precision data: 120.220000
Row 21: Double precision data: 120.370000
Row 22: Double precision data: 120.370000
Row 23: Double precision data: 120.370000
Row 24: Double precision data: 120.290000
Row 25: Double precision data: 120.290000
Row 26: Double precision data: 120.290000
2) Perform a query on an EK file that contains a database with
the Supplementary Engineering Data Records of the Viking
Project in order to retrieve the IMAGE_TIME values (double
precision time) that correspond to the images with
IMAGE_NUMBER smaller than a given value, ordered by
IMAGE_NUMBER.
Use the EK kernel below to load the information from the
original Supplementary Engineering Data Record (SEDR) data
set generated by the Viking Project.
vo_sedr.bdb
Use the LSK kernel below to load the leap seconds and time
constants required for the conversions.
naif0012.tls
Example code begins here.
PROGRAM EKGD_EX2
IMPLICIT NONE
C
C Include the EK Maximum length of an input query,
C MAXQRY, and the maximum length of literal string
C values, MAXSTR, from eklimit.inc.
C
INCLUDE 'ekqlimit.inc'
C
C Local parameters
C
CHARACTER*(*) EKNAME
PARAMETER ( EKNAME = 'vo_sedr.bdb' )
CHARACTER*(*) LSKNAM
PARAMETER ( LSKNAM = 'naif0012.tls' )
INTEGER ERRLEN
PARAMETER ( ERRLEN = 1840 )
INTEGER TIMLEN
PARAMETER ( TIMLEN = 24 )
C
C Local variables
C
CHARACTER*(ERRLEN) ERRMSG
CHARACTER*(MAXQRY) QUERY
CHARACTER*(TIMLEN) UTCSTR
DOUBLE PRECISION DDATA
INTEGER ELTIDX
INTEGER NMROWS
INTEGER ROWNO
INTEGER SELIDX
LOGICAL ERROR
LOGICAL FOUND
LOGICAL ISNULL
C
C Load leapseconds file for time conversion.
C
CALL FURNSH ( LSKNAM )
C
C Open an EK file.
C
CALL FURNSH ( EKNAME )
C
C The table 'VIKING_SEDR_DATA' has a column
C 'IMAGE_TIME' of time values (stored as double
C precision items).
C
C Define a set of constraints to perform a query on
C all loaded EK files (the SELECT clause). In this
C case select the column 'IMAGE_TIME' from table
C 'VIKING_SEDR_DATA' sorted by 'IMAGE_NUMBER'.
C
QUERY = 'Select IMAGE_TIME from VIKING_SEDR_DATA '
. // 'where IMAGE_NUMBER < 25860000 '
. // 'order by IMAGE_NUMBER'
C
C Query the EK system for data rows matching the
C SELECT constraints.
C
CALL EKFIND ( QUERY, NMROWS, ERROR, ERRMSG )
C
C Check whether an error occurred while processing the
C SELECT clause. If so, output the error message.
C
IF ( ERROR ) THEN
WRITE(*,*) 'SELECT clause error: ', ERRMSG
ELSE
C
C Fetch the character data. We know the query returned
C one column and the column contains only scalar data,
C so the index of all elements is 1.
C
SELIDX = 1
ELTIDX = 1
C
C Loop over each row found matching the query.
C
DO ROWNO = 1, NMROWS
C
C Use EKGD to retrieve the string from
C
CALL EKGD ( SELIDX, ROWNO, ELTIDX,
. DDATA, ISNULL, FOUND )
IF ( ISNULL ) THEN
WRITE (*,'(A,I3,A)') 'Row ', ROWNO,
. ': Time data: <Null>'
ELSE
CALL ET2UTC ( DDATA, 'C', 3, UTCSTR )
WRITE (*,'(A,I3,2A)') 'Row ', ROWNO,
. ': Time data: ', UTCSTR
END IF
END DO
END IF
END
When this program was executed on a Mac/Intel/gfortran/64-bit
platform, the output was:
Row 1: Time data: 1976 JUN 16 16:50:55.925
Row 2: Time data: 1976 JUN 16 16:51:00.269
Row 3: Time data: 1976 JUN 16 20:56:53.051
Row 4: Time data: 1976 JUN 16 20:56:57.395
Row 5: Time data: 1976 JUN 17 01:02:50.177
Row 6: Time data: 1976 JUN 17 01:02:54.521
Row 7: Time data: 1976 JUN 17 05:08:56.263
Row 8: Time data: 1976 JUN 17 05:09:00.607
Row 9: Time data: 1976 JUN 17 06:30:28.424
Row 10: Time data: 1976 JUN 17 06:30:46.174
Row 11: Time data: 1976 JUN 17 06:30:55.168
Row 12: Time data: 1976 JUN 17 11:17:47.471
Row 13: Time data: 1976 JUN 17 11:18:05.221
Row 14: Time data: 1976 JUN 17 11:18:14.215
Row 15: Time data: 1976 JUN 17 13:20:23.634
Row 16: Time data: 1976 JUN 17 13:20:41.384
Row 17: Time data: 1976 JUN 17 13:20:50.378
Row 18: Time data: 1976 JUN 17 15:23:17.717
Row 19: Time data: 1976 JUN 17 15:23:35.467
Row 20: Time data: 1976 JUN 17 15:23:44.461
Row 21: Time data: 1976 JUN 17 17:26:20.760
Row 22: Time data: 1976 JUN 17 17:26:38.510
Row 23: Time data: 1976 JUN 17 17:26:47.504
Row 24: Time data: 1976 JUN 17 19:29:23.803
Row 25: Time data: 1976 JUN 17 19:29:41.553
Row 26: Time data: 1976 JUN 17 19:29:50.547
3) This example demonstrates how to fetch double precision values
from a column in three different cases: single values,
variable-size arrays and static-size arrays.
Create an EK that contains a table TAB that has the following
columns:
Column name Data Type Size
----------- --------- ----
DP_COL_1 DP 1
DP_COL_2 DP VARIABLE
DP_COL_3 DP 3
Issue the following query
QUERY = 'SELECT DP_COL_1, DP_COL_2, DP_COL_3 FROM TAB'
to fetch and dump column values from the rows that satisfy the
query.
Example code begins here.
PROGRAM EKGD_EX3
IMPLICIT NONE
C
C Include the EK Column Name Size (CNAMSZ)
C and EK Query Limit Parameters (MAXQRY)
C
INCLUDE 'ekcnamsz.inc'
INCLUDE 'ekqlimit.inc'
C
C Local parameters
C
CHARACTER*(*) EKNAME
PARAMETER ( EKNAME = 'ekgd_ex3.bdb' )
CHARACTER*(*) TABLE
PARAMETER ( TABLE = 'TAB' )
INTEGER COL3SZ
PARAMETER ( COL3SZ = 3 )
INTEGER DECLEN
PARAMETER ( DECLEN = 200 )
INTEGER ERRLEN
PARAMETER ( ERRLEN = 1840 )
INTEGER MXC2SZ
PARAMETER ( MXC2SZ = 4 )
INTEGER NAMLEN
PARAMETER ( NAMLEN = 40 )
INTEGER NCOLS
PARAMETER ( NCOLS = 3 )
INTEGER NROWS
PARAMETER ( NROWS = 4 )
C
C Local variables
C
CHARACTER*(DECLEN) CDECLS ( NCOLS )
CHARACTER*(CNAMSZ) CNAMES ( NCOLS )
CHARACTER*(ERRLEN) ERRMSG
CHARACTER*(NAMLEN) IFNAME
CHARACTER*(MAXQRY) QUERY
DOUBLE PRECISION COL1
DOUBLE PRECISION COL2 ( MXC2SZ )
DOUBLE PRECISION COL3 ( COL3SZ )
DOUBLE PRECISION DVALS ( MXC2SZ )
INTEGER ELTIDX
INTEGER HANDLE
INTEGER I
INTEGER J
INTEGER NELT
INTEGER NMROWS
INTEGER NRESVC
INTEGER RECNO
INTEGER ROW
INTEGER SEGNO
INTEGER SELIDX
LOGICAL ERROR
LOGICAL FOUND
LOGICAL ISNULL
C
C Open a new EK file. For simplicity, we will not
C reserve any space for the comment area, so the
C number of reserved comment characters is zero.
C The variable IFNAME is the internal file name.
C
NRESVC = 0
IFNAME = 'Test EK/Created 13-JUN-2019'
CALL EKOPN ( EKNAME, IFNAME, NRESVC, HANDLE )
C
C Set up the column names and declarations
C for the TAB segment. We'll index all of
C the columns.
C
CNAMES(1) = 'DP_COL_1'
CDECLS(1) = 'DATATYPE = DOUBLE PRECISION, ' //
. 'INDEXED = TRUE'
CNAMES(2) = 'DP_COL_2'
CDECLS(2) = 'DATATYPE = DOUBLE PRECISION, ' //
. 'SIZE = VARIABLE'
CNAMES(3) = 'DP_COL_3'
CDECLS(3) = 'DATATYPE = DOUBLE PRECISION, ' //
. 'SIZE = 3'
C
C Start the segment.
C
CALL EKBSEG ( HANDLE, TABLE, NCOLS,
. CNAMES, CDECLS, SEGNO )
C
C At the records to the table.
C
DO I = 1, NROWS
C
C Append a new record to the EK.
C
CALL EKAPPR ( HANDLE, SEGNO, RECNO )
C
C Add DP_COL_1
C
COL1 = I * 100.D0
CALL EKACED ( HANDLE, SEGNO, RECNO,
. CNAMES(1), 1, COL1, .FALSE. )
C
C Add I items to DP_COL_2
C
DO J = 1, I
COL2(J) = J + I*200.D0
END DO
CALL EKACED ( HANDLE, SEGNO, RECNO,
. CNAMES(2), I, COL2, .FALSE. )
C
C Add 3 items to DP_COL_3
C
DO J = 1, 3
COL3(J) = I + J*100.D0
END DO
CALL EKACED ( HANDLE, SEGNO, RECNO,
. CNAMES(3), 3, COL3, .FALSE. )
END DO
C
C Close the file.
C
CALL EKCLS ( HANDLE )
C
C Open the created file. Perform the query and show the
C results.
C
CALL FURNSH ( EKNAME )
QUERY = 'SELECT DP_COL_1, DP_COL_2, DP_COL_3 FROM TAB'
C
C Query the EK system for data rows matching the
C SELECT constraints.
C
CALL EKFIND ( QUERY, NMROWS, ERROR, ERRMSG )
C
C Check whether an error occurred while processing the
C SELECT clause. If so, output the error message.
C
IF ( ERROR ) THEN
WRITE(*,*) 'SELECT clause error: ', ERRMSG
ELSE
DO ROW = 1, NMROWS
WRITE(*,*) ' '
WRITE(*,'(A,I3)') 'ROW = ', ROW
C
C Fetch values from column DP_COL_1. Since
C DP_COL_1 was the first column selected, the
C selection index SELIDX is set to 1.
C
SELIDX = 1
ELTIDX = 1
CALL EKGD ( SELIDX, ROW, ELTIDX,
. DVALS(1), ISNULL, FOUND )
IF ( ISNULL ) THEN
WRITE(*,*) ' COLUMN = DP_COL_1: <Null>'
ELSE
WRITE(*,*) ' COLUMN = DP_COL_1:', DVALS(1)
END IF
C
C Fetch values from column DP_COL_2 in the current
C row. Since DP_COL_2 contains variable-size array
C elements, we call EKNELT to determine how many
C elements to fetch.
C
SELIDX = 2
CALL EKNELT ( SELIDX, ROW, NELT )
ELTIDX = 1
ISNULL = .FALSE.
DO WHILE ( ( ELTIDX .LE. NELT )
. .AND. ( .NOT. ISNULL ) )
CALL EKGD ( SELIDX, ROW, ELTIDX,
. DVALS(ELTIDX), ISNULL, FOUND )
ELTIDX = ELTIDX + 1
C
C If the column entry is null, we'll be kicked
C out of this loop after the first iteration.
C
END DO
IF ( ISNULL ) THEN
WRITE(*,*) ' COLUMN = DP_COL_2: <Null>'
ELSE
WRITE(*,'(A,4F6.1)') ' COLUMN = DP_COL_2:',
. ( DVALS(I), I = 1, NELT )
END IF
C
C Fetch values from column DP_COL_3 in the current
C row. We need not call EKNELT since we know how
C many elements are in each column entry.
C
SELIDX = 3
ELTIDX = 1
ISNULL = .FALSE.
DO WHILE ( ( ELTIDX .LE. COL3SZ )
. .AND. ( .NOT. ISNULL ) )
CALL EKGD ( SELIDX, ROW, ELTIDX,
. DVALS(ELTIDX), ISNULL, FOUND )
ELTIDX = ELTIDX + 1
END DO
IF ( ISNULL ) THEN
WRITE(*,*) ' COLUMN = DP_COL_3: <Null>'
ELSE
WRITE(*,'(A,3F6.1)') ' COLUMN = DP_COL_3:',
. ( DVALS(I), I = 1, COL3SZ )
END IF
END DO
C
C We either parsed the SELECT clause or had an error.
C
END IF
END
When this program was executed on a Mac/Intel/gfortran/64-bit
platform, the output was:
ROW = 1
COLUMN = DP_COL_1: 100.00000000000000
COLUMN = DP_COL_2: 201.0
COLUMN = DP_COL_3: 101.0 201.0 301.0
ROW = 2
COLUMN = DP_COL_1: 200.00000000000000
COLUMN = DP_COL_2: 401.0 402.0
COLUMN = DP_COL_3: 102.0 202.0 302.0
ROW = 3
COLUMN = DP_COL_1: 300.00000000000000
COLUMN = DP_COL_2: 601.0 602.0 603.0
COLUMN = DP_COL_3: 103.0 203.0 303.0
ROW = 4
COLUMN = DP_COL_1: 400.00000000000000
COLUMN = DP_COL_2: 801.0 802.0 803.0 804.0
COLUMN = DP_COL_3: 104.0 204.0 304.0
Note that after run completion, a new EK file exists in the
output directory.
4) See $Examples in EKQMGR.
In this example, the names and data types of the columns from
which to fetch data are not known in advance.
Restrictions
None.
Literature_References
None.
Author_and_Institution
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
Version
SPICELIB Version 2.1.0, 06-JUL-2021 (JDR)
Added IMPLICIT NONE statement.
Edited the header to comply with NAIF standard.
Added complete code examples from existing fragments.
SPICELIB Version 2.0.0, 16-NOV-2001 (NJB)
Bug fix: When an already loaded kernel is opened with EKOPR,
it now has its link count reset to 1 via a call to EKCLS.
SPICELIB Version 1.1.0, 07-JUL-1996 (NJB)
Redundant CHKIN call removed from SELIDX error check.
Misspelling of "issued" was fixed. Previous version line
was changed from "Beta" to "SPICELIB."
SPICELIB Version 1.0.0, 23-OCT-1995 (NJB)
|
Fri Dec 31 18:36:18 2021