1 /*
2 
3 -Procedure ekrced_c ( EK, read column entry element, d.p. )
4 
5 -Abstract
6 
7    Read data from a double precision column in a specified EK
8    record.
9 
10 -Disclaimer
11 
12    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
13    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
14    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
15    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
16    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
17    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
18    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
19    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
20    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
21    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
22 
23    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
24    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
25    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
26    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
27    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
28    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
29 
30    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
31    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
32    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
33    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
34 
35 -Required_Reading
36 
37    EK
38 
39 -Keywords
40 
41    EK
42    FILES
43    UTILITY
44 
45 */
46 
47    #include "SpiceUsr.h"
48    #include "SpiceZfc.h"
49    #include "SpiceZmc.h"
50 
ekrced_c(SpiceInt handle,SpiceInt segno,SpiceInt recno,ConstSpiceChar * column,SpiceInt * nvals,SpiceDouble * dvals,SpiceBoolean * isnull)51    void ekrced_c ( SpiceInt           handle,
52                    SpiceInt           segno,
53                    SpiceInt           recno,
54                    ConstSpiceChar   * column,
55                    SpiceInt         * nvals,
56                    SpiceDouble      * dvals,
57                    SpiceBoolean     * isnull )
58 /*
59 
60 -Brief_I/O
61 
62    Variable  I/O  Description
63    --------  ---  --------------------------------------------------
64    handle     I   Handle attached to EK file.
65    segno      I   Index of segment containing record.
66    recno      I   Record from which data is to be read.
67    column     I   Column name.
68    nvals      O   Number of values in column entry.
69    dvals      O   D.p. values in column entry.
70    isnull     O   Flag indicating whether column entry is null.
71 
72 -Detailed_Input
73 
74    handle         is an EK file handle.  The file may be open for
75                   read or write access.
76 
77    segno          is the index of the segment from which data is to
78                   be read.  The first segment in the file has index 0.
79 
80    recno          is the index of the record from which data is to be
81                   read.  This record number is relative to the start
82                   of the segment indicated by segno; the first
83                   record in the segment has index 0.
84 
85    column         is the name of the column from which data is to be
86                   read.
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        double precision, the error SPICE(WRONGDATATYPE) will be
123        signaled.
124 
125    6)  If column specifies a column of whose class is not a double precision
126        class known to this routine, the error SPICE(NOCLASS) will be signaled.
127 
128    7)  If an attempt is made to read an uninitialized column entry,
129        the error will be diagnosed by routines called by this
130        routine.  A null entry is considered to be initialized, but
131        entries do not contain null values by default.
132 
133    8)  If an I/O error occurs while reading the indicated file,
134        the error will be diagnosed by routines called by this
135        routine.
136 
137    9)  If the input column name string pointer is null, the error
138        SPICE(NULLPOINTER) will be signaled.
139 
140    10) If the input column name string has length zero, the error
141        SPICE(EMPTYSTRING) will be signaled.
142 
143 -Files
144 
145    See the EK Required Reading for a discussion of the EK file
146    format.
147 
148 -Particulars
149 
150    This routine is a utility that allows an EK file to be read
151    directly without using the high-level query interface.
152 
153 -Examples
154 
155    1)  Read the value in the third record of the column DCOL in
156        the fifth segment of an EK file designated by HANDLE.
157 
158 
159           #include "SpiceUsr.h"
160              .
161              .
162              .
163           ekrced_c ( handle, 4, 2, "DCOL", &n, &dval, &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 double precision data from EK column
187 
188 -&
189 */
190 
191 { /* Begin ekrced_c */
192 
193    /*
194    Local variables
195    */
196    logical                 null;
197 
198    /*
199    Participate in error tracing.
200    */
201    chkin_c ( "ekrced_c" );
202 
203 
204    /*
205    Check the column name to make sure the pointer is non-null
206    and the string length is non-zero.
207    */
208    CHKFSTR ( CHK_STANDARD, "ekrced_c", column );
209 
210 
211    /*
212    Map the segment and record numbers to their Fortran-style
213    values.  Pass a flag of type logical to ekrced_.
214    */
215 
216    segno++;
217    recno++;
218 
219    ekrced_ ( ( integer    * ) &handle,
220              ( integer    * ) &segno,
221              ( integer    * ) &recno,
222              ( char       * ) column,
223              ( integer    * ) nvals,
224              ( doublereal * ) dvals,
225              ( logical    * ) &null,
226              ( ftnlen       ) strlen(column) );
227 
228    /*
229    Set the output null flag.
230    */
231 
232    *isnull = null;
233 
234 
235    chkout_c ( "ekrced_c" );
236 
237 } /* End ekrced_c */
238