1 /* 2 3 -Procedure badkpv_c ( Bad Kernel Pool Variable ) 4 5 -Abstract 6 7 Determine if a kernel pool variable is present and if so 8 that it has the correct size and type. 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 None. 38 39 -Keywords 40 41 ERROR 42 43 */ 44 45 #include "SpiceUsr.h" 46 #include "SpiceZfc.h" 47 #include "SpiceZmc.h" 48 49 badkpv_c(ConstSpiceChar * caller,ConstSpiceChar * name,ConstSpiceChar * comp,SpiceInt size,SpiceInt divby,SpiceChar type)50 SpiceBoolean badkpv_c ( ConstSpiceChar *caller, 51 ConstSpiceChar *name, 52 ConstSpiceChar *comp, 53 SpiceInt size, 54 SpiceInt divby, 55 SpiceChar type ) 56 57 /* 58 59 -Brief_I/O 60 61 VARIABLE I/O DESCRIPTION 62 -------- --- -------------------------------------------------- 63 caller I Name of the routine calling this routine. 64 name I Name of a kernel pool variable 65 comp I Comparison operator. 66 size I Expected size of the kernel pool variable 67 divby I A divisor of the size of the kernel pool variable. 68 type I Expected type of the kernel pool variable 69 70 The function returns SPICEFALSE if the kernel pool variable is OK. 71 72 -Detailed_Input 73 74 caller is the name of the routine calling this routine 75 to check correctness of kernel pool variables. 76 77 name is the name of a kernel pool variable that the 78 calling program expects to be present in the 79 kernel pool. 80 81 comp is the comparison operator to use when comparing 82 the number of components of the kernel pool variable 83 specified by name with the integer size. If dim is 84 is the actual size of the kernel pool variable then 85 badkpv_c will check that the sentence 86 87 dim comp size 88 89 is a true statement. If it is not a true statement 90 an error will be signaled. 91 92 Allowed values for comp and their meanings are: 93 94 "=" dim == size 95 "<" dim < size 96 ">" dim > size 97 "=>" dim >= size 98 "<=" dim <= size 99 100 101 size is an integer to compare with the actual 102 number of components of the kernel pool variable 103 specified by name. 104 105 divby is an integer that is one of the factors of the 106 actual dimension of the specified kernel pool variable. 107 In other words, it is expected that divby evenly 108 divides the actual dimension of name. In those 109 cases in which the factors of the dimension of name 110 are not important, set divby to 1 in the calling 111 program. 112 113 type is the expected type of the kernel pool variable. 114 Recognized values are 115 116 'C' for character type 117 'N' for numeric type (integer and double precision) 118 119 The case of type is insignificant. If the value 120 of TYPE is not one of the 2 values given above 121 no check for the type of the variable will be 122 performed. 123 124 125 -Detailed_Output 126 127 The function returns the value SPICEFALSE if the kernel pool variable 128 has the expected properties. Otherwise the routine signals 129 an error and returns the value SPICETRUE. 130 131 -Parameters 132 133 None. 134 135 -Files 136 137 None. 138 139 -Exceptions 140 141 1) If the kernel pool variable specified by name is not 142 present in the kernel pool, the error 143 SPICE(VARIABLENOTFOUND) will be signaled and the 144 routine will return the value SPICETRUE. 145 146 2) If the comparison operator specified by comp is unrecognized 147 the error SPICE(UNKNOWNCOMPARE) will be signaled and the 148 routine will return the value SPICETRUE. 149 150 3) If the comparison of the actual size of the kernel pool 151 variable with size is not satisfied, the error 152 SPICE(BADVARIABLESIZE) will be signaled and the 153 routine will return the value SPICETRUE. 154 155 4) If the variable does not have the expected type, the error 156 SPICE(BADVARIABLETYPE) will be signaled and the routine 157 will return the value SPICETRUE. 158 159 5) If any input string pointers are null, the error 160 SPICE(NULLPOINTER) will be signaled. 161 162 6) If any input strings have length zero, the error 163 SPICE(EMPTYSTRING) will be signaled. 164 165 -Particulars 166 167 This routine takes care of routine checking that often needs 168 to be done by programs and routines that rely upon kernel 169 pool variables being present and having the correct attributes. 170 171 It checks for the presence of the kernel pool variable and 172 examines the type and dimension of the variable to make sure 173 they conform to the requirements of the calling routine. 174 175 -Examples 176 177 Suppose that you need to fetch a number of variables 178 from the kernel pool and want to check that the requested 179 items are in fact available prior to performing further 180 computations. The following shows how you might use 181 this routine to handle the details of checking of 182 the various items. 183 184 caller == "MYROUTINE" 185 186 We need some data for body 399 and we expect there to 187 be an even number of items available. Moreover we 188 expect these items to be numeric. 189 190 name == "BODY_399_DATA" 191 comp == ">" 192 size == 1 193 divby == 2 194 type == 'N' 195 196 In addition we need the units associated with this data. 197 We expect the units to be character and that the number 198 of components is 1. 199 200 name == "BODY_399_DATAUNIT"; 201 comp == "=" 202 size == 1 203 divby == 1 204 type == 'C' 205 206 207 if ( badkpv_c( caller, "BODY_399_DATA", ">", 1, 2, 'N' ) 208 || badkpv_c( caller, "BODY_399_DATAUNITS", "=", 1, 1, 'C' ) ) 209 { 210 chkout_c ( "MYROUTINE" ); 211 return; 212 } 213 214 215 -Restrictions 216 217 None. 218 219 -Author_and_Institution 220 221 W.L. Taber (JPL) 222 N.J. Bachman (JPL) 223 224 -Literature_References 225 226 None. 227 228 -Version 229 230 -CSPICE Version 1.0.0, 07-JUL-2000 (WLT) (NJB) 231 232 -Index_Entries 233 234 Check the properties of a kernel pool variable 235 236 -& 237 */ 238 239 { /* Begin badkpv_c */ 240 241 242 /* 243 Local variables 244 */ 245 logical isbad; 246 247 248 /* 249 Participate in error tracing. 250 */ 251 chkin_c ( "badkpv_c" ); 252 253 254 /* 255 Check the input strings to make sure the pointers are non-null 256 and the string lengths are non-zero. 257 */ 258 CHKFSTR_VAL ( CHK_STANDARD, "badkpv_c", caller, SPICETRUE ); 259 CHKFSTR_VAL ( CHK_STANDARD, "badkpv_c", name, SPICETRUE ); 260 CHKFSTR_VAL ( CHK_STANDARD, "badkpv_c", comp, SPICETRUE ); 261 262 /* 263 Let the f2c'd routine do all the work. 264 */ 265 isbad = badkpv_ ( (char *) caller, 266 (char *) name, 267 (char *) comp, 268 (integer *) &size, 269 (integer *) &divby, 270 (char *) &type, 271 (ftnlen ) strlen(caller), 272 (ftnlen ) strlen(name), 273 (ftnlen ) strlen(comp), 274 (ftnlen ) 1 ); 275 276 277 chkout_c ( "badkpv_c" ); 278 279 return ( (SpiceBoolean) isbad ); 280 281 } /* End badkpv_c */ 282