| ekgi |
|
Table of contents
Procedure
EKGI ( EK, get event data, integer )
ENTRY EKGI ( SELIDX, ROW, ELMENT, IDATA, NULL, FOUND )
Abstract
Return an element of an entry in a column of integer
type in a specified row.
Required_Reading
EK
Keywords
ASSIGNMENT
EK
Declarations
INTEGER SELIDX
INTEGER ROW
INTEGER ELMENT
INTEGER IDATA
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.
IDATA O Integer 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
IDATA is the requested element of the specified column
entry. If the entry is null, IDATA 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 integer 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 integer 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 IMAGE_NUMBER values (integer
numbers) 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 EKGI_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
INTEGER ELTIDX
INTEGER IDATA
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 'IMAGE_NUMBER' 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 'IMAGE_NUMBER' from table
C 'VIKING_SEDR_DATA' sorted by 'IMAGE_NUMBER'.
C
QUERY = 'Select IMAGE_NUMBER 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 EKGI ( SELIDX, ROWNO, ELTIDX,
. IDATA, ISNULL, FOUND )
IF ( ISNULL ) THEN
WRITE (*,'(A,I3,A)') 'Row ', ROWNO,
. ': Integer data: <Null>'
ELSE
WRITE (*,'(A,I3,A,I10)') 'Row ', ROWNO,
. ': Integer data: ', IDATA
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: Integer data: 25837050
Row 2: Integer data: 25837051
Row 3: Integer data: 25840344
Row 4: Integer data: 25840345
Row 5: Integer data: 25843638
Row 6: Integer data: 25843639
Row 7: Integer data: 25846934
Row 8: Integer data: 25846935
Row 9: Integer data: 25848026
Row 10: Integer data: 25848030
Row 11: Integer data: 25848032
Row 12: Integer data: 25851874
Row 13: Integer data: 25851878
Row 14: Integer data: 25851880
Row 15: Integer data: 25853516
Row 16: Integer data: 25853520
Row 17: Integer data: 25853522
Row 18: Integer data: 25855162
Row 19: Integer data: 25855166
Row 20: Integer data: 25855168
Row 21: Integer data: 25856810
Row 22: Integer data: 25856814
Row 23: Integer data: 25856816
Row 24: Integer data: 25858458
Row 25: Integer data: 25858462
Row 26: Integer data: 25858464
2) This example demonstrates how to fetch integer 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
----------- --------- ----
INT_COL_1 INT 1
INT_COL_2 INT VARIABLE
INT_COL_3 INT 3
Issue the following query
QUERY = 'SELECT INT_COL_1, INT_COL2, INT_COL3 FROM TAB'
to fetch and dump column values from the rows that satisfy the
query.
Example code begins here.
PROGRAM EKGI_EX2
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 = 'ekgi_ex2.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
INTEGER COL1
INTEGER COL2 ( MXC2SZ )
INTEGER COL3 ( COL3SZ )
INTEGER ELTIDX
INTEGER HANDLE
INTEGER I
INTEGER IVALS ( MXC2SZ )
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) = 'INT_COL_1'
CDECLS(1) = 'DATATYPE = INTEGER, INDEXED = TRUE'
CNAMES(2) = 'INT_COL_2'
CDECLS(2) = 'DATATYPE = INTEGER, SIZE = VARIABLE'
CNAMES(3) = 'INT_COL_3'
CDECLS(3) = 'DATATYPE = INTEGER, 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 INT_COL_1
C
COL1 = I * 100
CALL EKACEI ( HANDLE, SEGNO, RECNO,
. CNAMES(1), 1, COL1, .FALSE. )
C
C Add I items to INT_COL_2
C
DO J = 1, I
COL2(J) = J + I*200
END DO
CALL EKACEI ( HANDLE, SEGNO, RECNO,
. CNAMES(2), I, COL2, .FALSE. )
C
C Add 3 items to INT_COL_3
C
DO J = 1, 3
COL3(J) = I + J*100.D0
END DO
CALL EKACEI ( 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 INT_COL_1, INT_COL_2, INT_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 INT_COL_1. Since
C INT_COL_1 was the first column selected, the
C selection index SELIDX is set to 1.
C
SELIDX = 1
ELTIDX = 1
CALL EKGI ( SELIDX, ROW, ELTIDX,
. IVALS(1), ISNULL, FOUND )
IF ( ISNULL ) THEN
WRITE(*,*) ' COLUMN = INT_COL_1: <Null>'
ELSE
WRITE(*,'(A,I6)') ' COLUMN = INT_COL_1:',
. IVALS(1)
END IF
C
C Fetch values from column INT_COL_2 in the current
C row. Since INT_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 EKGI ( SELIDX, ROW, ELTIDX,
. IVALS(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 = INT_COL_2: <Null>'
ELSE
WRITE(*,'(A,4I6)') ' COLUMN = INT_COL_2:',
. ( IVALS(I), I = 1, NELT )
END IF
C
C Fetch values from column INT_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 EKGI ( SELIDX, ROW, ELTIDX,
. IVALS(ELTIDX), ISNULL, FOUND )
ELTIDX = ELTIDX + 1
END DO
IF ( ISNULL ) THEN
WRITE(*,*) ' COLUMN = INT_COL_3: <Null>'
ELSE
WRITE(*,'(A,3I6)') ' COLUMN = INT_COL_3:',
. ( IVALS(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 = INT_COL_1: 100
COLUMN = INT_COL_2: 201
COLUMN = INT_COL_3: 101 201 301
ROW = 2
COLUMN = INT_COL_1: 200
COLUMN = INT_COL_2: 401 402
COLUMN = INT_COL_3: 102 202 302
ROW = 3
COLUMN = INT_COL_1: 300
COLUMN = INT_COL_2: 601 602 603
COLUMN = INT_COL_3: 103 203 303
ROW = 4
COLUMN = INT_COL_1: 400
COLUMN = INT_COL_2: 801 802 803 804
COLUMN = INT_COL_3: 104 204 304
Note that after run completion, a new EK file exists in the
output directory.
3) 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)
E.D. Wright (JPL)
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.1, 22-SEP-2004 (EDW)
Edited version 1.1.0 entry to not include
the token used to mark the $Procedure section.
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." Header $Procedure
line was corrected to indicate integer data type.
SPICELIB Version 1.0.0, 23-OCT-1995 (NJB)
|
Fri Dec 31 18:36:18 2021