1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
|
/*
* Name:
* error.c
* Purpose:
* Implement error handling functions.
* Description:
* This file implements the Error module which provides functions
* for handling error conditions in the AST library. For a
* description of the module and its interface, see the .h file of
* the same name.
*
* Since its initial release, AST has used a global status variable
* rather than adding an explicit status parameter to the argument
* list of each AST function. This caused problems for the thread-safe
* version of AST since each thread needs its own status value. Whilst
* it would have been possible for each function to access a global
* status value via the pthreads "thread speific data key" mechanism,
* the huge number of status checks performed within AST caused this
* option to be slow. Instead AST has been modified so that every
* function has an explicit status pointer parameter. This though
* causes problems in that we cannot change the public interface to
* AST because doing so would break large amounts of external software.
* To get round this, the macros that define the public interface to
* AST have been modified so that they provide a status pointer
* automatically to the function that is being invoked. This is how
* the system works...
*
* All AST functions have an integer inherited status pointer parameter
* called "status". This parameter is "hidden" in AST functions that
* are invoked via macros (typically public and protected functions).
* This means that whilst "int *status" appears explicitly at the end
* of the function argument list (in both prototype and definition), it
* is not included in the prologue documentation, and is not included
* explicitly in the argument list when invoking the function. Instead,
* the macro that is used to invoke the function adds in the required
* status parameter to the function invocation.
*
* Macros which are invoked within AST (the protected interface) expand
* to include ", status" at the end of the function parameter list. For
* backward compatability with previous versions of AST, macros which
* are invoked from outside AST (the public interface) expand to include
* ", astGetStatusPtr" at the end of the function parameter list. The
* astGetStatusPtr function returns a pointer to the interbal AST
* status variable or to the external variable specified via astWatch.
*
* Parameter lists for functions that have variable argument lists
* (such as astError) cannot be handled in this way, since macros cannot
* have variable numbers of arguments. Instead, separate public and
* protected implementations of such functions are provided within AST.
* Protected implementations include an explicit, documented status
* pointer parameter that must be given explicitly when invoking the
* function. Public implementations do not have a status pointer
* parameter. Instead they obtain the status pointer internally using
* astGetStatusPtr.
*
* Private functions are called directly rather than via macros, and so
* they have a documented status pointer parameter that should be
* included explicitly in the parameter list when invoking the
* function.
* Copyright:
* Copyright (C) 1997-2006 Council for the Central Laboratory of the
* Research Councils
* Copyright (C) 2008-2009 Science & Technology Facilities Council.
* All Rights Reserved.
* Licence:
* This program is free software: you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation, either
* version 3 of the License, or (at your option) any later
* version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
* License along with this program. If not, see
* <http://www.gnu.org/licenses/>.
* Authors:
* RFWS: R.F. Warren-Smith (Starlink)
* DSB: David S. Berry (Starlink)
* History:
* 2-JAN-1996 (RFWS):
* Original version.
* 8-JAN-1996 (RFWS):
* Tidied up.
* 26-JAN-1996 (RFWS):
* Incorporated changes to prologue style.
* 14-JUN-1996 (RFWS):
* Added astAt.
* 20-JUN-1996 (RFWS):
* Added astSetStatus.
* 15-JUL-1996 (RFWS):
* Sorted out the public interface.
* 16-JUL-1996 (RFWS):
* Added astWatch.
* 18-MAR-1998 (RFWS):
* Added notes about functions being available for writing
* foreign language and graphics interfaces, etc.
* 27-NOV-2002 (DSB):
* Added suppression of error reporting using astReporting.
* 11-MAR-2004 (DSB):
* Add facility to astAt to allow astAt to be called from public
* interface without private interface settings over-riding the
* public interface settings.
* 30-MAR-2005 (DSB):
* Added facility to report deferred messages when reporting is
* switched back on.
* 16-FEB-2006 (DSB):
* Improve efficiency by replacing the astOK_ function with a macro
* which tests the value of status variable. The pointer which points
* to the AST status variable are now global rather than static.
* 19-SEP-2008 (DSB):
* Big changes for the thread-safe version of AST.
* 3-FEB-2009 (DSB):
* Added astBacktrace.
*/
/* Define the astCLASS macro (even although this is not a class
implementation) to obtain access to protected interfaces. */
#define astCLASS
/* Include files. */
/* ============== */
/* Interface definitions. */
/* ---------------------- */
#include "err.h" /* Interface to the err module */
#include "error.h" /* Interface to this module */
#include "globals.h" /* Thread-safe global data access */
/* C header files. */
/* --------------- */
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
/* Configuration results. */
/* ---------------------- */
#if HAVE_CONFIG_H
#include <config.h>
#endif
/* Select the appropriate memory management functions. These will be the
system's malloc, free and realloc unless AST was configured with the
"--with-starmem" option, in which case they will be the starmem
malloc, free and realloc. */
#ifdef HAVE_STAR_MEM_H
# include <star/mem.h>
# define MALLOC starMalloc
# define FREE starFree
# define REALLOC starRealloc
#else
# define MALLOC malloc
# define FREE free
# define REALLOC realloc
#endif
/* Include execinfo.h if the backtrace function is available */
#if HAVE_EXECINFO_H
#include <execinfo.h>
#endif
/* Module Variables. */
/* ================= */
/* Define macros for accessing all items of thread-safe global data
used by this module. */
#ifdef THREAD_SAFE
#define reporting astGLOBAL(Error,Reporting)
#define current_file astGLOBAL(Error,Current_File)
#define current_routine astGLOBAL(Error,Current_Routine)
#define current_line astGLOBAL(Error,Current_Line)
#define foreign_set astGLOBAL(Error,Foreign_Set)
#define message_stack astGLOBAL(Error,Message_Stack)
#define mstack_size astGLOBAL(Error,Mstack_Size)
/* Since the external astPutErr function may not be thread safe, we need
to ensure that it cannot be invoked simultaneously from two different
threads. So we lock a mutex before each call to astPutErr. */
static pthread_mutex_t mutex1 = PTHREAD_MUTEX_INITIALIZER;
#define INVOKE_ASTPUTERR( status, buff ) \
( pthread_mutex_lock( &mutex1 ), \
astPutErr( (status), (buff) ), \
(void) pthread_mutex_unlock( &mutex1 ) )
/* Define the initial values for the global data for this module. */
#define GLOBAL_inits \
globals->Reporting = 1; \
globals->Current_File = NULL; \
globals->Current_Routine = NULL; \
globals->Current_Line = 0; \
globals->Foreign_Set = 0; \
globals->Mstack_Size = 0; \
/* Create the global initialisation function. */
astMAKE_INITGLOBALS(Error)
/* If thread safety is not needed, declare globals at static variables. */
/* -------------------------------------------------------------------- */
#else
/* Status variable. */
static int internal_status = 0; /* Internal error status */
int *starlink_ast_status_ptr = &internal_status; /* Pointer to status variable */
/* Reporting flag: delivery of message is supressed if zero. */
static int reporting = 1;
/* Error context. */
static const char *current_file = NULL; /* Current file name pointer */
static const char *current_routine = NULL; /* Current routine name pointer */
static int current_line = 0; /* Current line number */
static int foreign_set = 0; /* Have foreign values been set? */
/* Un-reported message stack */
static char *message_stack[ AST__ERROR_MSTACK_SIZE ];
static int mstack_size = 0;
/* If thread-safety is not needed, we can invoke the external astPutErr
function directly. */
#define INVOKE_ASTPUTERR( status, buff ) \
astPutErr( (status), (buff) );
#endif
/* Function prototypes. */
/* ==================== */
static void EmptyStack( int, int * );
/* Function implementations. */
/* ========================= */
void astAt_( const char *routine, const char *file, int line, int forn,
int *status) {
/*
*+
* Name:
* astAt
* Purpose:
* Store a routine, file and line number context in case of error.
* Type:
* Protected function.
* Synopsis:
* #include "error.h"
* void astAt( const char *routine, const char *file, int line, int forn)
* Description:
* This function stores a pointer to two strings containing the
* names of a routine and a file, together with an integer line
* number. These values are retained for subsequent use in
* reporting the context of any error that may arise.
* Parameters:
* routine
* Pointer to a null terminated C string containing a routine
* name (which should reside in static memory).
* file
* Pointer to a null terminated C string containing a file name
* (which should reside in static memory).
* line
* The line number in the file.
* for
* Is this call being made from a foreign language interface?
* If so any values supplied will take precedence of the values
* set by the C interface.
* Notes:
* - This function returns without action (i.e. without changing
* the stored values) if the global error status is set. It
* performs no other error checking.
* - Any (or all) of the arguments may be omitted by supplying a
* NULL or zero value (as appropriate) and will then not be included
* in any error report.
* - This function is documented as protected because it should not
* be invoked by external code. However, it is available via the
* external C interface so that it may be used when writing (e.g.)
* foreign language or graphics interfaces.
*-
*/
/* Local Variables: */
astDECLARE_GLOBALS /* Pointer to thread-specific global data */
/* Check the global error status. */
if ( !astOK ) return;
/* If needed, get a pointer to the thread specific global data structure. */
astGET_GLOBALS(NULL);
/* If the values refer to a foreign interface, or if no foreign values
have yet been set, store the supplied values. */
if( forn|| !foreign_set ) {
current_routine = routine;
current_file = file;
current_line = line;
}
/* If the values relate to a foreign interface, set a flag which prevents
local values set later replacing them. */
foreign_set = forn;
}
void astBacktrace_( int *status ) {
/*
c+
* Name:
* astBacktrace
* Purpose:
* Display a backtrace on standard output.
* Type:
* Protected macro.
* Synopsis:
* #include "error.h"
* astBacktrace;
* Description:
* This macro displays a set of messages on standard output that
* give a backtrace of the caller. It can be useful for debugging AST
* code in situations when it is not easy or possible to use a
* debugger (for instance, when debugging JNIAST).
* Notes:
* - Only non-static function names are included in the backtrace.
* - This function requires the GNU C library. When called, it will
* just issue a warning if the GNU 'backtrace' function was not
* available when AST was configured.
c-
*/
#if HAVE_BACKTRACE
#define MAX_ADDR 100
/* Local Variables: */
char **strings; /* Pointer to array of formated strings */
char buf[ 120 ]; /* Output line buffer */
int j; /* String index */
int np; /* Number of used return addresses */
void *buffer[ MAX_ADDR ]; /* Array of return addresses */
/* Get the array of return addresses. */
np = backtrace( buffer, MAX_ADDR );
/* Convert them into strings. */
strings = backtrace_symbols( buffer, np );
/* If succesful, display them and then free the array. Note we skip the
first one since that will refer to this function. */
if( strings ) {
INVOKE_ASTPUTERR( astStatus, " " );
for( j = 1; j < np; j++ ) {
sprintf( buf, "%d: %s", j, strings[j] );
INVOKE_ASTPUTERR( astStatus, buf );
}
free( strings );
INVOKE_ASTPUTERR( astStatus, " " );
/* If not succesful, issue a warning. */
} else {
INVOKE_ASTPUTERR( astStatus, "Cannot convert backtrace addresses into formatted strings" );
}
#else
INVOKE_ASTPUTERR( astStatus, "Backtrace functionality is not available "
"on the current operating system." );
#endif
}
void astClearStatus_( int *status ) {
/*
c++
* Name:
* astClearStatus
* Purpose:
* Clear the AST error status.
* Type:
* Public macro.
* Synopsis:
* #include "error.h"
* void astClearStatus
* Description:
* This macro resets the AST error status to an OK value,
* indicating that an error condition (if any) has been cleared.
* Notes:
* - If the AST error status is set to an error value (after an
* error), most AST functions will not execute and will simply
* return without action. Using astClearStatus will restore normal
* behaviour.
c--
*/
/* Empty the deferred error stack without displaying the messages on the
stack. */
EmptyStack( 0, status );
/* Reset the error status value. */
*status = 0;
}
static void EmptyStack( int display, int *status ) {
/*
* Name:
* EmptyStack
* Purpose:
* Empty the stack of deferred error messages, optionally displaying
* them.
* Type:
* Private function.
* Synopsis:
* #include "error.h"
* void EmptyStack( int display, int *status )
* Description:
* This function removes all messages from the stack of deferred error
* messages. If "display" is non-zero it reports them using astPutErr
* before deleting them.
* Parameters:
* display
* Report messages before deleting them?
* status
* Pointer to the integer holding the inherited status value.
*/
/* Local variables; */
astDECLARE_GLOBALS /* Pointer to thread-specific global data */
int i;
/* If needed, get a pointer to the thread specific global data structure. */
astGET_GLOBALS(NULL);
/* Loop round all messages on the stack. */
for( i = 0; i < mstack_size; i++ ) {
/* Display the message if required. */
if( display ) INVOKE_ASTPUTERR( astStatus, message_stack[ i ] );
/* Free the memory used to hold the message. */
FREE( message_stack[ i ] );
message_stack[ i ] = NULL;
}
/* Reset the stack size to zero. */
mstack_size = 0;
}
void astErrorPublic_( int status_value, const char *fmt, ... ) {
/*
*+
* Name:
* astError
* Purpose:
* Set the AST error status and report an error message.
* Type:
* Protected function.
* Synopsis:
* #include "error.h"
* void astError( int status_value, const char *fmt, ... )
* Description:
* This function sets the AST error status to a specified value and
* reports an associated error message.
* Parameters:
* status_value
* The new error status value to be set.
* fmt
* Pointer to a null-terminated character string containing the
* format specification for the error message, in the same way
* as for a call to the C "printf" family of functions.
* ...
* Additional optional arguments (as used by e.g. "printf")
* which specify values which are to appear in the error
* message.
* Notes:
* This function operates just like "printf", except that:
* - The first argument is an error status.
* - The return value is void.
* - A newline is automatically appended to the error message
* (there is no need to add one).
* - This function is documented as protected because it should not
* be invoked by external code. However, it is available via the
* external C interface so that it may be used when writing (e.g.)
* foreign language or graphics interfaces.
*-
* This is the public implementation of astError. It does not have an
status pointer parameter, but instead obtains the status pointer
explicitly using the astGetStatusPtr function. This is different to
other public functions, which typically have a status pointer parameter
that is supplied via a call to astGetStatusPtr within the associated
interface macro. The benefit of doing it the usual way is that the
public and protected implementations are the same, with the
differences between public and protecte dinterfaces wrapped up in the
associated interface macro. We cannot do this with this function
because of the variale argument list. The prologue for the astError_
function defines the interface for use internally within AST.
*/
/* Local Constants: */
#define BUFF_LEN 1023 /* Max. length of an error message */
/* Local Variables: */
astDECLARE_GLOBALS /* Pointer to thread-specific global data */
char buff[ BUFF_LEN + 1 ]; /* Message buffer */
int *status; /* Pointer to inherited status value */
int imess; /* Index into deferred message stack */
int nc; /* Number of characters written */
va_list args; /* Variable argument list pointer */
/* Initialise the variable argument list pointer. */
va_start( args, fmt );
/* If needed, get a pointer to the thread specific global data structure. */
astGET_GLOBALS(NULL);
/* Get a pointer to the integer holding the inherited status value. */
status = astGetStatusPtr;
/* If this is the first report of an error (the global status has not
previously been set) and error context information is available,
then construct an error context message. */
if ( astOK &&
( current_routine || current_file || current_line ) ) {
nc = sprintf( buff, "AST: Error" );
if ( current_routine ) {
nc += sprintf( buff + nc, " in routine %s", current_routine );
}
if ( current_line ) {
nc += sprintf( buff + nc, " at line %d", current_line );
}
if ( current_file ) {
nc += sprintf( buff + nc, " in file %s", current_file );
}
nc += sprintf( buff + nc, "." );
/* Deliver the error message unless reporting has been switched off using
astReporting. In which case store them in a static array. */
if( reporting ) {
INVOKE_ASTPUTERR( status_value, buff );
} else if( mstack_size < AST__ERROR_MSTACK_SIZE ){
imess = mstack_size++;
message_stack[ imess ] = MALLOC( strlen( buff ) + 1 );
if( message_stack[ imess ] ) {
strcpy( message_stack[ imess ], buff );
}
}
/* Set the global status. */
astSetStatus( status_value );
}
/* Write the error message supplied to the formatting buffer. */
nc = vsprintf( buff, fmt, args );
/* Tidy up the argument pointer. */
va_end( args );
/* Deliver the error message unless reporting has been switched off using
astReporting. */
if( reporting ) {
INVOKE_ASTPUTERR( status_value, buff );
} else if( mstack_size < AST__ERROR_MSTACK_SIZE ){
imess = mstack_size++;
message_stack[ imess ] = MALLOC( strlen( buff ) + 1 );
if( message_stack[ imess ] ) {
strcpy( message_stack[ imess ], buff );
}
}
/* Set the error status value. */
astSetStatus( status_value );
/* Undefine macros local to this function. */
#undef BUFF_LEN
}
void astError_( int status_value, const char *fmt, int *status, ... ) {
/*
*+
* Name:
* astError
* Purpose:
* Set the AST error status and report an error message.
* Type:
* Protected function.
* Synopsis:
* #include "error.h"
* void astError( int status_value, const char *fmt, int *status, ... )
* Description:
* This function sets the AST error status to a specified value and
* reports an associated error message.
* Parameters:
* status_value
* The error status value to be set.
* fmt
* Pointer to a null-terminated character string containing the
* format specification for the error message, in the same way
* as for a call to the C "printf" family of functions.
* status
* Pointer to the integer holding the inherited status value.
* ...
* Additional optional arguments (as used by e.g. "printf")
* which specify values which are to appear in the error
* message.
* Notes:
* This function operates just like "printf", except that:
* - The first argument is an error status.
* - The return value is void.
* - A newline is automatically appended to the error message
* (there is no need to add one).
* - This function is documented as protected because it should not
* be invoked by external code. However, it is available via the
* external C interface so that it may be used when writing (e.g.)
* foreign language or graphics interfaces.
*-
* This is the protected implementation of astError. It has a status
pointer parameter that is not present in the public form. Different
implementations for protected and public interfaces are required
because of the variable argument list.
*/
/* Local Constants: */
#define BUFF_LEN 1023 /* Max. length of an error message */
/* Local Variables: */
astDECLARE_GLOBALS /* Pointer to thread-specific global data */
char buff[ BUFF_LEN + 1 ]; /* Message buffer */
int imess; /* Index into deferred message stack */
int nc; /* Number of characters written */
va_list args; /* Variable argument list pointer */
/* Initialise the variable argument list pointer. */
va_start( args, status );
/* If needed, get a pointer to the thread specific global data structure. */
astGET_GLOBALS(NULL);
/* If this is the first report of an error (the global status has not
previously been set) and error context information is available,
then construct an error context message. */
if ( astOK &&
( current_routine || current_file || current_line ) ) {
nc = sprintf( buff, "AST: Error" );
if ( current_routine ) {
nc += sprintf( buff + nc, " in routine %s", current_routine );
}
if ( current_line ) {
nc += sprintf( buff + nc, " at line %d", current_line );
}
if ( current_file ) {
nc += sprintf( buff + nc, " in file %s", current_file );
}
nc += sprintf( buff + nc, "." );
/* Deliver the error message unless reporting has been switched off using
astReporting. In which case store them in a static array. */
if( reporting ) {
INVOKE_ASTPUTERR( status_value, buff );
} else if( mstack_size < AST__ERROR_MSTACK_SIZE ){
imess = mstack_size++;
message_stack[ imess ] = MALLOC( strlen( buff ) + 1 );
if( message_stack[ imess ] ) {
strcpy( message_stack[ imess ], buff );
}
}
/* Set the global status. */
astSetStatus( status_value );
}
/* Write the error message supplied to the formatting buffer. */
nc = vsprintf( buff, fmt, args );
/* Tidy up the argument pointer. */
va_end( args );
/* Deliver the error message unless reporting has been switched off using
astReporting. */
if( reporting ) {
INVOKE_ASTPUTERR( status_value, buff );
} else if( mstack_size < AST__ERROR_MSTACK_SIZE ){
imess = mstack_size++;
message_stack[ imess ] = MALLOC( strlen( buff ) + 1 );
if( message_stack[ imess ] ) {
strcpy( message_stack[ imess ], buff );
}
}
/* Set the error status value. */
astSetStatus( status_value );
/* Undefine macros local to this function. */
#undef BUFF_LEN
}
int *astGetStatusPtr_(){
/*
*+
* Name:
* astGetStatusPtr
* Purpose:
* Return a pointer to the integer holding the inherited status value.
* Type:
* Protected function.
* Synopsis:
* #include "error.h"
* int *astGetStatusPtr;
* Description:
* This macro returns a pointer to the integer holding the inherited
* status pointer. This will either be an internal global integer
* (possibly stored as thread specific data), or an ineger specified
* via the astWatch function.
* Returned Value:
* A pointer to the integer holding the inherited status value.
*-
*/
/* The thread-safe version of AST stores the status pointer in thread
specific data, using the key stored in the global variable
"starlink_ast_status_key". */
#if defined(THREAD_SAFE)
astDECLARE_GLOBALS
AstStatusBlock *sb;
astGET_GLOBALS(NULL);
sb = (AstStatusBlock *) pthread_getspecific(starlink_ast_status_key);
return sb->status_ptr;
/* The non thread-safe version of AST stores the status pointer in the
global variable "starlink_ast_status_ptr". */
#else
return starlink_ast_status_ptr;
#endif
}
/*
c++
* Name:
* astOK
* Purpose:
* Test whether AST functions have been successful.
* Type:
* Public macro.
* Synopsis:
* #include "error.h"
* int astOK
* Description:
* This macro returns a boolean value (0 or 1) to indicate if
* preceding AST functions have completed successfully
* (i.e. without setting the AST error status). If the error status
* is set to an error value, a value of zero is returned, otherwise
* the result is one.
* Returned Value:
* astOK
* One if the AST error status is OK, otherwise zero.
* Notes:
* - If the AST error status is set to an error value (after an
* error), most AST functions will not execute and will simply
* return without action. To clear the error status and restore
* normal behaviour, use astClearStatus.
c--
*/
int astReporting_( int report, int *status ) {
/*
c+
* Name:
* astReporting
* Purpose:
* Controls the reporting of error messages.
* Type:
* Protected function.
* Synopsis:
* #include "error.h"
* int astReporting( int report )
* Description:
* Error messages supplied to astError will only be delivered to the
* underlying error system if the "Reporting" flag is set to a
* non-zero value. Setting this flag to zero suppresses the reporting
* of error messages (the value of the AST error status however is
* unaffected). Instead, the reports are saved in an internal message
* stack. When reporting is switched back on again, any messages on this
* stack of deferred messages will be reported (and the stack emptied)
* if the AST error status is not astOK. Also the stack is emptied each
* time astClearStatus is called (the stacked messages are not displayed
* in this case).
* Parameters:
* report
* The new value for the Reporting flag.
* Returned Value:
* The original value of the Reporting flag.
* Notes:
* - The Reporting flag is initially set to 1.
c-
*/
/* Local Variables: */
astDECLARE_GLOBALS /* Pointer to thread-specific global data */
int oldval; /* Original "reporting" value */
/* If needed, get a pointer to the thread specific global data structure. */
astGET_GLOBALS(NULL);
/* Save the original reporting value, and then store the new value. */
oldval = reporting;
reporting = report;
/* If we are now reporting errors, flush any messages on the error stack.
This causes the messages to be displayed and the stack emptied. */
if( reporting ) EmptyStack( 1, status );
/* Return the original reporting value. */
return oldval;
}
/*
c++
* Name:
* astSetStatus
* Purpose:
* Set the AST error status to an explicit value.
* Type:
* Public function.
* Synopsis:
* #include "error.h"
* void astSetStatus( int status_value )
* Description:
* This function sets the AST error status to the value supplied.
* It does not cause any error message to be produced and should
* not be used as part of normal error reporting. Its purpose is
* simply to communicate to AST that an error has occurred in some
* other item of software.
*
* For example, a source or sink function supplied as an argument
* to astChannel or astFitsChan might use this to signal that an
* input/output error has occurred. AST could then respond by
* terminating the current read or write operation.
* Parameters:
* status_value
* The new error status value to be set.
* Notes:
* - If the AST error status is set to an error value, most AST
* functions will not execute and will simply return without
* action. To clear the error status and restore normal behaviour,
* use astClearStatus.
c--
*/
/*
c++
* Name:
* astStatus
* Purpose:
* Obtain the current AST error status value.
* Type:
* Public function.
* Synopsis:
* #include "error.h"
* int astStatus
* Description:
* This function returns the current value of the AST error status.
* Returned Value:
* astStatus
* The AST error status value.
* Notes:
* - If the AST error status is set to an error value (after an
* error), most AST functions will not execute and will simply
* return without action. To clear the error status and restore
* normal behaviour, use astClearStatus.
c--
*/
int *astWatch_( int *status_ptr ) {
/*
c++
* Name:
* astWatch
* Purpose:
* Identify a new error status variable for the AST library.
* Type:
* Public function.
* Synopsis:
* #include "error.h"
* int *astWatch( int *status_ptr )
* Description:
* This function allows a new error status variable to be accessed
* by the AST library when checking for and reporting error
* conditions.
*
* By default, the library uses an internal integer error status
* which is set to an error value if an error occurs. Use of
* astWatch allows the internal error status to be replaced by an
* integer variable of your choosing, so that the AST library can
* share its error status directly with other code which uses the
* same error detection convention.
*
* If an alternative error status variable is supplied, it is used
* by all related AST functions and macros (e.g. astOK, astStatus
* and astClearStatus).
* Parameters:
* status_ptr
* Pointer to an int whose value is to be used subsequently as
* the AST inherited status value. If a NULL pointer is supplied,
* the AST library will revert to using its own internal error status.
* Returned Value:
* astWatch()
* Address of the previous error status variable. This may later
* be passed back to astWatch to restore the previous behaviour
* of the library. (Note that on the first invocation of
* astWatch the returned value will be the address of the
* internal error status variable.)
* Notes:
* - This function is not available in the FORTRAN 77 interface to
* the AST library.
c--
*/
/* Local Variables: */
int *result; /* Value to be returned */
astDECLARE_GLOBALS /* Pointer to thread-specific global data */
#if defined(THREAD_SAFE)
AstStatusBlock *sb = NULL;
#endif
/* Ensure that the thread-specific status block has been created and
ininitialised. */
astGET_GLOBALS(NULL);
#if defined(THREAD_SAFE)
sb = (AstStatusBlock *) pthread_getspecific( starlink_ast_status_key );
result = sb->status_ptr;
sb->status_ptr = status_ptr ? status_ptr : &(sb->internal_status);
#else
result = starlink_ast_status_ptr;
starlink_ast_status_ptr = status_ptr ? status_ptr : &internal_status;
#endif
/* Return the old address. */
return result;
}
|