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