1 /*
2 
3 -Procedure ekrcei_c ( EK, read column entry element, integer )
4 
5 -Abstract
6 
7    Read data from an integer column in a specified EK record.
8 
9 -Disclaimer
10 
11    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
12    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
13    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
14    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
15    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
16    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
17    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
18    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
19    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
20    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
21 
22    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
23    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
24    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
25    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
26    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
27    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
28 
29    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
30    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
31    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
32    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
33 
34 -Required_Reading
35 
36    EK
37 
38 -Keywords
39 
40    EK
41    FILES
42    UTILITY
43 
44 */
45 
46    #include "SpiceUsr.h"
47    #include "SpiceZfc.h"
48    #include "SpiceZmc.h"
49 
ekrcei_c(SpiceInt handle,SpiceInt segno,SpiceInt recno,ConstSpiceChar * column,SpiceInt * nvals,SpiceInt * ivals,SpiceBoolean * isnull)50    void ekrcei_c ( SpiceInt           handle,
51                    SpiceInt           segno,
52                    SpiceInt           recno,
53                    ConstSpiceChar   * column,
54                    SpiceInt         * nvals,
55                    SpiceInt         * ivals,
56                    SpiceBoolean     * isnull )
57 /*
58 
59 -Brief_I/O
60 
61    Variable  I/O  Description
62    --------  ---  --------------------------------------------------
63    handle     I   Handle attached to EK file.
64    segno      I   Index of segment containing record.
65    recno      I   Record from which data is to be read.
66    column     I   Column name.
67    nvals      O   Number of values in column entry.
68    ivals      O   Integer values in column entry.
69    isnull     O   Flag indicating whether column entry is null.
70 
71 -Detailed_Input
72 
73    handle         is an EK file handle.  The file may be open for
74                   read or write access.
75 
76    segno          is the index of the segment from which data is to
77                   be read.  The first segment in the file has index 0.
78 
79    recno          is the index of the record from which data is to be
80                   read.  This record number is relative to the start
81                   of the segment indicated by segno; the first
82                   record in the segment has index 0.
83 
84    column         is the name of the column from which data is to be
85                   read.
86 
87 
88 -Detailed_Output
89 
90    nvals,
91    ivals          are, respectively, the number of values found in
92                   the specified column entry and the set of values
93                   themselves.
94 
95                   For columns having fixed-size entries, when a
96                   a column entry is null, nvals is still set to the
97                   column entry size.  For columns having variable-
98                   size entries, nvals is set to 1 for null entries.
99 
100    isnull         is a logical flag indicating whether the returned
101                   column entry is null.
102 
103 -Parameters
104 
105    None.
106 
107 -Exceptions
108 
109    1)  If handle is invalid, the error will be diagnosed by routines
110        called by this routine.
111 
112    2)  If segno is out of range, the error will diagnosed by routines
113        called by this routine.
114 
115    3)  If recno is out of range, the error will diagnosed by routines
116        called by this routine.
117 
118    4)  If column is not the name of a declared column, the error
119        will be diagnosed by routines called by this routine.
120 
121    5)  If column specifies a column of whose data type is not
122        integer, the error SPICE(WRONGDATATYPE) will be
123        signaled.
124 
125    6)  If column specifies a column of whose class is not
126        an integer class known to this routine, the error
127        SPICE(NOCLASS) will be signaled.
128 
129    7)  If an attempt is made to read an uninitialized column entry,
130        the error will be diagnosed by routines called by this
131        routine.  A null entry is considered to be initialized, but
132        entries do not contain null values by default.
133 
134    8)  If an I/O error occurs while reading the indicated file,
135        the error will be diagnosed by routines called by this
136        routine.
137 
138    9)  If the input column name string pointer is null, the error
139        SPICE(NULLPOINTER) will be signaled.
140 
141    10) If the input column name string has length zero, the error
142        SPICE(EMPTYSTRING) will be signaled.
143 
144 -Files
145 
146    See the EK Required Reading for a discussion of the EK file
147    format.
148 
149 -Particulars
150 
151    This routine is a utility that allows an EK file to be read
152    directly without using the high-level query interface.
153 
154 -Examples
155 
156    1)  Read the value in the third record of the column ICOL in
157        the fifth segment of an EK file designated by handle.
158 
159           #include "SpiceUsr.h"
160              .
161              .
162              .
163           ekrcei_c ( handle, 4, 2, "ICOL", &n, &ival, &isnull );
164 
165 -Restrictions
166 
167    1) EK files open for write access are not necessarily readable.
168       In particular, a column entry can be read only if it has been
169       initialized. The caller is responsible for determining
170       when it is safe to read from files open for write access.
171 
172 -Literature_References
173 
174    None.
175 
176 -Author_and_Institution
177 
178    N.J. Bachman   (JPL)
179 
180 -Version
181 
182    -CSPICE Version 1.0.0, 04-JUL-2000 (NJB)
183 
184 -Index_Entries
185 
186    read integer data from EK column
187 
188 -&
189 */
190 
191 { /* Begin ekrcei_c */
192 
193    /*
194    Local variables
195    */
196    logical                 null;
197 
198 
199    /*
200    Participate in error tracing.
201    */
202    chkin_c ( "ekrcei_c" );
203 
204    /*
205    Map the segment and record numbers to their Fortran-style
206    values.  Pass a flag of type logical to ekrcei_.
207    */
208 
209    segno++;
210    recno++;
211 
212    ekrcei_  (  ( integer * ) &handle,
213                ( integer * ) &segno,
214                ( integer * ) &recno,
215                ( char    * ) column,
216                ( integer * ) nvals,
217                ( integer * ) ivals,
218                ( logical * ) &null,
219                ( ftnlen    ) strlen(column) );
220 
221    /*
222    Set the output null flag.
223    */
224 
225    *isnull = null;
226 
227    chkout_c ( "ekrcei_c" );
228 
229 } /* End ekrcei_c */
230