1 /* 2 3 -Procedure erract_c ( Get/Set Default Error Action ) 4 5 -Abstract 6 7 Retrieve or set the default error action. 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 ERROR 37 38 -Keywords 39 40 ERROR 41 42 */ 43 44 #include "SpiceUsr.h" 45 #include "SpiceZmc.h" 46 #include "SpiceZfc.h" 47 #include "SpiceZst.h" 48 erract_c(ConstSpiceChar * op,SpiceInt lenout,SpiceChar * action)49 void erract_c ( ConstSpiceChar * op, 50 SpiceInt lenout, 51 SpiceChar * action ) 52 53 /* 54 55 -Brief_I/O 56 57 VARIABLE I/O DESCRIPTION 58 -------- --- -------------------------------------------------- 59 op I Operation -- "GET" or "SET" 60 lenout I Length of list for output. 61 action I/O Error response action 62 63 -Detailed_Input 64 65 op indicates the operation -- "GET" or "SET". "GET" means, 66 "Set action to the current value of the error response 67 action." "SET" means, "update the error response action to 68 the value indicated by action." 69 70 op may be in mixed case; for example, 71 72 erract_c ( "gEt", lenout, action ); 73 74 will work. 75 76 lenout is the string size of output 'action' when op equals "GET." 77 The size described by lenout should be large enough to 78 hold all characters of any possible output string 79 plus 1 (to accommodate the C null terminator). 80 81 action is an input argument when op is "SET." It takes the 82 values, "ABORT", "IGNORE", "REPORT", "RETURN", and 83 "DEFAULT". 84 85 Briefly, the meanings of the error response 86 choices are as follows: 87 88 1. "ABORT" -- When an error is detected by a 89 CSPICE routine, or when 90 ANY routine signals detection 91 of an error via a call to sigerr_c, the 92 toolkit will output any error messages that 93 it has been enabled to output (see errprt_c 94 and errdev_c also ), and then execute an 95 exit statement. 96 97 2. "REPORT" -- In this mode, the toolkit does 98 NOT abort when errors are detected. 99 When sigerr_c is called to report 100 an error, all error messages that the toolkit 101 is enabled to output will be sent to the 102 designated error output device. Similarly, 103 a call to setmsg_c will result in the long 104 error message being output, if the toolkit 105 is enabled to output it. 106 107 108 3. "RETURN" -- In this mode, the toolkit also 109 does NOT abort when errors are 110 detected. Instead, error messages 111 are output if the toolkit is enabled to do 112 so, and subsequently, ALL TOOLKIT ROUTINES 113 RETURN IMMEDIATELY UPON ENTRY until the 114 error status is reset via a call to RESET. 115 (No, RESET itself doesn't return on entry). 116 Resetting the error status will cause the 117 toolkit routines to resume their normal 118 execution threads. 119 120 121 122 4. "IGNORE" -- The toolkit will not take any 123 action in response to errors; 124 calls to sigerr_c will have no 125 effect. 126 127 128 5. "DEFAULT" -- This mode is the same as "ABORT", 129 except that an additional error 130 message is output. The additional 131 message informs the user that the 132 error response action can be 133 modified, and refers to documentation 134 of the error handling feature. 135 136 137 action may be in mixed case; for example, 138 139 erract_c ( "SET", lenout,"igNORe" ); 140 141 will work. 142 143 -Detailed_Output 144 145 action is an output argument returning the current error 146 response action when 'op' equals "GET." Possible values 147 are: "ABORT", "REPORT", "RETURN", and "IGNORE". 148 See "Detailed Input" for descriptions of these values. 149 150 -Parameters 151 152 None. 153 154 -Exceptions 155 156 1) If the input argument op does not indicate a valid operation, 157 the error SPICE(INVALIDOPERATION) will be signaled. 158 159 2) When op is "SET", if the input argument action does not indicate a 160 valid error handling action, the error SPICE(INVALIDACTION) will 161 be signaled. 162 163 3) The error SPICE(EMPTYSTRING) is signaled if either input string 164 does not contain at least one character, since an input string 165 cannot be converted to a Fortran-style string in this case. This 166 check always applies to op; it applies to action only when 167 action is an input, that is, when op is "SET." 168 169 4) The error SPICE(NULLPOINTER) is signaled if either string pointer 170 argument is null. 171 172 5) The caller must pass a value indicating the length of the output 173 string, when action is an output. If this value is not at least 174 2, the error SPICE(STRINGTOOSHORT) is signaled. 175 176 -Files 177 178 None. 179 180 -Particulars 181 182 As indicated in the "detailed input" section above, the choices for 183 the Toolkit's error handling action are designated by the strings 184 "ABORT", "REPORT", "RETURN", "IGNORE", and "DEFAULT". These 185 choices control the way the toolkit behaves when an error is 186 detected. The toolkit thinks an error has been detected when 187 sigerr_c is called. 188 189 1. "ABORT" In this mode, the toolkit sends error messages 190 to the error output device and then stops. 191 This is the default mode. It is probably 192 the one to choose for running non-interactive programs. 193 You may also wish to use this for programs which 194 have many bugs, or in other cases where continued 195 operation following detection of an error isn't useful. 196 197 2. "REPORT" In this mode, the toolkit sends error messages 198 to the error output device and keeps going. This mode 199 may be useful if you are debugging a large program, 200 since you can get more information from a single test run. 201 You will probably want to use errdev_c to indicate a file 202 where your error messages should be sent. 203 204 3. "RETURN" In this mode, the toolkit also sends error messages 205 to the error output device and "keeps going". But 206 instead of following their normal execution threads, 207 the toolkit routines will simply return immediately upon 208 entry, once an error has been detected. 209 The availability of this feature makes it safe to call 210 multiple toolkit routines without checking the error 211 status after each one returns; if one routine detects 212 an error, subsequent calls to toolkit routines will have 213 no effect; therefore, no crash will occur. The error 214 messages set by the routine which detected the error 215 will remain available for retrieval by getmsg_. 216 217 4. "IGNORE" This mode can be dangerous! It is best 218 used when running a program whose behavior you 219 understand well, in cases where you wish to suppress 220 annoying messages. BUT, if an unexpected error 221 occurs, you won't hear about it from anyone, except 222 possibly your run-time system. 223 224 5. "DEFAULT" As the name suggests, this is the default 225 error handling mode. The error handling mechanism 226 starts out in this mode when a program using the 227 toolkit is run, and the mode remains "DEFAULT" until 228 it is changed via a call to this routine. 229 This mode is the same as "ABORT", 230 except that an additional error message is output. 231 The additional message informs the user that the 232 error response action can be modified, and refers 233 to documentation of the error handling feature. 234 235 236 NOTE: 237 238 By default, error messages are printed to the screen 239 when errors are detected. You may want to send them 240 to a different output device, or choose a subset to 241 output. Use the routines errdev_c and errprt_c to choose 242 the output device and select the messages to output, 243 respectively. 244 245 You can also suppress the automatic output of messages 246 and retrieve them directly in your own program. getmsg_ 247 can be used for this. To make sure that the messages 248 retrieved correspond to the FIRST error that occurred, 249 use "RETURN" mode. In "REPORT" mode, new messages 250 overwrite old ones in the CSPICE message storage 251 area, so getmsg_ will get the messages from the LATEST 252 error that occurred. 253 254 255 -Examples 256 257 258 1. Setting up "ABORT" mode: 259 260 /. 261 We wish to have our program abort if an error 262 is detected. But instead of having the error 263 messages printed on the screen, we want them 264 to be written to the file, ERROR_LOG.TXT 265 266 We want to see all of the messages, so we 267 call errprt_c, using the "ALL" option. 268 269 Finally, we call erract_c to set the action to "ABORT": 270 ./ 271 272 errdev_c ( "SET", lenout, "ERROR_LOG.DAT" ); 273 274 errprt_c ( "SET", lenout, "ALL" ); 275 276 erract_c ( "SET", lenout, "ABORT" ); 277 278 279 280 2. Setting up "REPORT" mode: 281 282 errdev_c ( "SET", lenout, "ERROR_LOG.DAT" ); 283 284 errprt_c ( "SET", lenout, "ALL" ); 285 286 erract_c ( "SET", lenout, "REPORT" ); 287 288 289 3. Setting up "RETURN" mode: This is the same 290 as example #2, except that the erract_c call becomes: 291 292 erract_c ( "SET", lenout, "RETURN" ); 293 294 295 296 4. Setting up "IGNORE" mode: 297 298 /. 299 In this case, we aren't going to have 300 ANY error messages (unless the call 301 to erract_c itself fails), so we don't 302 really need to call errprt_c and errdev_c. 303 (If the call to erract_c DOES fail, which 304 it can do only if we misspell "IGNORE," 305 the resulting error messages will go to 306 the screen). 307 ./ 308 309 erract_c ( "SET", lenout, "IGNORE" ); 310 311 312 -Restrictions 313 314 None. 315 316 -Literature_References 317 318 None. 319 320 -Author_and_Institution 321 322 N.J. Bachman (JPL) 323 K.R. Gehringer (JPL) 324 325 -Version 326 327 -CSPICE Version 1.3.1, 25-SEP-2003 (EDW) 328 329 Corrected confusing description of 'lenout' argument. 330 331 -CSPICE Version 1.3.0, 24-JUN-2003 (NJB) 332 333 Bug fix: case of invalid operation keyword is now 334 diagnosed, as per the Exceptions section of the header. 335 336 -CSPICE Version 1.2.0, 09-FEB-1998 (NJB) 337 338 Re-implemented routine without dynamically allocated, temporary 339 strings. Made various header fixes. 340 341 -CSPICE Version 1.0.1, 30-OCT-1997 (EDW) 342 343 Corrected errors in examples in which the call sequence 344 was incorrect. 345 346 -CSPICE Version 1.0.0, 25-OCT-1997 (EDW) 347 348 -Index_Entries 349 350 get/set default error action 351 352 -& 353 */ 354 355 { /* Begin erract_c */ 356 357 358 /* 359 Participate in error tracing. 360 */ 361 if ( return_c() ) 362 { 363 return; 364 } 365 366 chkin_c ( "erract_c" ); 367 368 369 /* 370 Check the input string op to make sure the pointer is non-null 371 and the string length is non-zero. 372 */ 373 CHKFSTR ( CHK_STANDARD, "erract_c", op ); 374 375 376 if( eqstr_c ( op, "SET") ) 377 { 378 379 /* 380 Operation is SET. "action" will be an input string. Check 381 action as well. 382 */ 383 CHKFSTR ( CHK_STANDARD, "erract_c", action ); 384 385 /* 386 Call the f2c'd Fortran routine. 387 */ 388 erract_ ( ( char * ) op, 389 ( char * ) action, 390 ( ftnlen ) strlen(op), 391 ( ftnlen ) strlen(action) ); 392 } 393 394 else if ( eqstr_c (op, "GET" ) ) 395 { 396 397 /* 398 Operation is GET. "action" will be an output string. Make sure 399 the output string has at least enough room for one output 400 character and a null terminator. Also check for a null pointer. 401 */ 402 CHKOSTR ( CHK_STANDARD, "erract_c", action, lenout ); 403 404 405 /* 406 Call the f2c'd Fortran routine. 407 */ 408 erract_ ( ( char * ) op, 409 ( char * ) action, 410 ( ftnlen ) strlen(op), 411 ( ftnlen ) lenout-1 ); 412 413 414 F2C_ConvertStr( lenout, action ); 415 } 416 417 else 418 { 419 setmsg_c ( "Input argument op had value: # " 420 "Valid choices are GET or SET." ); 421 errch_c ( "#", op ); 422 sigerr_c ( "SPICE(INVALIDOPERATION)" ); 423 chkout_c ( "erract_c" ); 424 return; 425 } 426 427 428 chkout_c ( "erract_c" ); 429 430 } /* End erract_c */ 431 432 433