update ast 8.6.2

1 files changed, 8950 insertions, 0 deletions

diff --git a/ast/object.c b/ast/object.c
new file mode 100644
index 0000000..2f8d869
--- /dev/null
+++ b/ast/object.c
@@ -0,0 +1,8950 @@
+/*
+*class++
+
+*  Name:
+*     Object
+
+*  Purpose:
+*     Base class for all AST Objects.
+
+*  Constructor Function:
+*     None.
+
+*  Description:
+*     This class is the base class from which all other classes in the
+*     AST library are derived. It provides all the basic Object
+*     behaviour and Object manipulation facilities required throughout
+*     the library. There is no Object constructor, however, as Objects
+*     on their own are not useful.
+
+*  Inheritance:
+*     The Object base class does not inherit from any other class.
+
+*  Attributes:
+*     All Objects have the following attributes:
+*
+*     - Class: Object class name
+*     - ID: Object identification string
+*     - Ident: Permanent Object identification string
+*     - Nobject: Number of Objects in class
+*     - ObjSize: The in-memory size of the Object in bytes
+*     - RefCount: Count of active Object pointers
+*     - UseDefs: Allow use of default values for Object attributes?
+
+*  Functions:
+c     The following functions may be applied to all Objects:
+f     The following routines may be applied to all Objects:
+*
+c     - astAnnul: Annul a pointer to an Object
+c     - astBegin: Begin a new AST context
+c     - astClear: Clear attribute values for an Object
+c     - astClone: Clone a pointer to an Object
+c     - astCopy: Copy an Object
+c     - astCreatedAt: Returns information about where an object was created
+c     - astDelete: Delete an Object
+c     - astEnd: End an AST context
+c     - astEscapes: Control whether graphical escape sequences are removed
+c     - astExempt: Exempt an Object pointer from AST context handling
+c     - astExport: Export an Object pointer to an outer context
+c     - astGet<X>: Get an attribute value for an Object
+c     - astHasAttribute: Test if an Object has a named attribute
+c     - astImport: Import an Object pointer to the current context
+c     - astIsA<Class>: Test class membership
+c     - astLock: Lock an Object for use by the calling thread
+c     - astToString: Create an in-memory serialisation of an Object
+c     - astSame: Do two AST pointers refer to the same Object?
+c     - astSet: Set attribute values for an Object
+c     - astSet<X>: Set an attribute value for an Object
+c     - astShow: Display a textual representation of an Object on standard
+c     output
+c     - astTest: Test if an attribute value is set for an Object
+c     - astTune: Set or get an integer AST tuning parameter
+c     - astTuneC: Set or get a character AST tuning parameter
+c     - astUnlock: Unlock an Object for use by other threads
+c     - astFromString: Re-create an Object from an in-memory serialisation
+c     - astVersion: Return the verson of the AST library being used.
+f     - AST_ANNUL: Annul a pointer to an Object
+f     - AST_BEGIN: Begin a new AST context
+f     - AST_CLEAR: Clear attribute values for an Object
+f     - AST_CLONE: Clone a pointer to an Object
+f     - AST_COPY: Copy an Object
+f     - AST_DELETE: Delete an Object
+f     - AST_END: End an AST context
+f     - AST_ESCAPES: Control whether graphical escape sequences are removed
+f     - AST_EXEMPT: Exempt an Object pointer from AST context handling
+f     - AST_EXPORT: Export an Object pointer to an outer context
+f     - AST_GET<X>: Get an attribute value for an Object
+f     - AST_HASATTRIBUTE: Test if an Object has a named attribute
+f     - AST_IMPORT: Import an Object pointer to the current context
+f     - AST_ISA<CLASS>: Test class membership
+f     - AST_SAME: Do two AST pointers refer to the same Object?
+f     - AST_SET: Set attribute values for an Object
+f     - AST_SET<X>: Set an attribute value for an Object
+f     - AST_SHOW: Display a textual representation of an Object on standard
+f     output
+f     - AST_TEST: Test if an attribute value is set for an Object
+f     - AST_TUNE: Set or get an integer AST tuning parameter
+f     - AST_TUNEC: Set or get a character AST tuning parameter
+f     - AST_VERSION: Return the verson of the AST library being used.
+
+*  Copyright:
+*     Copyright (C) 1997-2006 Council for the Central Laboratory of the
+*     Research Councils
+*     Copyright (C) 2010 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:
+*     1-FEB-1996 (RFWS):
+*        Original version.
+*     22-APR-1996 (RFWS):
+*        Added attribute setting functions.
+*     2-JUL-1996 (RFWS):
+*        Added functions to support the external interface (using
+*        identfiers).
+*     10-SEP-1996 (RFWS):
+*        Added I/O facilities.
+*     30-MAY-1997 (RFWS):
+*        Add ID attribute.
+*     14-JUL-1997 (RFWS):
+*        Add astExempt function.
+*     14-OCT-1997 (RFWS):
+*        Fixed uninitialised use of "dynamic" in astCopy_.
+*     14-NOV-1997 (RFWS):
+*        Remove the subversive C "strtok" function.
+*     20-JAN-1998 (RFWS):
+*        Make the astClear and astRVSet methods virtual.
+*     29-APR-1998 (RFWS):
+*        Fixed bug in algorithm for encoding Object IDs.
+*     15-SEP-1999 (RFWS)
+*        Made astAnnulId accessible from protected code.
+*     12-APR-2000 (DSB):
+*        Zero all memory allocated for a new Object in InitObject before
+*        storing any new values in the memory.
+*     3-APR-2001 (DSB):
+*        Added the Ident attribute.
+*     28-SEP-2001 (DSB):
+*        Modified VSet to ensure a non-null string always follows the equal
+*        sign in the attribute setting passed to SetAttrib.
+*     27-NOV-2002 (DSB):
+*        Modified astShow to use astWrite instead of astDump, so that
+*        invocations of astShow will be included in the count of the
+*        number of invocations of astWrite returned by astWriteInvocations.
+*     8-JAN-2003 (DSB):
+*        Changed private InitVtab method to protected astInitObjectVtab
+*        method.
+*     8-FEB-2004 (DSB):
+*        Added astEscapes.
+*     10-FEB-2004 (DSB):
+*        Added debug conditional code to keep track of memory leaks.
+*     22-AUG-2004 (DSB):
+*        Added astEqual
+*     27-JAN-2005 (DSB):
+*        Correct use of ->ident pointers, and added further DEBUG blocks.
+*     11-MAR-2005 (DSB):
+*        Added attribute UseDefs.
+*     14-FEB-2006 (DSB):
+*        Added attribute ObjSize.
+*     23-FEB-2006 (DSB):
+*        Added MemoryCaching tuning parameter.
+*     27-FEB-2006 (DSB):
+*        Include Objects returned by astCopy in the ObjectCaching system.
+*     28-FEB-2006 (DSB):
+*        Use astOK to protect against errors within astGrow.
+*     1-MAR-2006 (DSB):
+*        Replace astSetPermMap within DEBUG blocks by astBeginPM/astEndPM.
+*     26-MAY-2006 (DSB):
+*        Correct handling of commas within the attribute value supplied
+*        to astSetC.
+*     30-MAY-2006 (DSB):
+*        Correct the correction made to handle commas within attribute
+*     6-JUN-2007 (DSB):
+*        Fix harmless compiler warnings.
+*     21-JUN-2007 (DSB):
+*        In astSet<X>, ignore trailing spaces in the attribute name.
+*     22-JUN-2007 (DSB):
+*        - Make astVSet return a pointer to dynamic memory holding the
+*        expanded setting string.
+*        - Add astSetVtab, and astCast.
+*     27-JUN-2007 (DSB):
+*        Modify astInitObject so that it ignores the supplied "size" value
+*        if some memory is supplied.
+*     2-JULY-2007 (DSB):
+*        Fix memory access problem in VSet.
+*     20-SEP-2007 (DSB):
+*        In astDelete, ensure the error status is reset before calling
+*        astGrow to extend the vtab free list.
+*     22-APR-2008 (DSB):
+*        Added astSame.
+*     24-OCT-2008 (DSB):
+*        Prevent a mutex deadlock that could occur when annulling an
+*        Object ID.
+*     28-JAN-2008 (DSB):
+*        Allow unlocked objects to be annulled using astAnnul.
+*     14-OCT-2009 (DSB):
+*        Modify astCast to make it a virtual function and add type
+*        checking.
+*     7-APR-2010 (DSB):
+*        Added method astHasAttribute.
+*     24-AUG-2010 (DSB):
+*        Allow commas to be included in attribute values supplied to
+*        astSet or astVSet by putting quotes around the attribute value.
+*     16-JUN-2011 (DSB):
+*        Added component "iref" to the Object structure. This is an
+*        integer identifier for each object that is unique within the
+*        class of the object. Useful for debugging.
+*     22-JUL-2011 (DSB):
+*        Add methods astSetProxy and astGetProxy.
+*     2-SEP-2011 (DSB):
+*        Add functions astToString and astFromString.
+*     13-SEP-2013 (DSB):
+*        Report an error in astAnnul if the supplied object handle is owned by
+*        a different thread. Note, the Object itself does not need to be owned
+*        by the current thread, since it should be possible for a thread to
+*        relinquish a pointer to an object (i.e. a handle) without actually
+*        owning the object itself.
+*     6-JAN-2014 (DSB):
+*        Added method astEnvSet.
+*     9-APR-2015 (DSB):
+*        Modify VSet to handle "%s" setting strings (i.e. where the whole
+*        list of settings is provided as a single variable argument).
+*        This is needed because supplying the while settings string in
+*        place of "%s" is considered a security issue by many compilers.
+*     4-JUL-2017 (DSB):
+*        Within astLockId, perform the correct check that the supplied
+*        object handle is not locked by another thread.
+*     17-SEP-2017 (DSB):
+*        Add function astCreatedAt. This increases the size of a Handle
+*        structure by 20 bytes. If this turns out to be problematic
+*        this facility could be controlled using a configure option.
+*class--
+*/
+
+/* Module Macros. */
+/* ============== */
+/* Set the name of the class we are implementing. This indicates to
+   the header files that define class interfaces that they should make
+   "protected" symbols available. */
+#define astCLASS Object
+
+#define INVALID_CONTEXT -1   /* Context value for handles that have no
+                                associated Object */
+#define UNOWNED_CONTEXT -2   /* Context value for handles for objects
+                                that are not locked by any thread */
+
+
+/* Include files. */
+/* ============== */
+
+/* Configuration information */
+/* ------------------------ */
+#include "version.h"             /* Version numbers */
+#if HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+/* Interface definitions. */
+/* ---------------------- */
+#include "error.h"               /* Error reporting facilities */
+#include "memory.h"              /* Memory allocation facilities */
+#include "channel.h"             /* I/O channels */
+#include "keymap.h"              /* Hash tables */
+#include "object.h"              /* Interface definition for this class */
+#include "plot.h"                /* Plot class (for astStripEscapes) */
+#include "globals.h"             /* Thread-safe global data access */
+
+/* Error code definitions. */
+/* ----------------------- */
+#include "ast_err.h"             /* AST error codes */
+
+/* C header files. */
+/* --------------- */
+#include <ctype.h>
+#include <errno.h>
+#include <float.h>
+#include <stdarg.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <limits.h>
+
+/* Type Definitions */
+/* ================ */
+/* Structure used to pass data between astToString/FromString and the
+   corresponding Channel source and sink functions. */
+typedef struct StringData {
+   char *ptr;      /* Pointer to serialisation text */
+   char *buff;     /* Pointer to a buffer for a single line of text */
+   int len;        /* Current length of serialisation text */
+} StringData;
+
+/* Module Variables. */
+/* ================= */
+
+/* The following globals have the same values in all threads and so do
+   not need to be in thread-specific data. */
+/* ------------------------------------------------------------------ */
+
+/* Character-valued tuning parameters. */
+#define MAXLEN_TUNEC 200
+static char hrdel[ MAXLEN_TUNEC ] = "%-%^50+%s70+h%+";
+static char mndel[ MAXLEN_TUNEC ] = "%-%^50+%s70+m%+";
+static char scdel[ MAXLEN_TUNEC ] = "%-%^50+%s70+s%+";
+static char dgdel[ MAXLEN_TUNEC ] = "%-%^53+%s60+o%+";
+static char amdel[ MAXLEN_TUNEC ] = "%-%^20+%s85+'%+";
+static char asdel[ MAXLEN_TUNEC ] = "%-%^20+%s85+\"%+";
+static char exdel[ MAXLEN_TUNEC ] = "10%-%^50+%s70+";
+
+/* A pointer full of zeros. */
+static AstObject *zero_ptr;
+
+/* A flag which indicates what should happen when an AST Object is
+   deleted. If this flag is non-zero, the memory used by the Object is
+   not freed, but a pointer to it is placed on the end of a list of free
+   memory chunk pointers so that the memory can be re-used if necessary
+   avoiding the need to re-allocate memory with malloc (which is slow).
+   A separate list of free memory chunks is kept for each class because
+   each class object will require chunks of a different size. Pointers
+   to these lists are stored in the virtual function table associated
+   with each class. All memory on these lists is freed when object
+   caching is switched off via the astTune function. */
+static int object_caching = 0;
+
+/* Set up global data access, mutexes, etc, needed for thread safety. */
+#ifdef THREAD_SAFE
+
+/* Define the initial values for the global data for this module. */
+#define GLOBAL_inits \
+   globals->Retain_Esc = 0; \
+   globals->Context_Level = 0; \
+   globals->GetAttrib_Buff[ 0 ] = 0; \
+   globals->AstGetC_Init = 0; \
+   globals->AstGetC_Istr = 0; \
+   globals->Active_Handles = NULL; \
+   globals->Class_Init = 0; \
+   globals->Nvtab = 0; \
+   globals->Known_Vtabs = NULL;
+
+/* Create the function that initialises global data for this module. */
+astMAKE_INITGLOBALS(Object)
+
+/* Define macros for accessing each item of thread specific global data. */
+#define retain_esc  astGLOBAL(Object,Retain_Esc)
+#define context_level  astGLOBAL(Object,Context_Level)
+#define active_handles  astGLOBAL(Object,Active_Handles)
+#define getattrib_buff  astGLOBAL(Object,GetAttrib_Buff)
+#define astgetc_strings  astGLOBAL(Object,AstGetC_Strings)
+#define astgetc_istr  astGLOBAL(Object,AstGetC_Istr)
+#define astgetc_init  astGLOBAL(Object,AstGetC_Init)
+#define class_init astGLOBAL(Object,Class_Init)
+#define class_vtab astGLOBAL(Object,Class_Vtab)
+#define nvtab astGLOBAL(Object,Nvtab)
+#define known_vtabs astGLOBAL(Object,Known_Vtabs)
+
+/* mutex1 is used to prevent tuning parameters being accessed by more
+   than one thread at any one time.  */
+static pthread_mutex_t mutex1 = PTHREAD_MUTEX_INITIALIZER;
+#define LOCK_MUTEX1 pthread_mutex_lock( &mutex1 );
+#define UNLOCK_MUTEX1 pthread_mutex_unlock( &mutex1 );
+
+/* mutex2 is used to prevent the global lists of object handles being
+   accessed by more than one thread at any one time.  */
+static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER;
+#define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 );
+#define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 );
+
+/* Each Object contains two mutexes. The primary mutex (mutex1) is used
+   to guard access to all aspects of the Object except for the "locker"
+   and "ref_count" items. The secondary mutex (mutex2) is used to guard
+   access to these two remaining items. We need this secondary mutex
+   since the "locker" and "ref_count" items need to be accessable within
+   a thread even if that thread has not locked the Object using astLock.
+   Define macros for accessing these two mutexes. */
+#define LOCK_PMUTEX(this) (pthread_mutex_lock(&((this)->mutex1)))
+#define UNLOCK_PMUTEX(this) (pthread_mutex_unlock(&((this)->mutex1)))
+#define LOCK_SMUTEX(this) (pthread_mutex_lock(&((this)->mutex2)))
+#define UNLOCK_SMUTEX(this) (pthread_mutex_unlock(&((this)->mutex2)))
+
+
+
+
+
+/* If thread safety is not needed, declare and initialise globals at static
+   variables. */
+#else
+
+/* Define the class virtual function table and its initialisation flag as
+   static variables. */
+static int class_init = 0;       /* Virtual function table initialised? */
+static AstObjectVtab class_vtab; /* Virtual function table */
+
+/* A list of pointers to all the known class virtual function tables. */
+static int nvtab = 0;
+static AstObjectVtab **known_vtabs = NULL;
+
+/* A flag which indicates if AST functions which return text strings
+   should retain any graphical escape sequences (as interpreted by the
+   Plot class). */
+static int retain_esc = 0;
+
+/* Context level (Begin/End/Exempt/Export) */
+static int context_level = 0;
+
+/* Array of list heads for each context (each list is a list of Handle
+   structures). */
+static int *active_handles = NULL;
+
+/* String returned by GetAttrib. */
+static char getattrib_buff[ AST__GETATTRIB_BUFF_LEN + 1 ] = "";
+
+/* Pointers to string buffers returned by astGetC. */
+static char *astgetc_strings[ AST__ASTGETC_MAX_STRINGS ];
+
+/* Offset of next string in "AstGetC_Strings" */
+static int astgetc_istr = 0;
+
+/* "AstGetC_Strings" array initialised? */
+static int astgetc_init = 0;
+
+/* Null macros for mutex locking and unlocking */
+#define LOCK_MUTEX1
+#define UNLOCK_MUTEX1
+#define LOCK_MUTEX2
+#define UNLOCK_MUTEX2
+#define LOCK_PMUTEX(this)
+#define LOCK_SMUTEX(this)
+#define UNLOCK_PMUTEX(this)
+#define UNLOCK_SMUTEX(this)
+
+#endif
+
+
+/* Prototypes for Private Member Functions. */
+/* ======================================== */
+static AstObject *Cast( AstObject *, AstObject *, int * );
+static const char *GetID( AstObject *, int * );
+static const char *GetAttrib( AstObject *, const char *, int * );
+static const char *GetIdent( AstObject *, int * );
+static const char *Get( AstObject *, const char *, int * );
+static const char *FromStringSource( void );
+static int Equal( AstObject *, AstObject *, int * );
+static int GetObjSize( AstObject *, int * );
+static int HasAttribute( AstObject *, const char *, int * );
+static int Same( AstObject *, AstObject *, int * );
+static int TestAttrib( AstObject *, const char *, int * );
+static int TestID( AstObject *, int * );
+static int TestIdent( AstObject *, int * );
+static unsigned long Magic( const AstObject *, size_t, int * );
+static void CleanAttribs( AstObject *, int * );
+static void Clear( AstObject *, const char *, int * );
+static void ClearAttrib( AstObject *, const char *, int * );
+static void ClearIdent( AstObject *, int * );
+static void ClearID( AstObject *, int * );
+static void Dump( AstObject *, AstChannel *, int * );
+static void EmptyObjectCache( int * );
+static void ToStringSink( const char * );
+static void SetAttrib( AstObject *, const char *, int * );
+static void SetID( AstObject *, const char *, int * );
+static void SetIdent( AstObject *, const char *, int * );
+static void Show( AstObject *, int * );
+static void VSet( AstObject *, const char *, char **, va_list, int * );
+static void EnvSet( AstObject *, int * );
+
+static int GetUseDefs( AstObject *, int * );
+static int TestUseDefs( AstObject *, int * );
+static void ClearUseDefs( AstObject *, int * );
+static void SetUseDefs( AstObject *, int, int * );
+
+#if defined(THREAD_SAFE)
+static void ChangeThreadVtab( AstObject *, int * );
+static int ManageLock( AstObject *, int, int, AstObject **, int * );
+#endif
+
+/* Member functions. */
+/* ================= */
+AstObject *astAnnul_( AstObject *this, int *status ) {
+/*
+*++
+*  Name:
+c     astAnnul
+f     AST_ANNUL
+
+*  Purpose:
+*     Annul a pointer to an Object.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     AstObject *astAnnul( AstObject *this )
+f     CALL AST_ANNUL( THIS, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+c     This function annuls a pointer to an Object so that it is no
+f     This routine annuls a pointer to an Object so that it is no
+*     longer recognised as a valid pointer by the AST library. Any
+*     resources associated with the pointer are released and made
+*     available for re-use.
+*
+c     This function also decrements the Object's RefCount attribute by
+f     This routine also decrements the Object's RefCount attribute by
+*     one. If this attribute reaches zero (which happens when the last
+*     pointer to the Object is annulled), then the Object is deleted.
+
+*  Parameters:
+c     this
+c        The Object pointer to be annulled.
+f     THIS = INTEGER (Given and Returned)
+f        The Object pointer to be annulled. A null pointer value (AST__NULL)
+f        is always returned.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+c  Returned Value:
+c     astAnnul()
+c        A null Object pointer (AST__NULL) is always returned.
+c
+*  Applicability:
+*     Object
+c        This function applies to all Objects.
+f        This routine applies to all Objects.
+
+*  Notes:
+c     - This function will attempt to annul the pointer even if the
+c     Object is not currently locked by the calling thread (see astLock).
+c     - This function attempts to execute even if the AST error
+c     status is set
+f     - This routine attempts to execute even if STATUS is set to an
+f     error value
+*     on entry, although no further error report will be
+*     made if it subsequently fails under these circumstances. In
+*     particular, it will fail if the pointer suppled is not valid,
+*     but this will only be reported if the error status is clear on
+*     entry.
+*--
+*/
+
+/* Check the pointer to ensure it identifies a valid Object (this
+   generates an error if it doesn't). */
+   if ( !astIsAObject( this ) ) return NULL;
+
+/* Get a lock on the object's secondary mutex. This mutex guards access
+   to the "ref_count" and "locker" components of the AstObject structure. */
+   LOCK_SMUTEX(this);
+
+#ifdef MEM_DEBUG
+   {   int rc;
+       char buf[100];
+       rc = this->ref_count;
+       sprintf(buf,"annulled (refcnt: %d -> %d)", rc, rc-1 );
+       astMemoryUse( this, buf );
+   }
+#endif
+
+/* Decrement the Object's reference count. */
+   --(this->ref_count);
+
+/* Unlock the object's secondary mutex. */
+   UNLOCK_SMUTEX(this);
+
+/* Decrement the Object's reference count and delete the Object if
+   necessary. */
+   if ( !this->ref_count ) (void) astDelete( this );
+
+/* Always return NULL. */
+   return NULL;
+}
+
+static AstObject *Cast( AstObject *this, AstObject *obj, int *status ) {
+/*
+*+
+*  Name:
+*     astCast
+
+*  Purpose:
+*     Cast an Object into an instance of a sub-class.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astCast( AstObject *this, AstObject *obj )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns a deep copy of an ancestral component of the
+*     supplied object. The required class of the ancestral component is
+*     specified by another object. Specifically, if "this" and "new" are
+*     of the same class, a copy of "this" is returned. If "this" is an
+*     instance of a subclass of "obj", then a copy of the component
+*     of "this" that matches the class of "obj" is returned. Otherwise,
+*     a NULL pointer is returned without error.
+
+*  Parameters:
+*     this
+*        Pointer to the Object to be cast.
+*     obj
+*        Pointer to an Object that defines the class of the returned Object.
+*        The returned Object will be of the same class as "obj".
+
+*  Returned Value:
+*     A pointer to the new Object. NULL if "this" is not a sub-class of
+*     "obj", or if an error occurs.
+
+*  Notes:
+*     - A NULL pointer will be returned if this function is invoked
+*     with the global error status set, or if it should fail for any
+*     reason.
+*-
+*/
+
+/* Local Variables: */
+   AstObject *new;
+   int generation_gap;
+
+/* Initialise */
+   new = NULL;
+
+/* Check inherited status */
+   if( !astOK ) return new;
+
+/* Check pointer have been supplied. */
+   if( this && obj ) {
+
+/* See how many steps up the class inheritance ladder it is from "this" to
+   "obj". A positive value is returned if "this" is a sub-class of "obj".
+   A negative value is returned if "obj" is a sub-class of "this". Zero
+   is returned if they are of the same class. AST__COUSIN is returned if
+   they share a common ancestor but are not on the same line of descent. */
+      generation_gap = astClassCompare( astVTAB( this ), astVTAB( obj ) );
+
+/* If the two objects are of the same class, just return a copy of
+   "this". */
+      if( generation_gap == 0 ) {
+         new = astCopy( this );
+
+/* If "this" is a subclass of "obj", return a deep copy of "this" cast
+   into the class of "obj". */
+      } else if( generation_gap != AST__COUSIN && generation_gap > 0 ) {
+         new = astCastCopy( this, obj );
+
+      }
+   }
+
+/* Return the new pointer. */
+   return new;
+}
+
+AstObject *astCastCopy_( AstObject *this, AstObject *obj, int *status ) {
+/*
+*+
+*  Name:
+*     astCastCopy
+
+*  Purpose:
+*     Cast an Object into an instance of a sub-class, without type-checking.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astCastCopy( AstObject *this, AstObject *obj )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns a deep copy of an ancestral component of the
+*     supplied object. The required class of the ancestral component is
+*     specified by another object. No checks are performed that "this" is
+*     a sub-class of "obj".
+*
+*     It works by temporarily changing the vtab in "this" to be the same
+*     as in "obj", and then doing a deep copy, and then re-instating the
+*     original vtab.
+
+*  Parameters:
+*     this
+*        Pointer to the Object to be cast.
+*     obj
+*        Pointer to an Object that defines the class of the returned Object.
+*        The returned Object will be of the same class as "obj".
+
+*  Returned Value:
+*     A pointer to the new Object.
+
+*  Notes:
+*     - A NULL pointer will be returned if this function is invoked
+*     with the global error status set, or if it should fail for any
+*     reason.
+*-
+*/
+
+/* Local Variables: */
+   AstObject *new;
+   AstObjectVtab *this_vtab;
+   size_t this_size;
+
+/* Initialise */
+   new = NULL;
+
+/* Check inherited status */
+   if( !astOK ) return new;
+
+/* Check pointer have been supplied. */
+   if( this && obj ) {
+
+/* Save a pointer to the original virtual function tables for "this". */
+      this_vtab = astVTAB( this );
+
+/* Temporarily change the vtab of "this" to that of "obJ". */
+      this->vtab = astVTAB( obj );
+
+/* Temporarily change the size of "this" to be the size of "obj". */
+      this_size = this->size;
+      this->size = obj->size;
+
+/* Now take a copy of the object (now considered to be an instance of the
+   class specified by "obj"). */
+      new = astCopy( this );
+
+/* Re-instate the original Object vtab and size. */
+      this->vtab = this_vtab;
+      this->size = this_size;
+
+/* The sub-clas to which "this" originally belonged may have extended the
+   range of values allowed for one or more of the attributes inherited from
+   the "obj" class. This means that the current attribute values stored
+   in the returned object may be inappropriate for the class of "obj". An
+   example is the System attribute defined by the Frame class, and extended
+   by sub-classes of Frame. So we now call astCleanAttribs to ensure that
+   any inappropriate attribute values are cleared in the returned object. */
+      astCleanAttribs( new );
+   }
+
+/* Return the new pointer. */
+   return new;
+}
+
+#if defined(THREAD_SAFE)
+static void ChangeThreadVtab( AstObject *this, int *status ){
+/*
+*  Name:
+*     ChangeThreadVtab
+
+*  Purpose:
+*     Modify an Object structure so that it refers to a vtab created by
+*     the currently executing thread.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void ChangeThreadVtab( AstObject *this, int *status )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     Each Object structure contains a pointer to a virtual function
+*     table (vtab) that identifies information about the class to
+*     which the Object belongs (function pointers, Object caches,
+*     etc). In order to avoid use of mutexes (which can slow down AST
+*     applications enormously), each thread has its own set of vtab
+*     structures (one for each AST class) stored in thread-specific
+*     data. Each time an Object is locked by the currently executing
+*     thread, this function should be called to change the vtab pointer
+*     in the Object to refer to the vtab relevant to the currently
+*     executing thread.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+*     status
+*        Pointer to the inherited status variable.
+
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS
+   const char *class;
+   int i;
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to Thread-specific data for the currently executing thread. */
+   astGET_GLOBALS(this);
+
+/* Get the class name for the supplied Object. This uses the existing
+   vtab pointer in the Object structure to locate the required GetClass
+   method and the class name. This vtab pointer may be for a vtab created
+   by a different thread to the one currently executing, but this shouldn't
+   matter since we are not modifying the vtab contents. */
+   class = astGetClass( this );
+
+/* Check a class name was obtained */
+   if( class ) {
+
+/* Loop round the vtab structures created by the currently executing thread. */
+      for( i = 0; i < nvtab; i++ ) {
+
+/* If the current vtab is for a class that matches the class of the
+   supplied Object, then store a pointer to the vtab in the Object
+   structure, and exit. */
+         if( !strcmp( class, known_vtabs[ i ]->class ) ) {
+            this->vtab = known_vtabs[ i ];
+            break;
+         }
+      }
+   }
+}
+#endif
+
+AstObject *astCheckLock_( AstObject *this, int *status ) {
+/*
+*+
+*  Name:
+*     astCheckLock
+
+*  Purpose:
+*     Check that supplied Object is locked by the calling thread.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astCheckLock( AstObject *this )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function reports an error if the supplied object has not
+*     previously been locked (using astLock) by the calling thread.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+
+*  Returned Value:
+*     A copy of the supplied pointer ("this") is returned. The Object
+*     reference count is not changed.
+
+*  Notes:
+*     - This function attempts to execute even if an error has already
+*     occurred.
+
+*-
+*/
+
+/* This function does nothing in the non-threads version of libast. */
+#if defined(THREAD_SAFE)
+
+/* Local Variables; */
+   AstObject *fail;
+
+/* Check the supplied pointer. */
+   if( this ) {
+
+/* First use the private ManageLock function rather than the virtual
+   astManageLock method to check the top level Object is locked for use
+   by the current thread. This saves time and allows a more appropriate
+   error message to be issued. */
+      if( ManageLock( this, AST__CHECKLOCK, 0, NULL, status ) ) {
+         if( astOK ) {
+            astError( AST__LCKERR, "astCheckLock(%s): The supplied %s cannot "
+                      "be used since it is not locked for use by the current "
+                      "thread (programming error).", status, astGetClass( this ),
+                      astGetClass( this ) );
+         }
+
+/* If the top level Object is locked, now use the virtual astManageLock
+   method to check any objects contained within the top level Object. */
+      } else if( astManageLock( this, AST__CHECKLOCK, 0, &fail ) ) {
+         if( astOK ) {
+            astError( AST__LCKERR, "astCheckLock(%s): The supplied %s cannot "
+                      "be used since a %s contained within the %s is not "
+                      "locked for use by the current thread (programming "
+                      "error).", status, astGetClass( this ),
+                       astGetClass( this ), astGetClass( fail ),
+                       astGetClass( this ) );
+         }
+      }
+   }
+#endif
+
+/* Return the supploed pointer. */
+   return this;
+
+}
+
+int astClassCompare_( AstObjectVtab *class1, AstObjectVtab *class2,
+                      int *status ) {
+/*
+*+
+*  Name:
+*     astClassCompare
+
+*  Purpose:
+*     Determine the relationship between two AST classes.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     int astClassCompare( AstObjectVtab *class1, AstObjectVtab *class2 )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns the number of steps up the class inheritance
+*     ladder from the class specified by "class1" to the class specified
+*     by "class2".
+
+*  Parameters:
+*     class1
+*        Pointer to a virtual function table describing the first AST class.
+*     class2
+*        Pointer to a virtual function table describing the second AST class.
+
+*  Returned Value:
+*     The generation gap between "class1" and "class2". The result will be
+*     positive if "class1" is a subclass of "class2", negative if "class2"
+*     is a subclass of "class1", zero if they are of the same class (or
+*     an error occurs), or AST__COUSIN if they are not on the same line
+*     of descent.
+
+*-
+*/
+
+/* Local Variables: */
+   AstClassIdentifier *class1_id;
+   AstClassIdentifier *class2_id;
+   AstClassIdentifier *id;
+   int *class1_check;
+   int *class2_check;
+   int result;
+
+/* Initialise */
+   result = 0;
+
+/* Check inherited status */
+   if( !astOK ) return result;
+
+/* Check pointer have been supplied. */
+   if( class1 && class2 ) {
+
+/* Get pointers to the AstClassIdentifier that identifies the top-level
+   class of each vtab. */
+      class1_id = class1->top_id;
+      class2_id = class2->top_id;
+
+/* Class membership is specified by the "check" value in each class
+   identifier. Get the check values for both vtabs. */
+      class1_check = class1_id->check;
+      class2_check = class2_id->check;
+
+/* Try walking up the class heirarchy of "class1" until the class of
+   "class2" is reached. The top-level AstObject class has a NULL "parent"
+   pointer in its class identifier structure. */
+      id = class1_id;
+      while( id && ( id->check != class2_check ) ) {
+         id = id->parent;
+         result++;
+      }
+
+/* If "class1" is not a subclass of "class2", try walking up the class
+   heirarchy of "class2" until the class of "class1" is reached. */
+      if( !id ) {
+         result = 0;
+         id = class2_id;
+         while( id && ( id->check != class1_check ) ) {
+            id = id->parent;
+            result--;
+         }
+
+/* If "class2" is not a subclass of "class1", return AST__COUSIN. */
+         if( !id ) result = AST__COUSIN;
+      }
+   }
+
+/* Return the generation gap. */
+   return result;
+}
+
+static void CleanAttribs( AstObject *this_object, int *status ) {
+/*
+*+
+*  Name:
+*     astCleanAttribs
+
+*  Purpose:
+*     Clear any invalid set attribute values.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astCleanAttribs( AstObject *this, int *status )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function clears any attributes that are currently set to
+*     invalid values in the supplied object. This can happen for instance
+*     when an object is cast into an instance of a parent class using
+*     astCast, since sub-classes can extend the range of valid values
+*     an attribute can take.
+
+*  Parameters:
+*     this
+*        Pointer to the Object to be cleaned.
+*-
+*/
+
+/* The base Object class has no attributes that need cleaning. */
+
+}
+
+static void Clear( AstObject *this, const char *attrib, int *status ) {
+/*
+*++
+*  Name:
+c     astClear
+f     AST_CLEAR
+
+*  Purpose:
+*     Clear attribute values for an Object.
+
+*  Type:
+*     Public virtual function.
+
+*  Synopsis:
+c     #include "object.h"
+c     void astClear( AstObject *this, const char *attrib )
+f     CALL AST_CLEAR( THIS, ATTRIB, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+c     This function clears the values of a specified set of attributes
+f     This routine clears the values of a specified set of attributes
+*     for an Object. Clearing an attribute cancels any value that has
+*     previously been explicitly set for it, so that the standard
+*     default attribute value will subsequently be used instead. This
+c     also causes the astTest function to return the value zero for
+f     also causes the AST_TEST function to return the value .FALSE. for
+*     the attribute, indicating that no value has been set.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the Object.
+c     attrib
+f     ATTRIB = CHARACTER * ( * ) (Given)
+c        Pointer to a null-terminated character string containing a
+c        comma-separated list of the names of the attributes to be cleared.
+f        A character string containing a comma-separated list of the
+f        names of the attributes to be cleared.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Applicability:
+*     Object
+c        This function applies to all Objects.
+f        This routine applies to all Objects.
+
+*  Notes:
+*     - Attribute names are not case sensitive and may be surrounded
+*     by white space.
+*     - It does no harm to clear an attribute whose value has not been
+*     set.
+*     - An error will result if an attempt is made to clear the value
+*     of a read-only attribute.
+*--
+*/
+
+/* Local Variables: */
+   char *buff;                   /* Pointer to character buffer */
+   char *name;                   /* Pointer to individual attribute name */
+   char *name_end;               /* Pointer to null at end of name */
+   int i;                        /* Loop counter for characters */
+   int j;                        /* Non-blank character count */
+   int len;                      /* Length of attrib string */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Obtain the length of the attrib string. */
+   len = (int) strlen( attrib );
+   if ( len != 0 ) {
+
+/* Allocate memory and store a copy of the string. */
+      buff = astStore( NULL, attrib, (size_t) ( len + 1 ) );
+      if ( astOK ) {
+
+/* Loop to process each element in the comma-separated list. */
+         name = buff;
+         while ( name ) {
+
+/* Change the comma at the end of each element to a null to terminate
+   the name. */
+            if ( ( name_end = strchr( name, ',' ) ) ) *name_end = '\0';
+
+/* Remove white space and upper case characters from the attribute
+   name. */
+            for ( i = j = 0; name[ i ]; i++ ) {
+               if ( !isspace( name[ i ] ) ) name[ j++ ] = tolower( name[ i ] );
+            }
+
+/* Terminate the attribute name and pass it to astClearAttrib to clear
+   the attribute (unless it is all blank, in which case we ignore
+   it). */
+            name[ j ] = '\0';
+            if ( j ) astClearAttrib( this, name );
+
+/* Check for errors and abort if any clear operation fails. Otherwise,
+   process the next attribute. */
+            if ( !astOK ) break;
+            name = name_end ? name_end + 1 : NULL;
+         }
+      }
+
+/* Free the memory allocated for the string buffer. */
+      buff = astFree( buff );
+   }
+}
+
+static void ClearAttrib( AstObject *this, const char *attrib, int *status ) {
+/*
+*+
+*  Name:
+*     astClearAttrib
+
+*  Purpose:
+*     Clear an attribute value for an Object.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astClearAttrib( AstObject *this, const char *attrib )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function clears the value of a specified attribute for an
+*     Object, so that the default value will subsequently be used.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+*     attrib
+*        Pointer to a null-terminated string specifying the attribute
+*        name.  This should be in lower case with no surrounding white
+*        space.
+
+*  Notes:
+*     - The Object class does not have any writable attributes, so
+*     this function merely reports an error. It is intended to be
+*     extended by other class definitions.
+*-
+*/
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Check the attribute name and clear the appropriate attribute. */
+
+/* ID. */
+/* --- */
+   if ( !strcmp( attrib, "id" ) ) {
+      astClearID( this );
+
+/* Ident. */
+/* ------ */
+   } else if ( !strcmp( attrib, "ident" ) ) {
+      astClearIdent( this );
+
+/* UseDefs. */
+/* -------- */
+   } else if ( !strcmp( attrib, "usedefs" ) ) {
+      astClearUseDefs( this );
+
+/* Read-only attributes. */
+/* --------------------- */
+/* Test if the attribute string matches any of the read-only
+   attributes of this class. If it does, then report an error. */
+   } else if ( !strcmp( attrib, "class" ) ||
+               !strcmp( attrib, "nobject" ) ||
+               !strcmp( attrib, "objsize" ) ||
+               !strcmp( attrib, "refcount" ) ) {
+      astError( AST__NOWRT, "astClear: Invalid attempt to clear the \"%s\" "
+                "value for a %s.", status, attrib, astGetClass( this ) );
+      astError( AST__NOWRT, "This is a read-only attribute." , status);
+
+/* Since no writable attributes are defined for the Object class, any
+   attempt to clear a value for anything else is also an error. */
+   } else {
+      astError( AST__BADAT, "astClear: The attribute name \"%s\" is invalid "
+               "for a %s.", status, attrib, astGetClass( this ) );
+   }
+}
+
+AstObject *astClone_( AstObject *this, int *status ) {
+/*
+*++
+*  Name:
+c     astClone
+f     AST_CLONE
+
+*  Purpose:
+*     Clone (duplicate) an Object pointer.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     AstObject *astClone( AstObject *this )
+f     RESULT = AST_CLONE( THIS, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns a duplicate pointer to an existing
+*     Object. It also increments the Object's RefCount attribute to
+*     keep track of how many pointers have been issued.
+*
+*     Note that this function is NOT equivalent to an assignment
+*     statement, as in general the two pointers will not have the same
+*     value.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Original pointer to the Object.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astClone()
+f     AST_CLONE = INTEGER
+*        A duplicate pointer to the same Object.
+
+*  Applicability:
+*     Object
+*        This function applies to all Objects.
+
+*  Notes:
+*     - A null Object pointer (AST__NULL) will be returned if this
+c     function is invoked with the AST error status set, or if it
+f     function is invoked with STATUS set to an error value, or if it
+*     should fail for any reason.
+*--
+*/
+
+/* Check the global error status. */
+   if ( !astOK ) return NULL;
+
+/* Get a lock on the object's secondary mutex. This mutex guards access
+   to the "ref_count" and "locker" components of the AstObject structure. */
+   LOCK_SMUTEX(this);
+
+#ifdef MEM_DEBUG
+   {   int rc;
+       char buf[100];
+       rc = this->ref_count;
+       sprintf(buf,"cloned (refcnt: %d -> %d)", rc, rc+1 );
+       astMemoryUse( this, buf );
+   }
+#endif
+
+/* Increment the Object's reference count. */
+   this->ref_count++;
+
+/* Unlock the object's secondary mutex. */
+   UNLOCK_SMUTEX(this);
+
+/* Return a new pointer to the Object. */
+   return this;
+}
+
+AstObject *astCopy_( const AstObject *this, int *status ) {
+/*
+*++
+*  Name:
+c     astCopy
+f     AST_COPY
+
+*  Purpose:
+*     Copy an Object.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     AstObject *astCopy( const AstObject *this )
+f     RESULT = AST_COPY( THIS, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function creates a copy of an Object and returns a pointer
+*     to the resulting new Object. It makes a "deep" copy, which
+*     contains no references to any other Object (i.e. if the original
+*     Object contains references to other Objects, then the actual
+*     data are copied, not simply the references). This means that
+*     modifications may safely be made to the copy without indirectly
+*     affecting any other Object.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the Object to be copied.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astCopy()
+f     AST_COPY = INTEGER
+*        Pointer to the new Object.
+
+*  Applicability:
+*     Object
+*        This function applies to all Objects.
+
+*  Notes:
+*     - A null Object pointer (AST__NULL) will be returned if this
+c     function is invoked with the AST error status set, or if it
+f     function is invoked with STATUS set to an error value, or if it
+*     should fail for any reason.
+*--
+*/
+
+/* Local Variables: */
+   AstObject *new;               /* Pointer to new object */
+   AstObjectVtab *vtab;          /* Pointer to object vtab */
+   int i;                        /* Loop counter for copy constructors */
+
+/* Initiallise. */
+   new = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return new;
+
+/* Re-use cached memory, or allocate new memory using the size of the input
+   object, to store the output Object. */
+
+   vtab = this->vtab;
+   if( object_caching ){
+
+      if( vtab->nfree > 0 ) {
+         new = vtab->free_list[ --(vtab->nfree) ];
+         vtab->free_list[ vtab->nfree ] = NULL;
+      } else {
+         new = astMalloc( this->size );
+      }
+
+   } else {
+      new = astMalloc( this->size );
+   }
+
+   if ( astOK ) {
+
+/* Perform an initial byte-by-byte copy of the entire object
+   structure. */
+      (void) memcpy( (void *) new, (const void *) this, this->size );
+
+/* Initialise any components of the new Object structure that need to
+   differ from the input. */
+      new->check = Magic( new, new->size, status );
+      new->dynamic = 1;
+      new->ref_count = 1;
+      new->id = NULL;   /* ID attribute is not copied (but Ident is copied) */
+      new->proxy = NULL;
+
+/* Copy the persistent identifier string. */
+      if( this->ident ) {
+         new->ident = astStore( NULL, this->ident, strlen( this->ident ) + 1 );
+      }
+
+/* Create a new mutex for the new Object, and lock it for use by the
+   current thread. */
+#ifdef THREAD_SAFE
+      if( pthread_mutex_init( &(new->mutex1), NULL ) != 0 && astOK ) {
+         astError( AST__INTER, "astInitObject(%s): Failed to "
+                   "initialise POSIX mutex1 for the new Object.", status,
+                   vtab->class );
+      }
+      if( pthread_mutex_init( &(new->mutex2), NULL ) != 0 && astOK ) {
+         astError( AST__INTER, "astInitObject(%s): Failed to "
+                   "initialise POSIX mutex2 for the new Object.", status,
+                   vtab->class );
+      }
+      new->locker = -1;
+      new->globals = NULL;
+      (void) ManageLock( new, AST__LOCK, 0, NULL, status );
+#endif
+
+/* Loop to execute any copy constructors declared by derived classes. */
+      for ( i = 0; i < vtab->ncopy; i++ ) {
+
+/* Invoke each copy constructor in turn. */
+         (*vtab->copy[ i ])( this, new, status );
+
+/* If any copy constructor fails, work backwards through the
+   corresponding destructor functions, invoking each in turn to undo
+   the copy operations that have been completed so far. */
+         if ( !astOK ) {
+            for ( ; i >= 0; i-- ) {
+               (*vtab->delete[ i ])( new, status );
+            }
+
+/* Zero the entire new Object structure (to prevent accidental re-use
+   of any of its values after deletion). */
+            (void) memset( new, 0, new->size );
+
+/* Free the Object's memory and ensure that a NULL pointer will be
+   returned. */
+            new = astFree( new );
+
+/* Quit trying to copy the Object. */
+            break;
+         }
+      }
+   }
+
+/* If OK, increment the count of active objects. */
+   if ( astOK ) vtab->nobject++;
+
+/* Return a pointer to the new Object. */
+   return new;
+}
+
+AstObject *astDelete_( AstObject *this, int *status ) {
+/*
+*++
+*  Name:
+c     astDelete
+f     AST_DELETE
+
+*  Purpose:
+*     Delete an Object.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     AstObject *astDelete( AstObject *this )
+f     CALL AST_DELETE( THIS, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+c     This function deletes an Object, freeing all resources
+f     This routine deletes an Object, freeing all resources
+*     associated with it and rendering any remaining pointers to the
+*     Object invalid.
+*
+*     Note that deletion is unconditional, regardless of whether other
+*     pointers to the Object are still in use (possibly within other
+*     Objects). A safer approach is to defer deletion, until all
+c     references to an Object have expired, by using astBegin/astEnd
+c     (together with astClone and astAnnul if necessary).
+f     references to an Object have expired, by using AST_BEGIN/AST_END
+f     (together with AST_CLONE and AST_ANNUL if necessary).
+
+*  Parameters:
+c     this
+c        Pointer to the Object to be deleted.
+f     THIS = INTEGER (Given and Returned)
+f        Pointer to the Object to be deleted. A null pointer value
+f        (AST__NULL) is always returned.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+c  Returned Value:
+c     astDelete()
+c        A null Object pointer (AST__NULL) is always returned.
+c
+*  Applicability:
+*     Object
+c        This function applies to all Objects.
+f        This routine applies to all Objects.
+
+*  Notes:
+c     - This function attempts to execute even if the AST error status
+c     is set
+f     - This routine attempts to execute even if STATUS is set to an error
+f     value
+*     on entry, although no further error report will be
+*     made if it subsequently fails under these circumstances.
+*--
+*/
+
+/* Local Variables: */
+   AstObjectVtab *vtab;          /* Pointer to virtual function table */
+   int dynamic;                  /* Was memory allocated dynamically? */
+   int i;                        /* Loop counter for destructors */
+   int ifree;                    /* Index of next slot on free list */
+   int status_value;             /* AST error status value */
+   size_t size;                  /* Object size */
+
+/* Check the pointer to ensure it identifies a valid Object (this
+   generates an error if it doesn't). */
+   if ( !astIsAObject( this ) ) return NULL;
+
+/* Loop through all the destructors associated with the Object by derived
+   classes (working up the class hierarchy). */
+   for ( i = this->vtab->ndelete - 1; i >= 0; i-- ) {
+
+/* Invoke each destructor in turn. Attempt to continue even if destructors
+   fail. */
+      ( *this->vtab->delete[ i ] )( this, status );
+   }
+
+/* Free the ID strings. */
+   this->id = astFree( this->id );
+   this->ident = astFree( this->ident );
+
+/* Attempt to unlock the Object and destroy its mutexes. */
+#if defined(THREAD_SAFE)
+   (void) ManageLock( this, AST__UNLOCK, 0, NULL, status );
+   pthread_mutex_destroy( &(this->mutex1) );
+   pthread_mutex_destroy( &(this->mutex2) );
+#endif
+
+/* Save the virtual function table address and note if the Object's
+   memory was allocated dynamically. Also note its size. */
+   vtab = this->vtab;
+   dynamic = this->dynamic;
+   size = this->size;
+
+/* Zero the entire Object structure (to prevent accidental re-use of
+   any of its values after deletion). */
+   (void) memset( this, 0, size );
+
+/* If necessary, free the Object's memory. If object caching is switched
+   on, the memory is not in fact freed; it is merely placed onto the end
+   of the list of free memory blocks included in the virtual function table
+   of the AST class concerned. astGrow returns immediately if an error
+   has already occurred, so we need to reset the error status explicitly
+   before calling astGrow. */
+   if ( dynamic ) {
+      if( object_caching ) {
+         ifree = (vtab->nfree)++;
+
+         status_value = astStatus;
+         astClearStatus;
+         vtab->free_list = astGrow( vtab->free_list, vtab->nfree,
+                                    sizeof(AstObject *) );
+         astSetStatus( status_value );
+
+         if( vtab->free_list ) vtab->free_list[ ifree ] = this;
+      } else {
+         (void) astFree( this );
+      }
+   }
+
+/* Decrement the count of active Objects. */
+   vtab->nobject--;
+
+/* Always return NULL. */
+   return NULL;
+}
+
+static void Dump( AstObject *this, AstChannel *channel, int *status ) {
+/*
+*+
+*  Name:
+*     astDump
+
+*  Purpose:
+*     Write an Object to a Channel.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astDump( AstObject *this, AstChannel *channel )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function writes an Object to a Channel, appending it to any
+*     previous Objects written to that Channel.
+
+*  Parameters:
+*     this
+*        Pointer to the Object to be written.
+*     channel
+*        Pointer to the output Channel.
+*-
+*/
+
+/* Local Variables: */
+   AstObjectVtab *vtab;          /* Pointer to virtual function table */
+   const char *sval;             /* Pointer to string value */
+   int helpful;                  /* Helpful to show value even if not set? */
+   int idump;                    /* Loop counter for dump functions */
+   int ival;                     /* Attribute value */
+   int set;                      /* Attribute value set? */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Write an initial "Begin" item, giving the class name of the Object
+   being written. Also supply a pointer to the comment associated with
+   the most recently-declared dump function in the Object's virtual
+   function table. This should describe the class to which the Object
+   belongs (assuming it has correctly declared its dump function). */
+   astWriteBegin( channel, astGetClass( this ),
+                  this->vtab->dump_comment[ this->vtab->ndump - 1 ] );
+
+/* Write out instance variable information for the base Object
+   class. Accompany these with appropriate comment strings, possibly
+   depending on the values being written.*/
+
+/* In the case of attributes, we first use the appropriate (private)
+   Test...  member function to see if they are set. If so, we then use
+   the (private) Get... function to obtain the value to be written
+   out.
+
+   For attributes which are not set, we use the astGet... method to
+   obtain the value instead. This will supply a default value
+   (possibly provided by a derived class which over-rides this method)
+   which is more useful to a human reader as it corresponds to the
+   actual default attribute value.  Since "set" will be zero, these
+   values are for information only and will not be read back. */
+
+/* ID. */
+/* --- */
+   set = TestID( this, status );
+   sval = set ? GetID( this, status ) : astGetID( this );
+
+/* Don't show an un-set ID value if it is blank. */
+   helpful = ( sval && *sval );
+   astWriteString( channel, "ID", set, helpful, sval,
+                   "Object identification string" );
+
+/* Ident. */
+/* --- */
+   set = TestIdent( this, status );
+   sval = set ? GetIdent( this, status ) : astGetIdent( this );
+
+/* Don't show an un-set Ident value if it is blank. */
+   helpful = ( sval && *sval );
+   astWriteString( channel, "Ident", set, helpful, sval,
+                   "Permanent Object identification string" );
+
+/* UseDefs */
+/* ------- */
+   set = TestUseDefs( this, status );
+   ival = set ? GetUseDefs( this, status ) : astGetUseDefs( this );
+   astWriteInt( channel, "UseDfs", set, 0, ival,
+                ival ? "Default attribute values can be used" :
+                       "Default values cannot be used" );
+
+/* RefCnt. */
+/* ------- */
+   LOCK_SMUTEX(this);
+   ival = this->ref_count;
+   UNLOCK_SMUTEX(this);
+
+   astWriteInt( channel, "RefCnt", 0, 0, ival,
+                "Count of active Object pointers" );
+
+
+/* Nobj. */
+/* ----- */
+   vtab = this->vtab;
+   astWriteInt( channel, "Nobj", 0, 0, vtab->nobject,
+                "Count of active Objects in same class" );
+
+/* Terminate the information above with an "IsA" item for the base
+   Object class. */
+   astWriteIsA( channel, "Object", "AST Object" );
+
+/* Now loop to perform the same operation for each additional class
+   from which the Object inherits (the Object class itself does not
+   declare a dump function). Invoke the dump function for each class
+   in turn, working down the class hierarchy, to write out instance
+   variable information for that class. */
+   for ( idump = 0; idump < this->vtab->ndump; idump++ ) {
+      ( *this->vtab->dump[ idump ] )( this, channel, status );
+
+/* Terminate the output from all except the final dump function with
+   an appropriate "IsA" item describing the class whose data have just
+   been written. */
+      if ( idump != ( this->vtab->ndump - 1 ) ) {
+         astWriteIsA( channel, this->vtab->dump_class[ idump ],
+                      this->vtab->dump_comment[ idump ] );
+      }
+
+/* Quit looping if an error occurs. */
+      if ( !astOK ) break;
+   }
+
+/* Terminate the output from the final dump function with an "End"
+   item to match the initial "Begin" item. */
+   astWriteEnd( channel, astGetClass( this ) );
+}
+
+static void EmptyObjectCache( int *status ){
+/*
+*  Name:
+*     EmptyObjectCache
+
+*  Purpose:
+*     Free all memory blocks currently on the free list of any class.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     EmptyObjectCache( int *status )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function empties the cache of Object memory by freeing all
+*     memory blocks on the free_list of all classes.
+
+*  Parameters:
+*     status
+*        Pointer to the inherited status variable.
+
+*  Notes:
+*     -  This function attempts to execute even if an error has occurred.
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS    /* Thread-specific global data */
+   int iblock;           /* Index of next entry in free list */
+   int itab;             /* Index of next virtual function table */
+   AstObjectVtab *vtab;  /* Pointer to next virtual function table */
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Loop round all the virtual function tables which are known about. */
+   for( itab = 0; itab < nvtab; itab++ ) {
+      vtab = known_vtabs[ itab ];
+
+/* Free all memory blocks stored on the free list for this class. */
+      for( iblock = 0; iblock < vtab->nfree; iblock++ ) {
+         (vtab->free_list)[ iblock ] = astFree( (vtab->free_list)[ iblock ] );
+      }
+
+/* Free the memory used to hold the free list, and indicate it has zero
+   length. */
+      vtab->free_list = astFree( vtab->free_list );
+      vtab->nfree = 0;
+   }
+}
+
+static void EnvSet( AstObject *this, int *status ) {
+/*
+*+
+*  Name:
+*     astEnvSet
+
+*  Purpose:
+*     Set default values for an Object's attributes.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astEnvSet( AstObject *this )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function assigns a set of attribute values for an Object,
+*     the attributes and their values being specified by means of an
+*     environment variable of the form "<CLASSNAME>_OPTIONS" that has
+*     a value of the form:
+*
+*        "attribute1 = value1, attribute2 = value2, ... "
+*
+*     Here, "attribute" specifies an attribute name and the value to
+*     the right of each "=" sign should be a suitable textual
+*     representation of the value to be assigned to that
+*     attribute. This will be interpreted according to the attribute's
+*     data type.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+
+*  Notes:
+*     - See astVSet for details of how the setting strings are
+*     interpreted.
+*-
+*/
+
+/* Local Variables: */
+   char varname[ 100 ];
+   const char *attrs = NULL;
+   const char *class = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get the string holding default attribute values for the class of the
+   supplied object. This string is held in the class virtual function
+   table. */
+   attrs = this->vtab->defaults;
+
+/* If this is the first time the defaults have been requested, get the
+   list of defaults from the environment variable "<CLASSNAME>_OPTIONS"
+   and store in the virtual function table. */
+   if( !attrs ) {
+
+/* Get the class name. */
+      class = astGetClass( this );
+
+/* Form the upper-case name of the environment variable. */
+      if( class ) {
+         sprintf( varname, "%s_OPTIONS", class );
+         astChrCase( NULL, varname, 1, sizeof( varname ) );
+
+/* Get the value of the environment variable. */
+         attrs = getenv( varname );
+
+/* If no defaults were specified store the string "None". */
+         if( ! attrs ) attrs = "None";
+
+/* Store a copy in the virtual function table. */
+         astBeginPM;
+         this->vtab->defaults = astStore( NULL, attrs, strlen( attrs ) + 1 );
+         astEndPM;
+      }
+   }
+
+/* If any defaults were specified, set the corresponding attributes. */
+   if( attrs && strcmp( attrs, "None" ) ) astSet( this, attrs, status );
+
+}
+
+static int Equal( AstObject *this, AstObject *that, int *status ){
+/*
+*+
+*  Name:
+*     astEqual
+
+*  Purpose:
+*     Check equality of two AST Objects.
+
+*  Type:
+*     Public (but undocumented) function.
+
+*  Synopsis:
+*     #include "object.h"
+*     int astEqual( AstObject *this, AstObject *this )
+
+*  Class Membership:
+*     Object virtual function.
+
+*  Description:
+*     This function returns non-zero if the two pointers identify
+*     equivalent objects.
+
+*  Parameters:
+*     this
+*        Pointer to the first Object.
+*     that
+*        Pointer to the second Object.
+
+*  Returned Value:
+*     Non-zero if the objects are equivalent.
+
+*  Notes:
+*    - This function is available in the public interface even though it is
+*    documented as protected. This is because it is difficult to document
+*    precisely which aspects of two Objects must be equal in order for this
+*    function to return a non-zero value. Each class of Object supplies
+*    its own Equal method that tests which-ever attributes the class
+*    considers to be significiant.
+*    - The implementation of this function provided by the base Object
+*    class simply compares the class names and the structure size.
+*    Sub-classes should override this method to provide more appropriate tests.
+*    - Zero is returned if an error has already occurred, or if
+*    this function should fail for any reason.
+
+*-
+*/
+
+/* Local Variables: */
+   int result;
+
+/* Check inherited status */
+   if( !astOK ) return 0;
+
+/* Objects are equivalent if they are the same object. */
+   if( this == that ) {
+      result = 1;
+
+/* Otherwise, check the structure size and class names */
+   } else {
+      result = ( this->size == that->size &&
+                 !strcmp( astGetClass( this ), astGetClass( that ) ) );
+   }
+
+   return result;
+}
+
+static const char *Get( AstObject *this, const char *attrib, int *status ) {
+/*
+*  Name:
+*     Get
+
+*  Purpose:
+*     Get the value of a specified attribute for an Object.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     const char *Get( AstObject *this, const char *attrib, int *status )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function returns a pointer to the value of a specified
+*     attribute for an Object, formatted as a character string. It is
+*     mainly a wrap-up used internally for invoking the astGetAttrib
+*     method. It converts the attribute name to lower case and removes
+*     white space before invoking the method. This saves derived
+*     classes that over-ride the astGetAttrib method from having to do
+*     this themselves.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+*     attrib
+*        Pointer to a null-terminated string containing the name of
+*        the attribute whose value is required. This may contain mixed
+*        case and white space, but should not be composed entirely of
+*        white space.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Returned Value:
+*     - Pointer to a null-terminated string containing the attribute
+*     value.
+
+*  Notes:
+*     - The returned string pointer may point at memory allocated
+*     within the Object, or at static memory. The contents of the
+*     string may be over-written or the pointer may become invalid
+*     following a further invocation of the same function or any
+*     modification of the Object. A copy of the string should
+*     therefore be made if necessary.
+*     - A NULL pointer will be returned if this function is invoked
+*     with the global error status set, or if it should fail for any
+*     reason.
+*/
+
+/* Local Variables: */
+   char *buff;                   /* Pointer to local string buffer */
+   const char *result;           /* Pointer value to return */
+   int i;                        /* Loop counter for characters */
+   int j;                        /* Non-blank character count */
+
+/* Initialise. */
+   result = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Allocate a local buffer long enough to hold the attribute name
+   string. */
+   buff = astMalloc( strlen( attrib ) + (size_t) 1 );
+   if ( astOK ) {
+
+/* Copy the attribute name characters into the buffer, omitting all
+   white space and converting to lower case. */
+      for ( i = j = 0; attrib[ i ]; i++ ) {
+         if ( !isspace( attrib[ i ] ) ) buff[ j++ ] = tolower( attrib[ i ] );
+      }
+
+/* Terminate the copied string. */
+      buff[ j ] = '\0';
+
+/* If no characters were copied, the attribute name was blank, so
+   report an error. */
+      if ( !j ) {
+         if( astOK ) astError( AST__BADAT, "astGet(%s): A blank attribute "
+                               "name was given.", status, astGetClass( this ) );
+
+/* Of OK, invoke astGetAttrib to obtain a pointer to the attribute
+   value formatted as a character string. */
+      } else {
+         result = astGetAttrib( this, buff );
+
+/* If required, strip out graphical escape sequences. */
+         if( !astEscapes( -1 ) ) result = astStripEscapes( result );
+      }
+   }
+
+/* Free the local string buffer. */
+   buff = astFree( buff );
+
+/* If an error occurred, clear the result value. */
+   if ( !astOK ) result = NULL;
+
+/* Return the result. */
+   return result;
+}
+
+static const char *GetAttrib( AstObject *this, const char *attrib, int *status ) {
+/*
+*+
+*  Name:
+*     astGetAttrib
+
+*  Purpose:
+*     Get the value of a specified attribute for an Object.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "object.h"
+*     const char *astGetAttrib( AstObject *this, const char *attrib )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns a pointer to the value of a specified
+*     attribute for an Object, formatted as a character string.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+*     attrib
+*        Pointer to a null-terminated string containing the name of
+*        the attribute whose value is required. This name should be in
+*        lower case, with all white space removed.
+
+*  Returned Value:
+*     - Pointer to a null-terminated string containing the attribute
+*     value.
+
+*  Notes:
+*     - The returned string pointer may point at memory allocated
+*     within the Object, or at static memory. The contents of the
+*     string may be over-written or the pointer may become invalid
+*     following a further invocation of the same function or any
+*     modification of the Object. A copy of the string should
+*     therefore be made if necessary.
+*     - A NULL pointer will be returned if this function is invoked
+*     with the global error status set, or if it should fail for any
+*     reason.
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   const char *result;           /* Pointer value to return */
+   int nobject;                  /* Nobject attribute value */
+   int objsize;                  /* ObjSize attribute value */
+   int ref_count;                /* RefCount attribute value */
+   int usedefs;                  /* UseDefs attribute value */
+
+/* Initialise. */
+   result = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* Compare "attrib" with each recognised attribute name in turn,
+   obtaining the value of the required attribute. If necessary, write
+   the value into "getattrib_buff" as a null-terminated string in an
+   appropriate format.  Set "result" to point at the result string. */
+
+/* Class. */
+/* ------ */
+   if ( !strcmp( attrib, "class" ) ) {
+      result = astGetClass( this );
+
+/* ID. */
+/* --- */
+   } else if ( !strcmp( attrib, "id" ) ) {
+      result = astGetID( this );
+
+/* Ident. */
+/* ------ */
+   } else if ( !strcmp( attrib, "ident" ) ) {
+      result = astGetIdent( this );
+
+/* UseDefs */
+/* ------- */
+   } else if ( !strcmp( attrib, "usedefs" ) ) {
+      usedefs = astGetUseDefs( this );
+      if ( astOK ) {
+         (void) sprintf( getattrib_buff, "%d", usedefs );
+         result = getattrib_buff;
+      }
+
+/* Nobject. */
+/* -------- */
+   } else if ( !strcmp( attrib, "nobject" ) ) {
+      nobject = astGetNobject( this );
+      if ( astOK ) {
+         (void) sprintf( getattrib_buff, "%d", nobject );
+         result = getattrib_buff;
+      }
+
+/* ObjSize */
+/* ------- */
+   } else if ( !strcmp( attrib, "objsize" ) ) {
+      objsize = astGetObjSize( this );
+      if ( astOK ) {
+         (void) sprintf( getattrib_buff, "%d", objsize );
+         result = getattrib_buff;
+      }
+
+/* RefCount. */
+/* --------- */
+   } else if ( !strcmp( attrib, "refcount" ) ) {
+      ref_count = astGetRefCount( this );
+      if ( astOK ) {
+         (void) sprintf( getattrib_buff, "%d", ref_count );
+         result = getattrib_buff;
+      }
+
+/* If the attribute name was not recognised, then report an error. */
+   } else if( astOK ){
+      astError( AST__BADAT, "astGet: The %s given does not have an attribute "
+                "called \"%s\".", status, astGetClass( this ), attrib );
+   }
+
+/* Return the result. */
+   return result;
+}
+
+const char *astGetClass_( const AstObject *this, int *status ) {
+/*
+*+
+*  Name:
+*     astGetClass
+
+*  Purpose:
+*     Obtain the value of the Class attribute for an Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     const char *astGetClass( const AstObject *this )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns a pointer to the Class string for an
+*     Object. This contains the name of the class which created the
+*     Object.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+
+*  Returned Value:
+*     Pointer to a string containing the class name.
+
+*  Notes:
+*     - This function does not check the global error status before
+*     executing.  This is to allow it to be used to obtain class names
+*     for inclusion in error messages.
+*     - A pointer to an explanatory string will be returned if this
+*     function is given a pointer which does not identify an Object.
+*-
+*/
+
+/* Local Variables: */
+   const char *name;             /* Pointer to returned string */
+
+/* First check if the Object pointer supplied is NULL, and set the
+   returned pointer accordingly. */
+   if ( !this ) {
+      name = "<NULL>";
+
+/* Also check if the supposed Object has the correct "magic number" in
+   its check field. If not, it is not an Object. */
+   } else if ( this->check != Magic( this, this->size, status ) ) {
+      name = "<unknown>";
+
+/* If OK, obtain a pointer to the class name from the Object's virtual
+   function table. */
+   } else {
+      name = this->vtab->class;
+   }
+
+/* Return the result. */
+   return name;
+}
+
+int astGetNobject_( const AstObject *this, int *status ) {
+/*
+*+
+*  Name:
+*     astGetNobject
+
+*  Purpose:
+*     Obtain the value of the Nobject attribute for an Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     int astGetNobject( const AstObject *this )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns the value of the Nobject attribute for an
+*     Object. This is a count of the number of active Objects in the
+*     same class as the Object supplied. This count does not include
+*     Objects in derived classes.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+
+*  Returned Value:
+*     The number of active Objects.
+
+*  Notes:
+*     - A value of zero will be returned if this function is invoked
+*     with the global error status set, or if it should fail for any
+*     reason.
+*-
+*/
+
+/* Check the global error status. */
+   if ( !astOK ) return 0;
+
+/* Return the active object count. */
+   return this->vtab->nobject;
+}
+
+static int GetObjSize( AstObject *this, int *status ) {
+/*
+*+
+*  Name:
+*     astGetObjSize
+
+*  Purpose:
+*     Determine the in-memory size of the Object.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "object.h"
+*     int astGetObjSize( AstObject *this )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns the in-memory size of an Object.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+
+*  Returned Value:
+*     The Object size, in bytes.
+
+*  Notes:
+*     - A value of zero will be returned if this function is invoked
+*     with the global error status set, or if it should fail for any
+*     reason.
+*-
+*/
+
+/* Check the global error status. */
+   if ( !astOK ) return 0;
+
+/* Return the object size. */
+   return this->size;
+}
+
+void *astGetProxy_( AstObject *this, int *status ) {
+/*
+*+
+*  Name:
+*     astGetProxy
+
+*  Purpose:
+*     Get a pointer to the foreign language proxy used to represent a
+*     given AST Object.
+
+*  Type:
+*     Undocumented public function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void *astGetProxy( AstObject *this )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns any pointer stored previously in the AST
+*     Object using astSetProxy. If no such pointer has been stored, a
+*     NULL pointer is returned.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+
+*  Returned Value:
+*     Pointer to the proxy object, or NULL.
+
+*  Notes:
+*     - This function is public, but is currently undocumented since it
+*     is only of interest to people writing AST interfaces for other
+*     languages.
+*     - This function attempts to execute even if the AST error status
+*     is set on entry, although no further error report will be made
+*     if it subsequently fails under these circumstances.
+*-
+*/
+   return this ? this->proxy : NULL;
+}
+
+int astGetRefCount_( AstObject *this, int *status ) {
+/*
+*+
+*  Name:
+*     astGetRefCount
+
+*  Purpose:
+*     Obtain the value of the RefCount attribute for an Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     int astGetRefCount( const AstObject *this )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns the value of the read-only RefCount
+*     attribute for an Object. This is a "reference count" of the
+*     number of active pointers to it, as accounted for by astClone
+*     and astAnnul (plus the pointer issued when it was created).  If
+*     the reference count for an Object falls to zero when astAnnul is
+*     invoked, the object will be deleted.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+
+*  Returned Value:
+*     The reference count.
+
+*  Notes:
+*     - A value of zero will be returned if this function is invoked
+*     with the global error status set, or if it should fail for any
+*     reason.
+*-
+*/
+
+/* Local Variables; */
+   int result;          /* Returned value */
+
+/* Check the global error status. */
+   if ( !astOK ) return 0;
+
+/* Get a lock on the object's secondary mutex. This mutex guards access
+   to the "ref_count" and "locker" components of the AstObject structure. */
+   LOCK_SMUTEX(this);
+
+/* Get the reference count. */
+   result = this->ref_count;
+
+/* Unlock the object's secondary mutex. */
+   UNLOCK_SMUTEX(this);
+
+/* Return the result. */
+   return result;
+}
+
+/*
+*++
+*  Name:
+c     astGet<X>
+f     AST_GET<X>
+
+*  Purpose:
+*     Get an attribute value for an Object.
+
+*  Type:
+*     Public functions.
+
+*  Synopsis:
+c     #include "object.h"
+c     <X>type astGet<X>( AstObject *this, const char *attrib )
+f     RESULT = AST_GET<X>( THIS, ATTRIB, STATUS )
+
+*  Class Membership:
+*     Object methods.
+
+*  Description:
+*     This is a family of functions which return a specified attribute
+*     value for an Object using one of several different data
+*     types. The type is selected by replacing <X> in the function name
+c     by C, D, F, I or L, to obtain a result in const char* (i.e. string),
+c     double, float, int, or long format, respectively.
+f     by C, D, I, L or R, to obtain a result in Character, Double
+f     precision, Integer, Logical or Real format, respectively.
+*
+*     If possible, the attribute value is converted to the type you
+*     request. If conversion is not possible, an error will result.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the Object.
+c     attrib
+f     ATTRIB = CHARACTER * ( * ) (Given)
+c        Pointer to a null-terminated string containing the name of
+c        the attribute whose value is required.
+f        A character string containing the name of the attribute whose
+f        value is required.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astGet<X>()
+f     AST_GET<X> = <X>type
+c        The attribute value, in the data type corresponding to <X> (or,
+c        in the case of astGetC, a pointer to a constant null-terminated
+c        character string containing this value).
+f        The attribute value, in the data type corresponding to <X>.
+
+*  Applicability:
+*     Object
+*        These functions apply to all Objects.
+
+*  Examples:
+c     printf( "RefCount = %d\n", astGetI( z, "RefCount" ) );
+c        Prints the RefCount attribute value for Object "z" as an int.
+c     title = astGetC( axis, "Title" );
+c        Obtains a pointer to a null-terminated character string containing
+c        the Title attribute of Object "axis".
+f     WRITE( *, '('' RefCount = '', A10 )' ) AST_GETC( Z, 'RefCount', STATUS )
+f        Prints the RefCount attribute value for Object Z as a character
+f        string.
+f     NAXES = AST_GETI( FRAME, 'Naxes', STATUS )
+f        Obtains the value of the Naxes attribute for Object FRAME as an
+f        integer.
+
+*  Notes:
+*     - Attribute names are not case sensitive and may be surrounded
+*     by white space.
+*     - An appropriate "null" value will be returned if this function
+c     is invoked with the AST error status set, or if it should
+f     is invoked with STATUS set to an error value, or if it should
+*     fail for any reason. This null value is zero for numeric
+c     values and NULL for pointer values.
+f     values, .FALSE. for logical values, and blank for character values.
+f     - Numerical attribute values of zero translate to logical value
+f     .FALSE. and all other numerical values translate to .TRUE..
+c     - The pointer returned by astGetC is guaranteed to remain valid
+c     and the string to which it points will not be over-written for a
+c     total of 50 successive invocations of this function. After this,
+c     the memory containing the string may be re-used, so a copy of
+c     the string should be made if it is needed for longer than this.
+*--
+*/
+
+/* Define a macro that expands to implement the astGetX_ member
+   functions required. The arguments to this macro are:
+
+      code
+         The character that appears at the end of the function name.
+      type
+         The C type of the function return value.
+      format
+         A quoted string containing a astSscanf format specifier that
+         will read the attribute value into a variable of the required
+         data type. This format should transfer 1 astSscanf value.
+*/
+#define MAKE_GETX(code,type,format) \
+type astGet##code##_( AstObject *this, const char *attrib, int *status ) { \
+\
+/* Local Variables: */ \
+   const char *str;              /* Pointer to string attribute value */ \
+   int nc;                       /* Number of characters read from string */ \
+   int nval;                     /* Number of values read from string */ \
+   type result;                  /* Value to return */ \
+   type value;                   /* Converted value */ \
+\
+/* Initialise. */ \
+   result = (type) 0; \
+\
+/* Check the global error status. */ \
+   if ( !astOK ) return result; \
+\
+/* Obtain the attribute value as a string. */ \
+   str = Get( this, attrib, status ); \
+   if ( astOK ) { \
+\
+/* Read the value from the string, ignoring surrounding white \
+   space. */ \
+      nc = 0; \
+      nval = astSscanf( str, " " format " %n", &value, &nc ); \
+\
+/* Check that the number of values read was 1 and that all the \
+   string's characters were consumed. If so, use the result. */ \
+      if ( ( nval == 1 ) && ( nc >= (int) strlen( str ) ) ) { \
+         result = value; \
+\
+/* If the read was unsuccessful, report an error. */ \
+      } else if( astOK ) { \
+         astError( AST__ATGER, "astGet" #code "(%s): The attribute " \
+                   "value \"%s=%s\" cannot be read using the requested data " \
+                   "type.", status,astGetClass( this ), attrib, str ); \
+      } \
+   } \
+\
+/* Return the result. */ \
+   return result; \
+}
+
+/* Use this macro to create all the GetX_ private member functions,
+   except SetC (which is handled separately). */
+MAKE_GETX(D,double,"%lf")
+MAKE_GETX(F,float,"%f")
+MAKE_GETX(I,int,"%d")
+MAKE_GETX(L,long,"%ld")
+
+/* Handle GetC separately because memory must be allocated to hold the
+   returned character values. */
+const char *astGetC_( AstObject *this, const char *attrib, int *status ) {
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   const char *result;           /* Pointer value to return */
+   const char *value;            /* Pointer to attribute value */
+   int i;                        /* Loop count */
+
+/* Initialise. */
+   result = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* If the "strings" array has not been initialised, fill it with
+   NULL pointers. */
+   if ( !astgetc_init ) {
+      astgetc_init = 1;
+      for ( i = 0; i < AST__ASTGETC_MAX_STRINGS; i++ ) astgetc_strings[ i ] = NULL;
+   }
+
+/* Obtain a pointer to the required attribute value, formatted as a
+   character string. */
+   value = Get( this, attrib, status );
+
+/* Use a null string if a NULL pointer was returned by Get. */
+   if( !value ) value = "";
+
+/* If OK, store a copy of the resulting string in dynamically
+   allocated memory, putting a pointer to the copy into the next
+   element of the "astgetc_strings" array.  (This process also de-allocates
+   any previously allocated memory pointed at by this "strings"
+   element, so the earlier string is effectively replaced by the new
+   one.) */
+   if ( astOK ) {
+
+      astBeginPM;
+      astgetc_strings[ astgetc_istr ] = astStore( astgetc_strings[ astgetc_istr ],
+                                             value, strlen( value ) + (size_t) 1 );
+      astEndPM;
+
+/* If OK, return a pointer to the copy and increment "astgetc_istr" to use the
+   next element of "astgetc_strings" on the next invocation. Recycle
+   "astgetc_istr" to zero when all elements have been used. */
+      if ( astOK ) {
+         result = astgetc_strings[ astgetc_istr++ ];
+         if ( astgetc_istr == ( AST__ASTGETC_MAX_STRINGS - 1 ) ) astgetc_istr = 0;
+      }
+   }
+
+/* Return the result. */
+   return result;
+
+}
+
+static int HasAttribute( AstObject *this, const char *attrib, int *status ) {
+/*
+*++
+*  Name:
+c     astHasAttribute
+f     AST_HASATTRIBUTE
+
+*  Purpose:
+*     Test if an Object has a named attribute.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     int astHasAttribute( AstObject *this, const char *attrib )
+f     RESULT = AST_HASATTRIBUTE( THIS, ATTRIB, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+c     This function returns a boolean result (0 or 1) to indicate
+f     This function returns a logical result to indicate
+*     whether the supplied Object has an attribute with the supplied name.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the first Object.
+c     attrib
+f     ATTRIB = INTEGER (Given)
+c        Pointer to a string holding the
+f        The
+*        name of the attribute to be tested.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astHasAttribute()
+c        One if the Object has the named attribute, otherwise zero.
+f     AST_SAME = LOGICAL
+f        .TRUE. if the Object has the named attribute, otherwise
+f        .FALSE.
+
+*  Applicability:
+*     Object
+c        This function applies to all Objects.
+f        This routine applies to all Objects.
+
+*  Notes:
+c     - A value of zero will be returned if this function is invoked
+c     with the AST error status set, or if it should fail for any reason.
+f     - A value of .FALSE. will be returned if this function is invoked
+f     with STATUS set to an error value, or if it should fail for any reason.
+*--
+*/
+
+/* Local Variables: */
+   int oldrep;           /* Original AST error reporting flag */
+   int result;           /* Returned value */
+
+/* Check the global error status. */
+   if ( !astOK ) return 0;
+
+/* Temporarily switch off error reporting. */
+   oldrep = astReporting( 0 );
+
+/* Attempt to get a value for the specified attribute. */
+   (void) Get( this, attrib, status );
+
+/* An error will have been reported if the object does not have the
+   requested attribute. Set the result and clear the error status. */
+   if( !astOK ) {
+      result = 0;
+      astClearStatus;
+   } else {
+      result = 1;
+   }
+
+/* Re-instate the original error reporting flag. */
+   (void) astReporting( oldrep );
+
+/* Return the result. */
+   return result;
+}
+
+static unsigned long Magic( const AstObject *this, size_t size, int *status ) {
+/*
+*  Name:
+*     Magic
+
+*  Purpose:
+*     Generate a "magic number" for an Object.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     unsigned long Magic( const AstObject *this, size_t size, int *status )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function generates a "magic number" which is a function of an Object
+*     pointer (address) and an Object size. This number may be stored in an
+*     Object to allow it to be recognised as a valid Object by other routines
+*     and to provide security against argument passing errors, etc.
+
+*  Parameters:
+*     this
+*        Pointer to an Object.
+*     size
+*        The Object size.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Returned Value:
+*     The magic number.
+
+*  Notes:
+*     -  This function does not perform any error checking.
+*/
+
+/* Form the bit-wise exclusive OR between the Object address and the Object
+   size, then add 2 and invert the bits. Return the result as an unsigned
+   long integer. */
+   return ~( ( ( (unsigned long) this ) ^ ( (unsigned long) size ) ) +
+             ( (unsigned long) 2 ) );
+}
+
+#if defined(THREAD_SAFE)
+static int ManageLock( AstObject *this, int mode, int extra,
+                       AstObject **fail, int *status ) {
+/*
+*+
+*  Name:
+*     astManageLock
+
+*  Purpose:
+*     Manage the thread lock on an Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     int astManageLock( AstObject *this, int mode, int extra,
+*                        AstObject **fail )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function manages the thread lock on the supplied Object. The
+*     lock can be locked, unlocked or checked by this function as
+*     deteremined by parameter "mode". See astLock for details of the way
+*     these locks are used.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+*     mode
+*        An integer flag indicating what the function should do:
+*
+*        AST__LOCK: Lock the Object for exclusive use by the calling
+*        thread. The "extra" value indicates what should be done if the
+*        Object is already locked (wait or report an error - see astLock).
+*
+*        AST__UNLOCK: Unlock the Object for use by other threads.
+*
+*        AST__CHECKLOCK: Check that the object is locked for use by the
+*        calling thread.
+*     extra
+*        Extra mode-specific information.
+*     fail
+*        If a non-zero function value is returned, a pointer to the
+*        Object that caused the failure is returned at "*fail". This may
+*        be "this" or it may be an Object contained within "this". Note,
+*        the Object's reference count is not incremented, and so the
+*        returned pointer should not be annulled. A NULL pointer is
+*        returned if this function returns a value of zero.
+
+*  Returned Value:
+*     A status value:
+*        0 - Success.
+*        1 - Could not lock or unlock the object because it was already
+*            locked by another thread.
+*        2 - Failed to lock a POSIX mutex
+*        3 - Failed to unlock a POSIX mutex
+*        4 - Bad "mode" value supplied.
+*        5 - Check failed - object is locked by a different thread
+*        6 - Check failed - object is unlocked
+*
+
+*  Notes:
+*     - This function attempts to execute even if an error has already
+*     occurred.
+
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   int result;                   /* Returned value */
+
+/* Initialise */
+   result = 0;
+   if( fail ) *fail = NULL;
+
+/* Check the supplied point is not NULL. */
+   if( ! this ) return result;
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Get a lock on the object's secondary mutex. This gives us exclusive
+   access to the "locker" (and "ref_count") component in the AstObject
+   structure. All other components in the structure are guarded by the
+   primary mutex (this->mutex1). */
+   if( LOCK_SMUTEX(this) ) {
+      result = 2;
+
+/* If the secondary mutex was locked succesfully, first deal with cases
+   where the caller wants to lock the Object for exclusive use by the
+   calling thread. */
+   } else if( mode == AST__LOCK ) {
+
+/* If the Object is not currently locked, lock the Object primary mutex
+   and record the identity of the calling thread in the Object. */
+      if( this->locker == -1 ) {
+         if( LOCK_PMUTEX(this) ) result = 2;
+         this->locker = AST__THREAD_ID;
+         this->globals = AST__GLOBALS;
+         ChangeThreadVtab( this, status );
+
+/* If the Object is already locked by the calling thread, do nothing. */
+      } else if( this->locker == AST__THREAD_ID ) {
+
+/* If the object is locked by a different thread, and the caller is
+   willing to wait, attempt to lock the Object primary mutex. This will
+   cause the calling thread to block until the Object is release by the
+   thread that currently has it locked. Then store the identity of the
+   calling thread (the new lock owner). We first need to release the
+   secondary mutex so that the other thread can modify the "locker"
+   component in the AstObject structure when it releases the Object
+   (using this function). We then re-lock the secondary mutex so this
+   thread can change the "locker" component safely. */
+      } else if( extra ) {
+         if( UNLOCK_SMUTEX(this) ) {
+            result = 3;
+         } else if( LOCK_PMUTEX(this) ) {
+            result = 2;
+         } else if( LOCK_SMUTEX(this) ) {
+            result = 2;
+         }
+         this->locker = AST__THREAD_ID;
+         this->globals = AST__GLOBALS;
+         ChangeThreadVtab( this, status );
+
+/* If the caller does not want to wait until the Object is available,
+   return a status of 1. */
+      } else {
+         result = 1;
+      }
+
+/* Unlock the Object for use by other threads. */
+   } else if( mode == AST__UNLOCK ) {
+
+/* Do nothing if the Object is currently unlocked. */
+      if( this->locker == -1 ) {
+
+/* If the object is currently locked by the calling thread, clear the
+   identity of the thread that owns the lock and unlock the primary
+   mutex. */
+      } else if( this->locker == AST__THREAD_ID ) {
+         this->locker = -1;
+         this->globals = NULL;
+         if( UNLOCK_PMUTEX(this) ) result = 3;
+
+/* Return an error status value if the Object is locked by another
+   thread. */
+      } else {
+         result = 1;
+      }
+
+/* Check the Object is locked by the calling thread. Return a status of 1 if
+   not. */
+   } else if( mode == AST__CHECKLOCK ) {
+      if( this->locker == -1 ) {
+         result = 6;
+      } else if( this->locker != AST__THREAD_ID ) {
+         result = 5;
+      }
+
+/* Return a status of 4 for any other modes. */
+   } else {
+      result = 4;
+   }
+
+/* Unlock the secondary mutex so that other threads can access the "locker"
+   component in the Object to see if it is locked. */
+   if( UNLOCK_SMUTEX(this) ) result = 3;
+
+/* If the operation failed, return a pointer to the failed object. */
+   if( result && fail ) *fail = this;
+
+/* Return the status value */
+   return result;
+}
+#endif
+
+char *astToString_( AstObject *this, int *status ) {
+/*
+c++
+*  Name:
+*     astToString
+
+*  Purpose:
+*     Create an in-memory serialisation of an Object
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+*     #include "object.h"
+*     char *astToString( AstObject *this )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns a string holding a minimal textual
+*     serialisation of the supplied AST Object. The Object can re
+*     re-created from the serialisation using astFromString.
+
+*  Parameters:
+*     this
+*        Pointer to the Object to be serialised.
+
+*  Returned Value:
+*     astToString()
+*        Pointer to dynamically allocated memory holding the
+*        serialisation, or NULL if an error occurs. The pointer
+*        should be freed when no longer needed using astFree.
+
+c--
+*/
+
+/* Local Variables: */
+   StringData data;              /* Data passed to the sink function */
+   AstChannel *channel;          /* Pointer to output Channel */
+
+/* Check the global error status. */
+   if ( !astOK ) return NULL;
+
+/* Create a Channel which will write to an expanding dynamically
+   allocated memory buffer. Set Channel attributes to exclude all
+   non-essential characters. */
+   channel = astChannel( NULL, ToStringSink, "Comment=0,Full=-1,Indent=0",
+                         status );
+
+/* Initialise the data structure used to communicate with the sink
+   function, and store a pointer to it in the Channel. */
+   data.ptr = NULL;
+   data.buff = NULL;
+   data.len = 0;
+   astPutChannelData( channel, &data );
+
+/* Write the Object to the Channel. */
+   astWrite( channel, this );
+
+/* Annul the Channel pointer. */
+   channel = astAnnul( channel );
+
+/* Free the returned string if an error has occurred. */
+   if( !astOK ) data.ptr = astFree( data.ptr );
+
+/* Return the pointer. */
+   return data.ptr;
+}
+
+static void ToStringSink( const char *text ){
+/*
+*  Name:
+*     ToStringSink
+
+*  Purpose:
+*     A Channel sink function for use by the astToString method.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*      ToStringSink( const char *text )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function appends the supplied line of text to the end of a
+*     dynamically growing memory block.
+
+*  Parameters:
+*     text
+*        Pointer to the null-terminated line of text to be stored.
+
+*/
+
+/* Local Variables: */
+   StringData *data;     /* Data passed to the sink function */
+   int *status;          /* Pointer to local status value */
+   int status_value;     /* Local status value */
+
+/* Set up the local status */
+   status_value = 0;
+   status = &status_value;
+
+/* Get a pointer to the structure holding the current memory pointer and
+   the length of the currently allocated memory. */
+   data = astChannelData;
+
+/* Append the supplied text to the end of the string, and update the
+   string length. */
+   data->ptr = astAppendString( data->ptr, &(data->len), text );
+
+/* Append a newline character to the end of the string, and update the
+   string length. */
+   data->ptr = astAppendString( data->ptr, &(data->len), "\n" );
+}
+
+void astSet_( void *this_void, const char *settings, int *status, ... ) {
+/*
+*++
+*  Name:
+c     astSet
+f     AST_SET
+
+*  Purpose:
+*     Set attribute values for an Object.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     void astSet( AstObject *this, const char *settings, ... )
+f     CALL AST_SET( THIS, SETTINGS, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+c     This function assigns a set of attribute values to an Object,
+f     This routine assigns a set of attribute values to an Object,
+*     over-riding any previous values. The attributes and their new
+*     values are specified via a character string, which should
+*     contain a comma-separated list of the form:
+*
+*        "attribute_1 = value_1, attribute_2 = value_2, ... "
+*
+*     where "attribute_n" specifies an attribute name, and the value
+*     to the right of each "=" sign should be a suitable textual
+*     representation of the value to be assigned. This value will be
+*     interpreted according to the attribute's data type.
+c
+c     The string supplied may also contain "printf"-style format
+c     specifiers, identified by "%" signs in the usual way. If
+c     present, these will be substituted by values supplied as
+c     additional optional arguments (using the normal "printf" rules)
+c     before the string is used.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the Object.
+c     settings
+f     SETTINGS = CHARACTER * ( * ) (Given)
+c        Pointer to a null-terminated character string containing a
+c        comma-separated list of attribute settings in the form described
+c        above.
+f        A character string containing a comma-separated list of
+f        attribute settings in the form described above.
+c     ...
+c        Optional additional arguments which supply values to be
+c        substituted for any "printf"-style format specifiers that
+c        appear in the "settings" string.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Applicability:
+*     Object
+c        This function applies to all Objects.
+f        This routine applies to all Objects.
+
+*  Examples:
+c     astSet( map, "Report = 1, Zoom = 25.0" );
+c        Sets the Report attribute for Object "map" to the value 1 and
+c        the Zoom attribute to 25.0.
+c     astSet( frame, "Label( %d ) =Offset along axis %d", axis, axis );
+c        Sets the Label(axis) attribute for Object "frame" to a
+c        suitable string, where the axis number is obtained from
+c        "axis", a variable of type int.
+c     astSet( frame, "Title =%s", mystring );
+c        Sets the Title attribute for Object "frame" to the contents of
+c        the string "mystring".
+f     CALL AST_SET( MAP, 'Report = 1, Zoom = 25.0', STATUS )
+f        Sets the Report attribute for Object MAP to the value 1 and
+f        the Zoom attribute to 25.0.
+f     CALL AST_SET( FRAME, 'Label( 1 ) =Offset from cluster axis', STATUS )
+f        Sets the Label(1) attribute for Object FRAME to a suitable
+f        string.
+
+*  Notes:
+*     - Attribute names are not case sensitive and may be surrounded
+*     by white space.
+*     - White space may also surround attribute values, where it will
+*     generally be ignored (except for string-valued attributes where
+*     it is significant and forms part of the value to be assigned).
+*     - To include a literal comma in the value assigned to an attribute,
+*     the whole attribute value should be enclosed in quotation markes.
+c     Alternatively, you can use "%s" format and supply the value as a
+c     separate additional argument to astSet (or use the astSetC
+c     function instead).
+c     - The same procedure may be adopted if "%" signs are to be included
+c     and are not to be interpreted as format specifiers (alternatively,
+c     the "printf" convention of writing "%%" may be used).
+*     - An error will result if an attempt is made to set a value for
+*     a read-only attribute.
+*--
+
+*  Implementation Notes:
+*     - Because this function has a variable argument list, it is
+*     invoked by a macro that evaluates to a function pointer (not a
+*     function invocation) and no checking or casting of arguments is
+*     performed before the function is invoked. Because of this, the
+*     Object identifier is of type (void *) and is converted and
+*     validated within the function itself.
+*     - This implementation of astSet is designed to be used within AST,
+*     and has an explicit status parameter. From outside AST, the astSet
+*     macro will invoke the astSetId_ function which does not have an
+*     status parameter.
+
+*--
+*/
+
+/* Local Variables: */
+   AstObject *this;              /* Pointer to the Object structure */
+   va_list args;                 /* Variable argument list */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Obtain and validate a pointer to the Object structure. */
+   this = astCheckObject( this_void );
+   if ( astOK ) {
+
+/* Obtain the variable argument list and pass all arguments to the
+   astVSet method for interpretation. */
+      va_start( args, status );
+      astVSet( this, settings, NULL, args );
+      va_end( args );
+   }
+}
+
+static void SetAttrib( AstObject *this, const char *setting, int *status ) {
+/*
+*+
+*  Name:
+*     astSetAttrib
+
+*  Purpose:
+*     Set an attribute value for an Object.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astSetAttrib( AstObject *this, const char *setting )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function assigns an attribute value for an Object, the attribute and
+*     its value being specified by means of a string of the form:
+*
+*        "attribute= value "
+*
+*     Here, "attribute" specifies the attribute name and should be in lower
+*     case with no white space present. The value to the right of the "="
+*     should be a suitable textual representation of the value to be assigned
+*     and this will be interpreted according to the attribute's data type.
+*     White space surrounding the value is only significant for string
+*     attributes.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+*     setting
+*        Pointer to a null-terminated string specifying the new attribute
+*        value.
+
+*  Notes:
+*     - The Object class does not have any writable attributes, so
+*     this function merely reports an error. It is intended to be
+*     extended by other class definitions.
+*-
+*/
+
+/* Local Variables: */
+   int id;                       /* Offset of ID string */
+   int ival;                     /* Integer attribute value */
+   int len;                      /* Length of setting string */
+   int nc;                       /* Number of characters read by astSscanf */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Obtain the length of the setting string. */
+   len = (int) strlen( setting );
+
+/* Test for each recognised attribute in turn, using "astSscanf" to parse
+   the setting string and extract the attribute value (or an offset to
+   it in the case of string values). In each case, use the value set
+   in "nc" to check that the entire string was matched. Once a value
+   has been obtained, use the appropriate method to set it. */
+
+/* ID. */
+/* --- */
+   if ( nc = 0, ( 0 == astSscanf( setting, "id=%n%*[^\n]%n", &id, &nc ) )
+                && ( nc >= len ) ) {
+      astSetID( this, setting + id );
+
+/* Ident. */
+/* ------ */
+   } else if ( nc = 0, ( 0 == astSscanf( setting, "ident=%n%*[^\n]%n", &id, &nc ) )
+                && ( nc >= len ) ) {
+      astSetIdent( this, setting + id );
+
+/* UseDefs */
+/* ------- */
+   } else if ( nc = 0,
+               ( 1 == astSscanf( setting, "usedefs= %d %n", &ival, &nc ) )
+               && ( nc >= len ) ) {
+      astSetUseDefs( this, ival );
+
+/* Define a macro to see if the setting string matches any of the
+   read-only attributes of this class and use this to report an error
+   if it does. */
+#define MATCH(attrib) \
+        ( nc = 0, ( 0 == astSscanf( setting, attrib "=%*[^\n]%n", &nc ) ) && \
+                  ( nc >= len ) )
+
+   } else if ( MATCH( "class" ) ||
+               MATCH( "nobject" ) ||
+               MATCH( "objsize" ) ||
+               MATCH( "refcount" ) ) {
+      astError( AST__NOWRT, "astSet: The setting \"%s\" is invalid for a %s.", status,
+                setting, astGetClass( this ) );
+      astError( AST__NOWRT, "This is a read-only attribute." , status);
+
+/* Since no writable attributes are defined for the Object class, any
+   attempt to set a value for anything else is also an error. */
+   } else {
+      astError( AST__BADAT, "astSet: The attribute setting \"%s\" is invalid "
+               "for a %s.", status, setting, astGetClass( this ) );
+   }
+
+/* Undefine macros local to this function. */
+#undef MATCH
+}
+
+void astSetCopy_( AstObjectVtab *vtab,
+                  void (* copy)( const AstObject *, AstObject *, int * ), int *status ) {
+/*
+*+
+*  Name:
+*     astSetCopy
+
+*  Purpose:
+*     Declare a copy constructor for an Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astSetCopy( AstObjectVtab *vtab,
+*                      void (* copy)( const AstObject *, AstObject * ) )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function is provided so that class definitions can declare a copy
+*     constructor to be associated with an Object that is being constructed.
+*     When a copy is later performed on the Object, the copy constructor of
+*     each class to which the Object belongs will be invoked in turn (working
+*     down the class hierarchy). The copy constructor is passed pointers to the
+*     source and destination Objects. It should implement the copy and return
+*     void.
+
+*  Parameters:
+*     vtab
+*        Pointer to the Object's virtual function table, in which the copy
+*        constructor's pointer is to be stored for future use.
+*     copy
+*        Pointer to the copy constructor function.
+
+*  Notes:
+*     -  When an Object is copied, a byte-by-byte copy of its structure is
+*     automatically made before any copy constructors are invoked. A copy
+*     constructor need only be provided if this does not suffice (e.g. if the
+*     structure contains pointers to other data).
+*     - If a copy constructor is declared for a class, then a
+*     destructor for that class must also be declared (using
+*     astSetDelete) so that there is a one-to-one correspondence
+*     between copy constructors and their associated destructors.
+*     -  Copy constructors should check the global error status in the normal
+*     way and should set it (and report an error) if they fail.
+*-
+*/
+
+
+/* Check the global status. */
+   if ( !astOK ) return;
+
+/* Indicate that subsequent memory allocations may never be freed (other
+   than by any AST exit handler). */
+   astBeginPM;
+
+/* Expand the array of copy constructor pointers in the virtual function table
+   (if necessary) to accommodate the new one. */
+   vtab->copy = astGrow( vtab->copy, vtab->ncopy + 1,
+                        sizeof( void (*)( const AstObject *, AstObject * ) ) );
+
+/* If OK, store the new function pointer and increment the count of copy
+   constructors. */
+   if ( astOK ) {
+      vtab->copy[ vtab->ncopy++ ] = copy;
+   }
+
+/* Mark the end of the section in which memory allocations may never be freed
+   (other than by any AST exit handler). */
+   astEndPM;
+
+}
+
+void astSetDelete_( AstObjectVtab *vtab, void (* delete)( AstObject *, int * ), int *status ) {
+/*
+*+
+*  Name:
+*     astSetDelete
+
+*  Purpose:
+*     Declare a destructor for an Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astSetDelete( AstObjectVtab *vtab, void (* delete)( AstObject * ) )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function is provided so that class definitions can declare a
+*     destructor to be associated with an Object. When the Object is later
+*     deleted, the destructor declared by each class to which the Object
+*     belongs will be invoked in turn (working up the class hierarchy). The
+*     destructor is passed a pointer to the Object. It should free any
+*     resources (e.g. memory) associated with it and return void. It should
+*     not free the memory containing the Object itself.
+
+*  Parameters:
+*     vtab
+*        Pointer to the Object's virtual function table, in which the
+*        destructor's pointer is to be stored for future use.
+*     delete
+*        Pointer to the destructor function.
+
+*  Notes:
+*     - A destructor need not be declared for a class if there are no
+*     resources to free.
+*     - If a destructor is declared for a class, then a copy
+*     constructor for that class must also be declared (using
+*     astSetCopy) so that there is a one-to-one correspondence between
+*     copy constructors and their associated destructors.
+*     - A destructor function should generally attempt to execute even
+*     if the global error status is set on entry, but should not
+*     report further errors in that case (errors should be reported
+*     normally if status is not set on entry).
+*-
+*/
+
+
+/* Check the global status. */
+   if ( !astOK ) return;
+
+/* Indicate that subsequent memory allocations may never be freed (other
+   than by any AST exit handler). */
+   astBeginPM;
+
+/* Expand the array of destructor pointers in the virtual function table (if
+   necessary) to accommodate the new one. */
+   vtab->delete = astGrow( vtab->delete, vtab->ndelete + 1,
+                           sizeof( void (*)( AstObject * ) ) );
+
+/* If OK, store the new function pointer and increment the count of
+   destructors. */
+   if ( astOK ) {
+      vtab->delete[ vtab->ndelete++ ] = delete;
+   }
+
+/* Mark the end of the section in which memory allocations may never be freed
+   (other than by any AST exit handler). */
+   astEndPM;
+
+}
+
+void astSetDump_( AstObjectVtab *vtab,
+                  void (* dump)( AstObject *, AstChannel *, int * ),
+                  const char *class, const char *comment, int *status ) {
+/*
+*+
+*  Name:
+*     astSetDump
+
+*  Purpose:
+*     Declare a dump function for an Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astSetDump( AstObjectVtab *vtab,
+*                      void (* dump)( AstObject *, AstChannel * ),
+*                      const char *class, const char *comment )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function is provided so that class definitions can declare
+*     a dump function to be associated with an Object that is being
+*     constructed.  When the astWrite (or astShow or astToString) method
+*     is later used to write the Object to a Channel, the dump function
+*     of each class to which the Object belongs will be invoked in turn
+*     (working down the class hierarchy). The dump function is passed
+*     pointers to the Object and the output Channel. It should write
+*     out any internal values (e.g. instance variables) for its class
+*     that are to be kept (using the protected astWrite... methods of
+*     the Channel) and return void.
+
+*  Parameters:
+*     vtab
+*        Pointer to the Object's virtual function table, in which the
+*        dump function's pointer is to be stored for future use.
+*     dump
+*        Pointer to the dump function.
+*     class
+*        Pointer to a constant null-terminated string (residing in
+*        static memory) containing the name of the class that is
+*        declaring the dump function.
+*     comment
+*        Pointer to a constant null-terminated string (residing in
+*        static memory) containing a comment to associate with the
+*        dump function.  This should normally describe the purpose of
+*        the class that is declaring the dump function.
+
+*  Notes:
+*     - Dump functions should check the global error status in the
+*     normal way and should set it (and report an error) if they fail.
+*-
+*/
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Indicate that subsequent memory allocations may never be freed (other
+   than by any AST exit handler). */
+   astBeginPM;
+
+/* Expand the arrays of pointers to dump functions and related data in
+   the virtual function table (if necessary) to accommodate the new
+   one. */
+   vtab->dump = astGrow( vtab->dump, vtab->ndump + 1,
+                         sizeof( void (*)( AstObject *, AstChannel * ) ) );
+   vtab->dump_class = astGrow( vtab->dump_class, vtab->ndump + 1,
+                               sizeof( char * ) );
+   vtab->dump_comment = astGrow( vtab->dump_comment, vtab->ndump + 1,
+                                 sizeof( char * ) );
+
+/* If OK, store the new pointers (to the dump function, class name and
+   comment) and increment the count of dump functions. */
+   if ( astOK ) {
+      vtab->dump[ vtab->ndump ] = dump;
+      vtab->dump_class[ vtab->ndump ] = class;
+      vtab->dump_comment[ vtab->ndump ] = comment;
+      vtab->ndump++;
+   }
+
+/* Mark the end of the section in which memory allocations may never be
+   freed (other than by any AST exit handler). */
+   astEndPM;
+}
+
+void astSetProxy_( AstObject *this, void *proxy, int *status ) {
+/*
+*+
+*  Name:
+*     astSetProxy
+
+*  Purpose:
+*     Store a pointer to the foreign language proxy used to represent a
+*     given AST Object.
+
+*  Type:
+*     Undocumented public function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astSetProxy( AstObject *this, void *proxy )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function stores the supplied pointer in the AST Object so that
+*     it can be retrieved later using astGetProxy.
+*
+*     The supplied pointer should point to a structure that is used
+*     to represent the AST Object within some external system. It is
+*     expected that the external system will check each object reference
+*     returned by AST to see if it has an associated proxy object. If not
+*     (i.e. if astGetProxy returns NULL), a new external object will be
+*     created to represent the AST Object, and a pointer to it will be
+*     stored in the AST Object using astSetProxy. If the AST Object
+*     already has a proxy, the AST reference is annulled and the existing
+*     proxy object is used by the external system.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+*     proxy
+*        Pointer to the proxy object, or NULL.
+
+*  Notes:
+*     - The suppied pointer is not used within AST itself, other than to
+*     be returned by the astGetProxy method.
+*     - This function is public, but is currently undocumented since it
+*     is only of interest to people writing AST interfaces for other
+*     languages.
+*-
+*/
+   if( !astOK ) return;
+   this->proxy = proxy;
+}
+
+void astSetVtab_( AstObject *this, AstObjectVtab *vtab, int *status ) {
+/*
+*+
+*  Name:
+*     astSetVtab
+
+*  Purpose:
+*     Change the virtual function table associated with an Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astSetVtab( AstObject *this, AstObjectVtab *vtab )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function changes the virtual function table associated with an
+*     Object. This may be needed, for instance, if a super-class
+*     initialises a parent class structure with a NULL vtab, causing the
+*     vtab of the parent class to be used instead of the super-class.
+*     Whilst the super-class object is being constructed its inherited methods
+*     will be determined by the parent class. Once the super-class object
+*     has been constructed, it can invoke this fuction in order to
+*     set the vtab to the super-class vtab, thus causing the method
+*     implementations provided by the super-cvlass to be used.
+
+*  Parameters:
+*     this
+*        Pointer to the Object to be modified.
+*     vtab
+*        Pointer to the virtual function table to store in the Object.
+*-
+*/
+   if( this ) this->vtab = vtab;
+}
+
+static int Same( AstObject *this, AstObject *that, int *status ) {
+/*
+*++
+*  Name:
+c     astSame
+f     AST_SAME
+
+*  Purpose:
+*     Test if two AST pointers refer to the same Object.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     int astSame( AstObject *this,  AstObject *that )
+f     RESULT = AST_SAME( THIS, THAT, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+c     This function returns a boolean result (0 or 1) to indicate
+f     This function returns a logical result to indicate
+*     whether two pointers refer to the same Object.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the first Object.
+c     that
+f     THAT = INTEGER (Given)
+*        Pointer to the second Object.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astSame()
+c        One if the two pointers refer to the same Object, otherwise zero.
+f     AST_SAME = LOGICAL
+f        .TRUE. if the two pointers refer to the same Object, otherwise
+f        .FALSE.
+
+*  Applicability:
+*     Object
+c        This function applies to all Objects.
+f        This routine applies to all Objects.
+
+*  Notes:
+*     - Two independent Objects that happen to be identical are not
+*     considered to be the same Object by this function.
+c     - A value of zero will be returned if this function is invoked
+c     with the AST error status set, or if it should fail for any reason.
+f     - A value of .FALSE. will be returned if this function is invoked
+f     with STATUS set to an error value, or if it should fail for any reason.
+*--
+*/
+
+/* Check the global error status. */
+   if ( !astOK ) return 0;
+
+/* Return the result. */
+   return ( this == that ) ? 1 : 0;
+}
+
+/*
+*++
+*  Name:
+c     astSet<X>
+f     AST_SET<X>
+
+*  Purpose:
+*     Set an attribute value for an Object.
+
+*  Type:
+*     Public functions.
+
+*  Synopsis:
+c     #include "object.h"
+c     void astSet<X>( AstObject *this, const char *attrib, <X>type value )
+f     CALL AST_SET<X>( THIS, ATTRIB, VALUE, STATUS )
+
+*  Class Membership:
+*     Object methods.
+
+*  Description:
+c     This is a family of functions which set a specified attribute
+f     This is a family of routines which set a specified attribute
+*     value for an Object using one of several different data
+c     types. The type is selected by replacing <X> in the function name
+f     types. The type is selected by replacing <X> in the routine name
+c     by C, D, F, I or L, to supply a value in const char* (i.e. string),
+c     double, float, int, or long format, respectively.
+f     by C, D, I, L or R, to supply a value in Character, Double
+f     precision, Integer, Logical or Real format, respectively.
+*
+*     If possible, the value you supply is converted to the type of
+*     the attribute. If conversion is not possible, an error will
+*     result.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the Object.
+c     attrib
+f     ATTRIB = CHARACTER * ( * ) (Given)
+c        Pointer to a null-terminated character string containing the
+c        name of the attribute whose value is to be set.
+f        A character string containing the name of the attribute whose
+f        value is to be set.
+c     value
+f     VALUE = <X>type (Given)
+c        The value to be set for the attribute, in the data type corresponding
+c        to <X> (or, in the case of astSetC, a pointer to a null-terminated
+c        character string containing this value).
+f        The value to be set for the attribute, in the data type corresponding
+f        to <X>.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Applicability:
+*     Object
+c        These functions apply to all Objects.
+f        These routines apply to all Objects.
+
+*  Examples:
+c     astSetI( frame, "Preserve", 1 );
+c        Sets the Preserve attribute value for Object "frame" to 1.
+c     astSetC( plot, "Format(1)", "%.2g" );
+c        Sets the Format(1) attribute value for Object "plot" to the
+c        character string "%.2g".
+f     CALL AST_SETC( PLOT, 'Title', CVALUE, STATUS )
+f        Sets the Title attribute value for Object PLOT to the contents
+f        of the character variable CVALUE.
+f     CALL AST_SETL( FRAME, 'Preserve', .TRUE., STATUS );
+f        Sets the Preserve attribute value for Object FRAME to 1 (true).
+
+*  Notes:
+*     - Attribute names are not case sensitive and may be surrounded
+*     by white space.
+f     - The logical value .FALSE. will translate to a numerical attribute
+f     value of zero and logical .TRUE. will translate to one.
+*     - An error will result if an attempt is made to set a value for
+*     a read-only attribute.
+*--
+*/
+
+/* Define a macro that expands to implement the astSetX_ member
+   functions required. The arguments to this macro are:
+
+      code
+         The character that appears at the end of the function name.
+      type
+         The C type of the function "value" parameter.
+      format
+         A quoted string containing a sprintf format specifier that will
+         format the supplied value as a character string. This format should
+         consume 2 sprintf arguments: a field width and the value to be
+         formatted.
+      fmtlen
+         The number of characters in the format specifier (above).
+      fieldsz
+         The value of the field width to be used by the format specifier.
+*/
+#define MAKE_SETX(code,type,format,fmtlen,fieldsz) \
+void astSet##code##_( AstObject *this, const char *attrib, type value, int *status ) { \
+\
+/* Local Variables: */ \
+   char *setting;                /* Pointer to attribute setting string */ \
+   int len;                      /* Length of attribute name */ \
+\
+/* Check the global status. */ \
+   if ( !astOK ) return; \
+\
+/* Obtain the length of the attribute name and allocate memory to hold \
+   this name plus the format specifier to be appended to it. */ \
+   len = (int) astChrLen( attrib ); \
+   setting = astMalloc( (size_t) ( len + fmtlen + 2 ) ); \
+\
+/* Make a copy of the attribute name in the allocated memory. */ \
+   if ( astOK ) { \
+      (void) memcpy( setting, attrib, (size_t) len ); \
+      setting[ len ] = 0; \
+\
+/* Append "=", followed by the format specifier, to construct a \
+   suitable "setting" string for use by astSet. */ \
+      (void) strcat( setting, "=" format ); \
+\
+/* Invoke astSet to set the attribute value. */ \
+      astSet( this, setting, status, fieldsz, value ); \
+   } \
+\
+/* Free the allocated memory. */ \
+   setting = astFree( setting ); \
+}
+
+/* Use this macro to create all the SetX_ private member functions. */
+MAKE_SETX(D,double,"%.*g",4,AST__DBL_DIG)
+MAKE_SETX(F,float,"%.*g",4,FLT_DIG)
+MAKE_SETX(I,int,"%.*d",4,1)
+MAKE_SETX(L,long,"%.*ld",5,1)
+
+
+/* The astSetC_ function is implemented separately so that commas can be
+   handled. Since astSetC can only be used to set a single attribute
+   value, we know that any commas in the supplied value are included
+   within the attribuite value, rather than being used as delimiters
+   between adjacent attribute settings. To avoid VSet using them as
+   delimiters, they are replaced here by '\r' before calling astSet, and
+   VSet then converts them back to commas. */
+
+void astSetC_( AstObject *this, const char *attrib, const char *value, int *status ) {
+
+/* Local Variables: */
+   char *d;                      /* Pointer to next setting character */
+   char *newv;                   /* Pointer to new attribute value string */
+   char *setting;                /* Pointer to attribute setting string */
+   const char *c;                /* Pointer to next value character */
+   int len;                      /* Length of attribute name */
+
+/* Check the global status. */
+   if ( !astOK ) return;
+
+/* Produce a copy of the supplied attribute value in which any commas
+   are replaced by carriage returns ("\r"). */
+   newv = astMalloc( (size_t)( strlen( value ) + 1 ) );
+   if( newv ) {
+      d = newv;
+      c = value;
+      while( *c ) {
+         if( *c == ',' ) {
+            *d = '\r';
+         } else {
+            *d = *c;
+         }
+         c++;
+         d++;
+      }
+      *d = 0;
+
+/* Obtain the length of the attribute name and allocate memory to hold
+   this name plus the format specifier to be appended to it. */
+      len = (int) astChrLen( attrib );
+      setting = astMalloc( (size_t) ( len + 5 ) );
+
+/* Make a copy of the attribute name in the allocated memory. */
+      if ( astOK ) {
+         (void) memcpy( setting, attrib, (size_t) len );
+         setting[ len ] = 0;
+
+/* Append "=", followed by the format specifier, to construct a
+   suitable "setting" string for use by astSet. */
+         (void) strcat( setting, "=%*s" );
+
+/* Invoke astSet to set the attribute value. */
+         astSet( this, setting, status, 0, newv );
+      }
+
+/* Free the allocated memory. */
+      setting = astFree( setting );
+   }
+   newv = astFree( newv );
+}
+
+static void Show( AstObject *this, int *status ) {
+/*
+*++
+*  Name:
+c     astShow
+f     AST_SHOW
+
+*  Purpose:
+*     Display a textual representation of an Object on standard output.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     void astShow( AstObject *this )
+f     CALL AST_SHOW( THIS, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+c     This function displays a textual description of any AST Object
+f     This routine displays a textual description of any AST Object
+*     on standard output. It is provided primarily as an aid to
+*     debugging.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the Object to be displayed.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Applicability:
+*     Object
+c        This function applies to all Objects.
+f        This routine applies to all Objects.
+*--
+*/
+
+/* Local Variables: */
+   AstChannel *channel;          /* Pointer to output Channel */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Create a Channel which will write to standard output. */
+   channel = astChannel( NULL, NULL, "", status );
+
+/* Write the Object to the Channel. */
+   astWrite( channel, this );
+
+/* Annul the Channel pointer. */
+   channel = astAnnul( channel );
+}
+
+int astTest_( AstObject *this, const char *attrib, int *status ) {
+/*
+*++
+*  Name:
+c     astTest
+f     AST_TEST
+
+*  Purpose:
+*     Test if an Object attribute value is set.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     int astTest( AstObject *this, const char *attrib )
+f     RESULT = AST_TEST( THIS, ATTRIB, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+c     This function returns a boolean result (0 or 1) to indicate
+f     This function returns a logical result to indicate
+*     whether a value has been explicitly set for one of an Object's
+*     attributes.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the Object.
+c     attrib
+f     ATTRIB = CHARACTER * ( * ) (Given)
+c        Pointer to a null-terminated character string containing
+c        the name of the attribute to be tested.
+f        A character string containing the name of the attribute to be
+f        tested.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astTest()
+c        One if a value has previously been explicitly set for the attribute
+c        (and hasn't been cleared), otherwise zero.
+f     AST_TEST = LOGICAL
+f        .TRUE. if a value has previously been explicitly set for the
+f        attribute (and hasn't been cleared), otherwise .FALSE..
+
+*  Applicability:
+*     Object
+c        This function applies to all Objects.
+f        This routine applies to all Objects.
+
+*  Notes:
+*     - Attribute names are not case sensitive and may be surrounded
+*     by white space.
+c     - A value of zero will be returned if this function is invoked
+f     - A value of .FALSE. will be returned if this function is invoked
+c     with the AST error status set, or if it should fail for any reason.
+f     with STATUS set to an error value, or if it should fail for any reason.
+c     - A value of zero will also be returned if this function is used
+f     - A value of .FALSE. will also be returned if this function is used
+*     to test a read-only attribute, although no error will result.
+*--
+*/
+
+/* Local Variables: */
+   char *buff;                   /* Pointer to character buffer */
+   int i;                        /* Loop counter for characters */
+   int j;                        /* Non-blank character count */
+   int len;                      /* Length of attrib string */
+   int result;                   /* Result value to return */
+
+/* Initialise. */
+   result = 0;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Obtain the length of the attrib string. */
+   len = (int) strlen( attrib );
+
+/* Allocate memory and store a copy of the string. */
+   buff = astStore( NULL, attrib, (size_t) ( len + 1 ) );
+   if ( astOK ) {
+
+/* Remove white space and upper case characters. */
+      for ( i = j = 0; buff[ i ]; i++ ) {
+         if ( !isspace( buff[ i ] ) ) buff[ j++ ] = tolower( buff[ i ] );
+      }
+
+/* Terminate the attribute name and pass it to astTestAttrib to test
+   the attribute. */
+      buff[ j ] = '\0';
+      result = astTestAttrib( this, buff );
+   }
+
+/* Free the memory allocated for the string buffer. */
+   buff = astFree( buff );
+
+/* If an error occurred, clear the result value. */
+   if ( !astOK ) result = 0;
+
+/* Return the result. */
+   return result;
+}
+
+static int TestAttrib( AstObject *this, const char *attrib, int *status ) {
+/*
+*+
+*  Name:
+*     astTestAttrib
+
+*  Purpose:
+*     Test if a specified attribute value is set for an Object.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "object.h"
+*     int astTestAttrib( AstObject *this, const char *attrib )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns a boolean result (0 or 1) to indicate whether
+*     a value has been set for one of an Object's attributes.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+*     attrib
+*        Pointer to a null-terminated string specifying the attribute
+*        name.  This should be in lower case with no surrounding white
+*        space.
+
+*  Returned Value:
+*     One if a value has been set, otherwise zero.
+
+*  Notes:
+*     - A value of zero will be returned if this function is invoked
+*     with the global status set, or if it should fail for any reason.
+*-
+*/
+
+/* Local Variables: */
+   int result;                   /* Result value to return */
+
+/* Initialise. */
+   result = 0;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Check the attribute name and test the appropriate attribute. */
+
+/* ID. */
+/* --- */
+   if ( !strcmp( attrib, "id" ) ) {
+      result = astTestID( this );
+
+/* Ident. */
+/* ------ */
+   } else if ( !strcmp( attrib, "ident" ) ) {
+      result = astTestIdent( this );
+
+/* UseDefs */
+/* ------- */
+   } else if ( !strcmp( attrib, "usedefs" ) ) {
+      result = astTestUseDefs( this );
+
+/* Test if the attribute string matches any of the read-only
+   attributes of this class. If it does, then return zero. */
+   } else if ( !strcmp( attrib, "class" ) ||
+               !strcmp( attrib, "nobject" ) ||
+               !strcmp( attrib, "objsize" ) ||
+               !strcmp( attrib, "refcount" ) ) {
+      result = 0;
+
+/* Any attempt to test any other attribute is an error. */
+   } else if( astOK ){
+      astError( AST__BADAT, "astTest: The attribute name \"%s\" is invalid "
+               "for a %s.", status, attrib, astGetClass( this ) );
+   }
+
+/* Return the result, */
+   return result;
+}
+
+int astTune_( const char *name, int value, int *status ) {
+/*
+*++
+*  Name:
+c     astTune
+f     AST_TUNE
+
+*  Purpose:
+*     Set or get an integer-valued AST global tuning parameter.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     int astTune( const char *name, int value )
+f     RESULT = AST_TUNE( NAME, VALUE, STATUS )
+
+*  Class Membership:
+*     Object function.
+
+*  Description:
+*     This function returns the current value of an integer-valued AST
+*     global tuning parameter, optionally storing a new value for the
+*     parameter. For character-valued tuning parameters, see
+c     astTuneC.
+f     AST_TUNEC.
+
+*  Parameters:
+c     name
+f     NAME = CHARACTER * ( * ) (Given)
+*        The name of the tuning parameter (case-insensitive).
+c     value
+f     VALUE = INTEGER (Given)
+*        The new value for the tuning parameter. If this is AST__TUNULL,
+*        the existing current value will be retained.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astTune()
+f     AST_TUNE = INTEGER
+c        The original value of the tuning parameter. A default value will
+*        be returned if no value has been set for the parameter.
+
+*  Tuning Parameters:
+*     ObjectCaching
+*        A boolean flag which indicates what should happen
+*        to the memory occupied by an AST Object when the Object is deleted
+*        (i.e. when its reference count falls to zero or it is deleted using
+c        astDelete).
+f        AST_DELETE).
+*        If this is zero, the memory is simply freed using the systems "free"
+*        function. If it is non-zero, the memory is not freed. Instead a
+*        pointer to it is stored in a pool of such pointers, all of which
+*        refer to allocated but currently unused blocks of memory. This allows
+*        AST to speed up subsequent Object creation by re-using previously
+*        allocated memory blocks rather than allocating new memory using the
+*        systems malloc function. The default value for this parameter is
+*        zero. Setting it to a non-zero value will result in Object memory
+*        being cached in future. Setting it back to zero causes any memory
+*        blocks currently in the pool to be freed. Note, this tuning parameter
+*        only controls the caching of memory used to store AST Objects. To
+*        cache other memory blocks allocated by AST, use MemoryCaching.
+*     MemoryCaching
+*        A boolean flag similar to ObjectCaching except
+*        that it controls caching of all memory blocks of less than 300 bytes
+*        allocated by AST (whether for internal or external use), not just
+*        memory used to store AST Objects.
+
+*  Notes:
+c     - This function attempts to execute even if the AST error
+c     status is set
+f     - This routine attempts to execute even if STATUS is set to an
+f     error value
+*     on entry, although no further error report will be
+*     made if it subsequently fails under these circumstances.
+*     - All threads in a process share the same AST tuning parameters
+*     values.
+*--
+*/
+
+   int result = AST__TUNULL;
+
+   if( name ) {
+
+      LOCK_MUTEX1;
+
+      if( astChrMatch( name, "ObjectCaching" ) ) {
+         result = object_caching;
+         if( value != AST__TUNULL ) {
+            object_caching = value;
+            if( !object_caching ) EmptyObjectCache( status );
+         }
+
+      } else if( astChrMatch( name, "MemoryCaching" ) ) {
+         result = astMemCaching( value );
+
+      } else if( astOK ) {
+         astError( AST__TUNAM, "astTune: Unknown AST tuning parameter "
+                   "specified \"%s\".", status, name );
+      }
+
+      UNLOCK_MUTEX1;
+
+   }
+
+   return result;
+}
+
+void astTuneC_( const char *name, const char *value, char *buff,
+                int bufflen, int *status ) {
+/*
+*++
+*  Name:
+c     astTuneC
+f     AST_TUNEC
+
+*  Purpose:
+*     Set or get a character-valued AST global tuning parameter.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     void astTuneC( const char *name, const char *value, char *buff,
+c                    int bufflen )
+f     CALL AST_TUNEC( NAME, VALUE, BUFF, STATUS )
+
+*  Class Membership:
+*     Object function.
+
+*  Description:
+*     This function returns the current value of a character-valued
+*     AST global tuning parameter, optionally storing a new value
+*     for the parameter. For integer-valued tuning parameters, see
+c     astTune.
+f     AST_TUNE.
+
+*  Parameters:
+c     name
+f     NAME = CHARACTER * ( * ) (Given)
+*        The name of the tuning parameter (case-insensitive).
+c     value
+f     VALUE = CHARACTER * ( ) (Given)
+*        The new value for the tuning parameter. If this is
+f        AST__TUNULLC,
+c        NULL,
+*        the existing current value will be retained.
+c     buff
+f     BUFF = CHARACTER * ( ) (Given)
+*        A character string in which to return the original value of
+*        the tuning parameter. An error will be reported if the buffer
+*        is too small to hold the value.
+c        NULL may be supplied if the old value is not required.
+c     bufflen
+c        The size of the supplied "buff" array. Ignored if "buff" is NULL.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Tuning Parameters:
+*     HRDel
+*        A string to be drawn following the hours field in a formatted
+*        sky axis value when "g" format is in use (see the Format
+*        attribute). This string may include escape sequences to produce
+*        super-scripts, etc. (see the Escapes attribute for details
+*        of the escape sequences allowed). The default value is
+*        "%-%^50+%s70+h%+" which produces a super-script "h".
+*     MNDel
+*        A string to be drawn following the minutes field in a formatted
+*        sky axis value when "g" format is in use. The default value is
+*        "%-%^50+%s70+m%+" which produces a super-script "m".
+*     SCDel
+*        A string to be drawn following the seconds field in a formatted
+*        sky axis value when "g" format is in use. The default value is
+*        "%-%^50+%s70+s%+" which produces a super-script "s".
+*     DGDel
+*        A string to be drawn following the degrees field in a formatted
+*        sky axis value when "g" format is in use. The default value is
+*        "%-%^53+%s60+o%+" which produces a super-script "o".
+*     AMDel
+*        A string to be drawn following the arc-minutes field in a formatted
+*        sky axis value when "g" format is in use. The default value is
+*        "%-%^20+%s85+'%+" which produces a super-script "'" (single quote).
+*     ASDel
+*        A string to be drawn following the arc-seconds field in a formatted
+*        sky axis value when "g" format is in use. The default value is
+*        "%-%^20+%s85+\"%+" which produces a super-script """ (double quote).
+*     EXDel
+*        A string to be drawn to introduce the exponent in a value when "g"
+*        format is in use. The default value is "10%-%^50+%s70+" which
+*        produces "10" followed by the exponent as a super-script.
+
+*  Notes:
+c     - This function attempts to execute even if the AST error
+c     status is set
+f     - This routine attempts to execute even if STATUS is set to an
+f     error value
+*     on entry, although no further error report will be
+*     made if it subsequently fails under these circumstances.
+*     - All threads in a process share the same AST tuning parameters
+*     values.
+*--
+*/
+
+/* Local Variables: */
+   char *p = NULL;
+   int len;
+
+/* Check the name of a tuning parameter was supplied. */
+   if( name ) {
+
+/* Serialise access to the tuning parameters since they are common to all
+   threads. */
+      LOCK_MUTEX1;
+
+/* Get a pointer to the buffer that holds the value of the requested
+   tuning parameter. */
+      if( astChrMatch( name, "hrdel" ) ) {
+         p = hrdel;
+      } else if( astChrMatch( name, "mndel" ) ) {
+         p = mndel;
+      } else if( astChrMatch( name, "scdel" ) ) {
+         p = scdel;
+      } else if( astChrMatch( name, "dgdel" ) ) {
+         p = dgdel;
+      } else if( astChrMatch( name, "amdel" ) ) {
+         p = amdel;
+      } else if( astChrMatch( name, "asdel" ) ) {
+         p = asdel;
+      } else if( astChrMatch( name, "exdel" ) ) {
+         p = exdel;
+
+/* Report an error if an the tuning parameter name is unknown. */
+      } else if( astOK ) {
+         p = NULL;
+         astError( AST__TUNAM, "astTuneC: Unknown AST tuning parameter "
+                   "specified \"%s\".", status, name );
+      }
+
+/* If the existing value was found. */
+      if( p ) {
+
+/* And is to be returned in the supplied buffer... */
+         if( buff ) {
+
+/* Check that the buffer is long enough. If so, copy the current value
+   into the buffer, otherwise report an error. */
+            len = strlen( p ) ;
+            if( len < bufflen ) {
+               strcpy( buff, p );
+            } else {
+               astError( AST__TUNAM, "astTuneC: Supplied string variable "
+                         "is too small - the current '%s' value (%s) has "
+                         "%d characters.", status, name, p, len );
+            }
+         }
+
+/* If a new value is to be stored.... */
+         if( value ) {
+
+/* Report an error if it is too long to fit in the static buffer. */
+            len = strlen( value ) ;
+            if( len >= MAXLEN_TUNEC ) {
+               astError( AST__TUNAM, "astTuneC: Supplied value for '%s' "
+                         "(%s) is too long - must not be longer than %d "
+                         "characters.", status, name, value, MAXLEN_TUNEC );
+
+/* Otherwise, copy the new value into the static buffer. */
+            } else {
+               strcpy( p, value );
+            }
+         }
+      }
+
+      UNLOCK_MUTEX1;
+   }
+}
+
+AstObject *astFromString_( const char *string, int *status ) {
+/*
+c++
+*  Name:
+*     astFromString
+
+*  Purpose:
+*     Re-create an Object from an in-memory serialisation
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astFromString( const char *string )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns a pointer to a new Object created from the
+*     supplied text string, which should have been created by astToString.
+
+*  Parameters:
+*     string
+*        Pointer to a text string holding an Object serialisation created
+*        previously by astToString.
+
+*  Returned Value:
+*     astFromString()
+*        Pointer to a new Object created from the supplied serialisation,
+*        or NULL if the serialisation was invalid, or an error occurred.
+
+c--
+*/
+
+/* Local Variables: */
+   StringData data;              /* Data passed to the source function */
+   AstChannel *channel;          /* Pointer to output Channel */
+   AstObject *result;            /* Pointer to returned Object */
+
+/* Check the global error status and supplied serialisation. */
+   if ( !astOK || !string ) return NULL;
+
+/* Create a Channel which will read from the supplied serialisation. */
+   channel = astChannel( FromStringSource, NULL, "", status );
+
+/* Initialise the data structure used to communicate with the source
+   function, and store a pointer to it in the Channel. */
+   data.ptr = (char *) string;
+   data.buff = NULL;
+   data.len = 0;
+   astPutChannelData( channel, &data );
+
+/* Read an Object from the Channel. */
+   result = astRead( channel );
+
+/* Annul the Channel pointer. */
+   channel = astAnnul( channel );
+
+/* Free the line buffer. */
+   data.buff = astFree( data.buff );
+
+/* Annul the returned Object if an error has occurred. */
+   if( !astOK ) result = astAnnul( result );
+
+/* Return the Object pointer. */
+   return result;
+}
+
+static const char *FromStringSource( void ){
+/*
+*  Name:
+*     FromStringSource
+
+*  Purpose:
+*     A Channel source function for use by the astFromString method.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     result = FromStringSource( void )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function reads the next line of text from a serialisation and
+*     returns a pointer to it, or NULL if no lines remain.
+
+*  Returned Value:
+*     Pointer to the null terminated line of text or NULL if no lines
+*     remain.
+*/
+
+/* Local Variables: */
+   StringData *data;     /* Data passed to the sink function */
+   char *nl;             /* Pointer to next newline character */
+   int *status;          /* Pointer to local status value */
+   int nc;               /* Number of characters to read from serialisation */
+   int status_value;     /* Local status value */
+
+/* Set up the local status */
+   status_value = 0;
+   status = &status_value;
+
+/* Get a pointer to the structure holding a pointer to the next line, and
+   to the buffer to return. */
+   data = astChannelData;
+
+/* Return NULL if no text remains to be read. */
+   if( !data->ptr || (data->ptr)[0] == 0 ) return NULL;
+
+/* Find the next newline (if any) in the serialisation. */
+   nl = strchr( data->ptr, '\n' );
+
+/* Get the number of characters to copy. */
+   nc = nl ? nl - data->ptr : strlen( data->ptr );
+
+/* Copy them into the returned buffer, including an extra character for
+   the terminating null. */
+   data->buff = astStore( data->buff, data->ptr, nc + 1 );
+
+/* Store the terminating null. */
+   (data->buff)[ nc ] = 0;
+
+/* Update the pointer to the next character to read from the
+   serialisation. */
+   data->ptr = nl ? nl + 1 : NULL;
+
+/* Return the buffer. */
+   return data->buff;
+}
+
+static void VSet( AstObject *this, const char *settings, char **text,
+                  va_list args, int *status ) {
+/*
+*+
+*  Name:
+*     astVSet
+
+*  Purpose:
+*     Set values for an Object's attributes.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astVSet( AstObject *this, const char *settings, char **text,
+*                   va_list args )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function assigns a set of attribute values for an Object,
+*     the attributes and their values being specified by means of a
+*     string containing a comma-separated list of the form:
+*
+*        "attribute1 = value1, attribute2 = value2, ... "
+*
+*     Here, "attribute" specifies an attribute name and the value to
+*     the right of each "=" sign should be a suitable textual
+*     representation of the value to be assigned to that
+*     attribute. This will be interpreted according to the attribute's
+*     data type.
+*
+*     The string supplied may also contain "printf"-style format
+*     specifiers identified by a "%" sign in the usual way. If
+*     present, these will be substituted by values supplied as
+*     optional arguments (as a va_list variable argument list), using
+*     the normal "printf" rules, before the string is used.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+*     settings
+*        Pointer to a null-terminated string containing a
+*        comma-separated list of attribute settings.
+*     text
+*        Pointer to a location at which to return a pointer to dynamic
+*        memory holding a copy of the expanded setting string. This memory
+*        should be freed using astFree when no longer needed. If a NULL
+*        pointer is supplied, no string is created.
+*     args
+*        The variable argument list which contains values to be
+*        substituted for any "printf"-style format specifiers that
+*        appear in the "settings" string.
+
+*  Notes:
+*     - Attribute names are not case sensitive.
+*     - White space may surround attribute names and will be ignored.
+*     - White space may also surround attribute values where it will
+*     be ignored (except for string-valued attributes where it is
+*     significant and forms part of the value to be assigned).
+*     - After this function has substituted values for "printf"-style
+*     format specifiers it splits the "settings" string into
+*     individual attribute settings which it passes one at a time to
+*     the protected astSetAttrib method (after removal of white space
+*     and conversion of attribute names to lower case). The
+*     astSetAttrib method should therefore be extended by derived
+*     classes which define new attributes, and this will allow the
+*     astVSet (and astSet) methods to have access to those attributes.
+*     - This function provides the same functionality as the astSet
+*     public method but accepts a va_list variable argument list
+*     instead of a variable number of arguments. It is provided for
+*     use by functions in other class implementations which accept a
+*     variable number of arguments and must therefore pass their
+*     argument list to this method in va_list form.
+*-
+*/
+
+#define MIN_BUFF_LEN 1024
+#define ERRBUF_LEN 80
+
+/* Local Variables: */
+   char errbuf[ ERRBUF_LEN ];    /* Buffer for system error message */
+   char setting_buf[ MIN_BUFF_LEN ]; /* Expanded "%s" settting string */
+   char *dyn_buf;                /* Pointer to dynamic buffer for expanded setting */
+   char *errstat;                /* Pointer to error message */
+   char *assign;                 /* Pointer to assigment substring */
+   char *assign_end;             /* Pointer to null at end of assignment */
+   char *buff1;                  /* Pointer to temporary string buffer */
+   char *buff2;                  /* Pointer to temporary string buffer */
+   char *buff3;                  /* Pointer to temporary string buffer */
+   char *eq1;                    /* Pointer to 1st equals sign */
+   int buff_len;                 /* Length of temporary buffer */
+   int expanded;                 /* Has the Settings string been expanded yet? */
+   int i;                        /* Loop counter for characters */
+   int j;                        /* Offset for revised assignment character */
+   int len;                      /* Length of settings string */
+   int lo;                       /* Convert next character to lower case? */
+   int nc;                       /* Number of vsprintf output characters */
+   int quoted;                   /* Are we in a quoted string? */
+   int stat;                     /* Value of errno after an error */
+   int tq;                       /* Test if the next non-space is a quote? */
+
+/* Initialise */
+   if( text ) *text = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Obtain the length of the "settings" string and test it is not
+   zero. If it is, there is nothing more to do. */
+   len = (int) strlen( settings );
+   if ( len != 0 ) {
+
+/* If the setting string is just "%s" (with optional trailing and leading
+   white space) then the variable argument potentially contains more than
+   one attribute setting, in which case we expand the setting string now
+   and use the expanded string in place of the supplied string in the rest
+   of this function. */
+      nc = 0;
+      sscanf( settings, " %%s %n", &nc );
+      if( nc == len ) {
+
+/* Expand the supplied string using a fixed-length buffer. This writes at
+   most MIN_BUFF_LEN characters to "buf", but returns the number of
+   characters that would have been needed to write the whole string. */
+         len =  vsnprintf( setting_buf, sizeof(setting_buf), settings, args );
+
+/* If the fixed-length buffer is too short, use a dynamically allocated
+   buffer instead. */
+         if( len + 1 > MIN_BUFF_LEN ) {
+            dyn_buf = astMalloc( len + 1 );
+            if( astOK ) {
+               len =  vsnprintf( dyn_buf, len + 1, settings, args );
+               settings = dyn_buf;
+            }
+         } else {
+            dyn_buf = NULL;
+            settings = setting_buf;
+         }
+
+/* Indicate that "settings" has been expanded. */
+         expanded = 1;
+
+      } else {
+         expanded = 0;
+         dyn_buf = NULL;
+      }
+
+/* Allocate memory and store a copy of the string. */
+      buff1 = astStore( NULL, settings, (size_t) ( len + 1 ) );
+      if ( astOK ) {
+
+/* Convert each comma in the string into '\n'. This is to distinguish
+   commas initially present from those introduced by the formatting to
+   be performed below. We only do this if there is more than one equals
+   sign in the setting string, since otherwise any commas are probably
+   characters contained within a string attribute value. Ignore commas
+   that occur within quoted strings. */
+         eq1 = strchr( buff1, '=' );
+         if( eq1 && strchr( eq1 + 1, '=' ) ) {
+            quoted = 0;
+            for ( i = 0; i < len; i++ ) {
+               if( !quoted ) {
+                  if ( buff1[ i ] == ',' ) {
+                     buff1[ i ] = '\n';
+                  } else if( buff1[ i ] == '"' ) {
+                     quoted = 1;
+                  }
+               } else if( buff1[ i ] == '"' ){
+                  quoted = 0;
+               }
+            }
+         }
+
+/* Calculate a size for a further buffer twice the size of the first
+   one.  Ensure it is not less than a minimum size and then allocate
+   this buffer. */
+         buff_len = 2 * len;
+         if ( buff_len < MIN_BUFF_LEN ) buff_len = MIN_BUFF_LEN;
+         buff2 = astMalloc( (size_t) ( buff_len + 1 ) );
+         if ( astOK ) {
+
+/* Use "vsprintf" to substitute values for any format specifiers in
+   the "settings" string, writing the resulting string into the second
+   buffer. If the "settings" string has already been expanded, then just
+   copy it. */
+            errno = 0;
+            if( !expanded ) {
+               nc = vsprintf( buff2, buff1, args );
+            } else {
+               strcpy( buff2, buff1 );
+               nc = strlen( buff1 );
+            }
+
+/* Get a copy of the expanded string to return as the function value and
+   convert newlines back to commas. */
+            if( text ) {
+               *text = astStore( NULL, buff2, nc + 1 );
+               if( *text ) {
+                  for ( i = 0; i <= nc; i++ ) {
+                     if ( (*text)[ i ] == '\n' ) (*text)[ i ] = ',';
+                  }
+               }
+            }
+
+/* The possibilities for error detection are limited here, but check
+   if an error value was returned and report an error. Include
+   information from errno if it was set. */
+            if ( nc < 0 ) {
+               if( astOK ) {
+                  stat = errno;
+
+                  if( stat ) {
+#if HAVE_STRERROR_R
+                     strerror_r( stat, errbuf, ERRBUF_LEN );
+                     errstat = errbuf;
+#else
+                     errstat = strerror( stat );
+#endif
+                  } else {
+                     *errbuf = 0;
+                     errstat = errbuf;
+                  }
+
+                  astError( AST__ATSER, "astVSet(%s): Error formatting an "
+                            "attribute setting%s%s.", status, astGetClass( this ),
+                            stat? " - " : "", errstat );
+                  astError( AST__ATSER, "The setting string was \"%s\".", status,
+                            settings );
+               }
+
+/* Also check that the result buffer did not overflow. If it did,
+   memory will probably have been corrupted but this cannot be
+   prevented with "vsprintf" (although we try and make the buffer
+   large enough). Report the error and abort. */
+            } else if ( nc > buff_len ) {
+               if( astOK ) {
+                  astError( AST__ATSER, "astVSet(%s): Internal buffer overflow "
+                            "while formatting an attribute setting - the result "
+                            "exceeds %d characters.", status, astGetClass( this ),
+                            buff_len );
+                  astError( AST__ATSER, "The setting string was \"%s\".", status,
+                            settings );
+               }
+
+/* If all is OK, loop to process each formatted attribute assignment
+   (these are now separated by '\n' characters). */
+	    } else {
+               assign = buff2;
+               while ( assign ) {
+
+/* Change the '\n' at the end of each assignment to a null to
+   terminate it. */
+                  if ( ( assign_end = strchr( assign, '\n' ) ) ) {
+                     *assign_end = '\0';
+                  }
+
+/* Before making the assignment, loop to remove white space and upper
+   case characters from the attribute name. */
+                  lo = 1;
+                  tq = -1;
+                  quoted = 0;
+                  for ( i = j = 0; assign[ i ]; i++ ) {
+
+/* Note when an '=' sign is encountered (this signals the end of the
+   attribute name). */
+                     if ( assign[ i ] == '=' ) lo = 0;
+
+/* Before the '=' sign, convert all characters to lower case and move
+   everything to the left to eliminate white space. Afer the '=' sign,
+   copy all characters to their new location unchanged, except for any
+   delimiting quotes, which are removed. astSetC replaces commas in the
+   attribute value by '\r' characters. Reverse this now. */
+                     if ( !lo || !isspace( assign[ i ] ) ) {
+                        if( assign[ i ] == '\r' ) {
+                           assign[ j++ ] = ',';
+
+                        } else if( lo ) {
+                           assign[ j++ ] = tolower( assign[ i ] );
+
+                        } else {
+                           assign[ j++ ] = assign[ i ];
+
+                           if( tq > 0 && !isspace( assign[ i ] ) ) {
+                              if( assign[ i ] == '"' ) {
+                                 quoted = 1;
+                                 j--;
+                              }
+                              tq = 0;
+                           }
+
+                        }
+                     }
+
+/* If the current character is the initial '=' sign, set "tq" positive,
+   meaning "check if the next non-space character is a quote". */
+                     if ( assign[ i ] == '=' && tq == -1 ) tq = 1;
+                  }
+
+/* if the value was quoted. remove the trailing quote. */
+                  if( quoted ) {
+                     j--;
+                     while( isspace( assign[ j ] ) ) j--;
+                     if( assign[ j ] == '"' ) j--;
+                     j++;
+                  }
+
+/* Terminate the revised assignment string and pass it to astSetAttrib
+   to make the assignment (unless the string was all blank, in which
+   case we ignore it). */
+                  assign[ j ] = '\0';
+                  if ( j ) {
+
+/* If there are no characters to the right of the equals sign append a
+   space after the equals sign. Without this, a string such as "Title="
+   would not be succesfully matched against the attribute name "Title"
+   within SetAttrib. */
+                     if( assign[ j - 1 ] == '=' ) {
+                        buff3 = astStore( NULL, assign,
+                                          (size_t) j + 2 );
+                        if ( astOK ) {
+                           buff3[ j ] = ' ';
+                           buff3[ j + 1 ] = '\0';
+                           astSetAttrib( this, buff3 );
+                        }
+                        buff3 = astFree( buff3 );
+
+                     } else {
+                        astSetAttrib( this, assign );
+                     }
+                  }
+
+/* Check for errors and abort if any assignment fails. Otherwise,
+   process the next assignment substring. */
+                  if ( !astOK ) break;
+                  assign = assign_end ? assign_end + 1 : NULL;
+               }
+	    }
+         }
+
+/* Free the memory allocated for string buffers. */
+         buff2 = astFree( buff2 );
+         dyn_buf = astFree( dyn_buf );
+      }
+      buff1 = astFree( buff1 );
+   }
+}
+#undef ERRBUF_LEN
+#undef MIN_BUFF_LEN
+
+/* Attribute access functions. */
+/* --------------------------- */
+/*
+*att++
+*  Name:
+*     Class
+
+*  Purpose:
+*     Object class name.
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     Character string, read-only.
+
+*  Description:
+*     This attribute gives the name of the class to which an Object
+*     belongs.
+
+*  Applicability:
+*     Object
+*        All Objects have this attribute.
+*att--
+*/
+
+/*
+*att++
+*  Name:
+*     ID
+
+*  Purpose:
+*     Object identification string.
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     String.
+
+*  Description:
+*     This attribute contains a string which may be used to identify
+*     the Object to which it is attached. There is no restriction on
+*     the contents of this string, which is not used internally by the
+*     AST library, and is simply returned without change when
+*     required. The default value is an empty string.
+*
+*     An identification string can be valuable when, for example,
+c     several Objects have been stored in a file (using astWrite) and
+f     several Objects have been stored in a file (using AST_WRITE) and
+c     are later retrieved (using astRead). Consistent use of the ID
+f     are later retrieved (using AST_READ). Consistent use of the ID
+*     attribute allows the retrieved Objects to be identified without
+*     depending simply on the order in which they were stored.
+*
+*     This attribute may also be useful during debugging, to
+c     distinguish similar Objects when using astShow to display them.
+f     distinguish similar Objects when using AST_SHOW to display them.
+
+*  Applicability:
+*     Object
+*        All Objects have this attribute.
+
+*  Notes:
+*     - Unlike most other attributes, the value of the ID attribute is
+*     not transferred when an Object is copied. Instead, its value is
+*     undefined (and therefore defaults to an empty string) in any
+*     copy. However, it is retained in any external representation of
+c     an Object produced by the astWrite function.
+f     an Object produced by the AST_WRITE routine.
+*att--
+*/
+/* Clear the ID value by freeing the allocated memory and assigning a
+   NULL pointer. */
+astMAKE_CLEAR(Object,ID,id,astFree( this->id ))
+
+/* If the ID value is not set, supply a default in the form of a
+   pointer to the constant string "". */
+astMAKE_GET(Object,ID,const char *,NULL,( this->id ? this->id : "" ))
+
+/* Set an ID value by freeing any previously allocated memory,
+   allocating new memory and storing the string. */
+astMAKE_SET(Object,ID,const char *,id,astStore( this->id, value,
+                                                strlen( value ) + (size_t) 1 ))
+
+/* The ID value is set if the pointer to it is not NULL. */
+astMAKE_TEST(Object,ID,( this->id != NULL ))
+
+/*
+*att++
+*  Name:
+*     Ident
+
+*  Purpose:
+*     Permanent Object identification string.
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     String.
+
+*  Description:
+*     This attribute is like the ID attribute, in that it contains a
+*     string which may be used to identify the Object to which it is
+*     attached. The only difference between ID and Ident is that Ident
+*     is transferred when an Object is copied, but ID is not.
+
+*  Applicability:
+*     Object
+*        All Objects have this attribute.
+
+*att--
+*/
+/* Clear the Ident value by freeing the allocated memory and assigning a
+   NULL pointer. */
+astMAKE_CLEAR(Object,Ident,ident,astFree( this->ident ))
+
+/* If the Ident value is not set, supply a default in the form of a
+   pointer to the constant string "". */
+astMAKE_GET(Object,Ident,const char *,NULL,( this->ident ? this->ident : "" ))
+
+/* Set an Ident value by freeing any previously allocated memory,
+   allocating new memory and storing the string. */
+astMAKE_SET(Object,Ident,const char *,ident,astStore( this->ident, value,
+                                                strlen( value ) + (size_t) 1 ))
+
+/* The Ident value is set if the pointer to it is not NULL. */
+astMAKE_TEST(Object,Ident,( this->ident != NULL ))
+
+/*
+*att++
+*  Name:
+*     UseDefs
+
+*  Purpose:
+*     Use default values for unspecified attributes?
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     Integer (boolean).
+
+*  Description:
+*     This attribute specifies whether default values should be used
+*     internally for object attributes which have not been assigned a
+*     value explicitly. If a non-zero value (the default) is supplied for
+*     UseDefs, then default values will be used for attributes which have
+*     not explicitly been assigned a value. If zero is supplied for UseDefs,
+*     then an error will be reported if an attribute for which no explicit
+*     value has been supplied is needed internally within AST.
+*
+*     Many attributes (including the UseDefs attribute itself) are unaffected
+*     by the setting of the UseDefs attribute, and default values will always
+*     be used without error for such attributes. The "Applicability:" section
+*     below lists the attributes which are affected by the setting of UseDefs.
+
+*     Note, UseDefs only affects access to attributes internally within
+*     AST. The public accessor functions such as
+c     astGetC
+f     AST_GETC
+*     is unaffected by the UseDefs attribute - default values will always
+*     be returned if no value has been set. Application code should use the
+c     astTest
+f     AST_TEST
+*     function if required to determine if a value has been set for an
+*     attribute.
+
+*  Applicability:
+*     Object
+*        All Objects have this attribute, but ignore its setting except
+*        as described below for individual classes.
+*     FrameSet
+*        The default value of UseDefs for a FrameSet is redefined to be
+*        the UseDefs value of its current Frame.
+*     CmpFrame
+*        The default value of UseDefs for a CmpFrame is redefined to be
+*        the UseDefs value of its first component Frame.
+*     Region
+*        The default value of UseDefs for a Region is redefined to be
+*        the UseDefs value of its encapsulated Frame.
+*     Frame
+*        If UseDefs is zero, an error is reported when aligning Frames if the
+*        Epoch, ObsLat or ObsLon attribute is required but has not been
+*        assigned a value explicitly.
+*     SkyFrame
+*        If UseDefs is zero, an error is reported when aligning SkyFrames
+*        if any of the following attributes are required but have not been
+*        assigned a value explicitly: Epoch, Equinox.
+*     SpecFrame
+*        If UseDefs is zero, an error is reported when aligning SpecFrames
+*        if any of the following attributes are required but have not been
+*        assigned a value explicitly: Epoch, RefRA, RefDec, RestFreq,
+*        SourceVel, StdOfRest.
+*     DSBSpecFrame
+*        If UseDefs is zero, an error is reported when aligning DSBSpecFrames
+*        or when accessing the ImagFreq attribute if any of the following
+*        attributes are required but have not been assigned a value explicitly:
+*        Epoch, DSBCentre, IF.
+*att--
+*/
+astMAKE_CLEAR(Object,UseDefs,usedefs,CHAR_MAX)
+astMAKE_GET(Object,UseDefs,int,1,((this->usedefs!=CHAR_MAX)?this->usedefs:1))
+astMAKE_SET(Object,UseDefs,int,usedefs,((value)?1:0))
+astMAKE_TEST(Object,UseDefs,(this->usedefs!=CHAR_MAX))
+
+/*
+*att++
+*  Name:
+*     Nobject
+
+*  Purpose:
+*     Number of Objects in class.
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     Integer, read-only.
+
+*  Description:
+*     This attribute gives the total number of Objects currently in
+*     existence in the same class as the Object whose attribute value
+*     is requested. This count does not include Objects which belong
+*     to derived (more specialised) classes.
+*
+*     This attribute is mainly intended for debugging. It can be used
+*     to detect whether Objects which should have been deleted have,
+*     in fact, been deleted.
+
+*  Applicability:
+*     Object
+*        All Objects have this attribute.
+*att--
+*/
+
+/*
+*att++
+*  Name:
+*     ObjSize
+
+*  Purpose:
+*     The in-memory size of the Object.
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     Integer, read-only.
+
+*  Description:
+*     This attribute gives the total number of bytes of memory used by
+*     the Object. This includes any Objects which are encapsulated within
+*     the supplied Object.
+
+*  Applicability:
+*     Object
+*        All Objects have this attribute.
+*att--
+*/
+
+/*
+*att++
+*  Name:
+*     RefCount
+
+*  Purpose:
+*     Count of active Object pointers.
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     Integer, read-only.
+
+*  Description:
+*     This attribute gives the number of active pointers associated
+*     with an Object. It is modified whenever pointers are created or
+c     annulled (by astClone, astAnnul or astEnd for example). The count
+f     annulled (by AST_CLONE, AST_ANNUL or AST_END for example). The count
+*     includes the initial pointer issued when the Object was created.
+*
+*     If the reference count for an Object falls to zero as the result
+*     of annulling a pointer to it, then the Object will be deleted.
+
+*  Applicability:
+*     Object
+*        All Objects have this attribute.
+*att--
+*/
+
+/* Standard class functions. */
+/* ========================= */
+/*
+*+
+*  Name:
+*     astCheck<Class>
+
+*  Purpose:
+*     Validate class membership.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "class.h"
+*     Ast<Class> *astCheck<Class>( Ast<Class> *this )
+
+*  Class Membership:
+*     <Class> class function.
+
+*  Description:
+*     This function validates membership of the class called <Class>,
+*     or of any class derived from it. If the Object is not a member,
+*     or the pointer supplied does not identify a valid Object, an
+*     error is reported and the global error status is set to
+*     AST__OBJIN.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+
+*  Returned Value:
+*     The function always returns a copy of the "this" pointer
+*     (whether it finds it valid or not).
+
+*  Notes:
+*     - Each class provides a function (astCheck<Class>) of this form,
+*     where <Class> and <class> are replaced by the class name (with
+*     appropriate capitalisation).
+*     - Normal error status checking is performed, so this function
+*     will not execute if the global error status is set on entry (the
+*     usual function value will be returned, however).
+*     - This function is primarily intended for validating Object
+*     pointers passed to member functions as part of a class
+*     interface.
+*-
+*/
+
+/* Implement the astCheckObject function using the macro defined for this
+   purpose in the "object.h" header file. */
+astMAKE_CHECK(Object)
+
+int astIsAObject_( const AstObject *this, int *status ) {
+/*
+*++
+*  Name:
+c     astIsA<Class>
+f     AST_ISA<CLASS>
+
+*  Purpose:
+*     Test membership of a class by an Object.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "class.h"
+c     int astIsA<Class>( const Ast<Class> *this )
+f     RESULT = AST_ISA<CLASS>( THIS, STATUS )
+
+*  Class Membership:
+*     Class function.
+
+*  Description:
+*     This is a family of functions which test whether an Object is a
+c     member of the class called <Class>, or of any class derived from
+f     member of the class called <CLASS>, or of any class derived from
+*     it.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the Object.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astIsA<Class>()
+c        One if the Object belongs to the class called <Class> (or to a
+c        class derived from it), otherwise zero.
+f     AST_ISA<CLASS> = LOGICAL
+f        .TRUE. if the Object belongs to the class called <CLASS> (or to
+f        a class derived from it), otherwise .FALSE..
+
+*  Applicability:
+*     Object
+*        These functions apply to all Objects.
+
+*  Examples:
+c     member = astIsAFrame( obj );
+c        Tests whether Object "obj" is a member of the Frame class, or
+c        of any class derived from a Frame.
+f     MEMBER = AST_ISAFRAME( OBJ, STATUS );
+f        Tests whether Object OBJ is a member of the Frame class, or
+f        of any class derived from a Frame.
+
+*  Notes:
+c     - Every AST class provides a function (astIsA<Class>) of this
+c     form, where <Class> should be replaced by the class name.
+f     - Every AST class provides a function (AST_ISA<CLASS>) of this
+f     form, where <CLASS> should be replaced by the class name.
+c     - This function attempts to execute even if the AST error status
+c     is set
+f     - This function attempts to execute even if STATUS is set to an
+f     error value
+*     on entry, although no further error report will be made
+*     if it subsequently fails under these circumstances.
+c     - A value of zero will be returned if this function should fail
+f     - A value of .FALSE. will be returned if this function should fail
+*     for any reason. In particular, it will fail if the pointer
+*     supplied does not identify an Object of any sort.
+*--
+*/
+
+/* Local Variables: */
+   int valid;                    /* Valid object? */
+
+/* Since this is the base class, the implementation of this function
+   differs from that in derived classes (in that it fails and
+   potentially reports an error if the returned result is zero). */
+
+/* Initialise. */
+   valid = 0;
+
+/* Check if a NULL pointer was supplied (this can never be valid). If
+   OK, check if the Object contains the correct "magic number" in its
+   check field. */
+   if ( !this || ( this->check != Magic( this, this->size, status ) ) ) {
+
+/* If it is not a valid Object, then report an error (but only if the
+   global error status has not already been set). */
+      if ( astOK ) {
+         astError( AST__OBJIN, "astIsAObject(%s): Invalid Object pointer "
+                   "given (points at address %p).", status, astGetClass( this ),
+                   (void *) this );
+      }
+
+/* Otherwise, note that the Object is valid. */
+   } else {
+      valid = 1;
+   }
+
+/* Return the result. */
+   return valid;
+}
+
+void astInitObjectVtab_(  AstObjectVtab *vtab, const char *name, int *status ) {
+/*
+*+
+*  Name:
+*     astInitObjectVtab
+
+*  Purpose:
+*     Initialise a virtual function table for a Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astInitObjectVtab( AstObjectVtab *vtab, const char *name )
+
+*  Class Membership:
+*     Object vtab initialiser.
+
+*  Description:
+*     This function initialises the component of a virtual function
+*     table which is used by the Object class.
+
+*  Parameters:
+*     vtab
+*        Pointer to the virtual function table.
+*     name
+*        Pointer to a constant null-terminated character string which contains
+*        the name of the class to which the virtual function table belongs (it
+*        is this pointer value that will subsequently be returned by the Object
+*        astClass function).
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   int ivtab;                    /* Index of next entry in known_vtabs */
+
+/* Check the local error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Initialise the contents of the class identifier. Since this is the
+   base class, we assign null values to the fields. */
+   vtab->id.check = NULL;
+   vtab->id.parent = NULL;
+
+/* Store pointers to the member functions (implemented here) that provide
+   virtual methods for this class. */
+   vtab->Clear = Clear;
+   vtab->ClearAttrib = ClearAttrib;
+   vtab->ClearID = ClearID;
+   vtab->ClearIdent = ClearIdent;
+   vtab->Dump = Dump;
+   vtab->Equal = Equal;
+   vtab->GetAttrib = GetAttrib;
+   vtab->GetID = GetID;
+   vtab->GetIdent = GetIdent;
+   vtab->HasAttribute = HasAttribute;
+   vtab->Same = Same;
+   vtab->SetAttrib = SetAttrib;
+   vtab->SetID = SetID;
+   vtab->SetIdent = SetIdent;
+   vtab->Show = Show;
+   vtab->TestAttrib = TestAttrib;
+   vtab->TestID = TestID;
+   vtab->TestIdent = TestIdent;
+   vtab->EnvSet = EnvSet;
+   vtab->VSet = VSet;
+   vtab->Cast = Cast;
+   vtab->GetObjSize = GetObjSize;
+   vtab->CleanAttribs = CleanAttribs;
+
+   vtab->TestUseDefs = TestUseDefs;
+   vtab->SetUseDefs = SetUseDefs;
+   vtab->ClearUseDefs = ClearUseDefs;
+   vtab->GetUseDefs = GetUseDefs;
+
+#if defined(THREAD_SAFE)
+   vtab->ManageLock = ManageLock;
+#endif
+
+/* Store the pointer to the class name. */
+   vtab->class = name;
+
+/* Initialise the count of active objects and the number of destructors,
+   copy constructors and dump functions. */
+   vtab->nobject = 0;
+   vtab->ndelete = 0;
+   vtab->ncopy = 0;
+   vtab->ndump = 0;
+
+/* Initialise the arrays of destructor, copy constructor and dump
+   function pointers. */
+   vtab->delete = NULL;
+   vtab->copy = NULL;
+   vtab->dump = NULL;
+   vtab->dump_class = NULL;
+   vtab->dump_comment = NULL;
+
+/* Initialise the default attributes to use when creating objects. */
+   vtab->defaults = NULL;
+
+/* The virtual function table for each class contains a list of pointers
+   to memory blocks which have previously been used to store an Object of
+   the same class, but which have since been deleted using astDelete.
+   These memory blocks are free to be re-used when a new Object of the
+   same class is initialised. This saves on the overheads associated with
+   continuously allocating small blocks of memory using malloc. */
+   vtab->nfree = 0;
+   vtab->free_list = NULL;
+
+/* Add the supplied virtual function table pointer to the end of the list
+   of known vtabs. */
+   ivtab = nvtab++;
+
+   astBeginPM;
+   known_vtabs = astGrow( known_vtabs, nvtab, sizeof( AstObjectVtab *) );
+   astEndPM;
+
+   if( astOK && known_vtabs ) known_vtabs[ ivtab ] = vtab;
+
+/* Fill a pointer value with zeros (not necessarily the same thing as a
+   NULL pointer) for subsequent use. */
+   (void) memset( &zero_ptr, 0, sizeof( AstObject * ) );
+
+/* If we have just initialised the vtab for the current class, indicate
+   that the vtab is now initialised. */
+   if( vtab == &class_vtab ) class_init = 1;
+}
+
+AstObject *astInitObject_( void *mem, size_t size, int init,
+                           AstObjectVtab *vtab, const char *name, int *status ) {
+/*
+*+
+*  Name:
+*     astInitObject
+
+*  Purpose:
+*     Initialise an Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astInitObject( void *mem, size_t size, int init,
+*                               AstObjectVtab *vtab, const char *name )
+
+*  Class Membership:
+*     Object initialiser.
+
+*  Description:
+*     This function is provided for use by class implementations to initialise
+*     a new Object. It allocates memory (if necessary) to accommodate the
+*     Object plus any additional data associated with the derived class. It
+*     then initialises an Object structure at the start of this memory. If the
+*     "init" flag is set, it also initialises the contents of a virtual
+*     function table for an Object at the start of the memory passed via the
+*     "vtab" parameter.
+
+*  Parameters:
+*     mem
+*        A pointer to the memory in which the Object is to be initialised.
+*        This must be of sufficient size to accommodate the Object data
+*        (sizeof(Object)) plus any data used by the derived class. If a value
+*        of NULL is given, this function will allocate the memory itself using
+*        the "size" parameter to determine its size.
+*     size
+*        The amount of memory used by the Object (plus derived class data).
+*        This will be used to allocate memory if a value of NULL is given for
+*        the "mem" parameter. This value is also stored in the Object
+*        structure, so a valid value must be supplied even if not required for
+*        allocating memory.
+*     init
+*        A logical flag indicating if the Object's virtual function table is
+*        to be initialised. If this value is non-zero, the virtual function
+*        table will be initialised by this function.
+*     vtab
+*        Pointer to the start of the virtual function table to be associated
+*        with the new Object.
+*     name
+*        Pointer to a constant null-terminated character string which contains
+*        the name of the class to which the new object belongs (it is this
+*        pointer value that will subsequently be returned by the Object
+*        astClass function).
+
+*  Returned Value:
+*     A pointer to the new Object.
+
+*  Notes:
+*     -  A null pointer will be returned if this function is invoked with the
+*     global error status set, or if it should fail for any reason.
+*-
+*/
+
+/* Local Variables: */
+   AstObject *new;               /* Pointer to new Object */
+
+/* Initialise. */
+   new = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return new;
+
+/* Determine if memory must be allocated dynamically. If so, use the last
+   block of memory in the list of previously allocated but currently
+   unused blocks identified by the vtab "free_list" array, reducing the
+   length of the free list by one, and nullifying the entry in the list
+   for safety. If the list is originally empty, allocate memory for a new
+   object using astMalloc. */
+   if( !mem ) {
+      if( object_caching ) {
+         if( vtab->nfree > 0 ) {
+            mem = vtab->free_list[ --(vtab->nfree) ];
+            vtab->free_list[ vtab->nfree ] = NULL;
+            if( astSizeOf( mem ) != size && astOK ) {
+               astError( AST__INTER, "astInitObject(%s): Free block has size "
+                         "%d but the %s requires %d bytes (internal AST "
+                         "programming error).", status, vtab->class,
+                         (int) astSizeOf( mem ), vtab->class, (int) size );
+            }
+         } else {
+            mem = astMalloc( size );
+         }
+
+      } else {
+         mem = astMalloc( size );
+      }
+
+/* If memory had already been allocated, adjust the "size" value to match
+   the size of the allocated memory. */
+   } else {
+      size = astSizeOf( mem );
+   }
+
+/* Obtain a pointer to the new Object. */
+   if ( astOK ) {
+      new = (AstObject *) mem;
+
+/* Zero the entire new Object structure (to prevent accidental re-use
+   of any of its values after deletion). */
+      (void) memset( new, 0, size );
+
+/* If necessary, initialise the virtual function table. */
+/* ---------------------------------------------------- */
+      if ( init ) astInitObjectVtab( vtab, name );
+      if( astOK ) {
+
+/* Initialise the Object data. */
+/* --------------------------- */
+/* Store a unique "magic" value in the Object structure. This will be
+   used (e.g. by astIsAObject) to determine if a pointer identifies a
+   valid Object. Note that this differs from the practice in derived
+   classes, where this number is stored in the virtual function
+   table. We take a different approach here so that we need not follow
+   a pointer to the virtual function table obtained from a structure
+   that hasn't yet been validated as an Object. This minimises the
+   risk of a memory access violation. */
+         new->check = Magic( new, size, status );
+
+/* Associate the Object with its virtual function table. */
+         new->vtab = vtab;
+
+/* Store the Object size and note if its memory was dynamically allocated. */
+         new->size = size;
+         new->dynamic = astIsDynamic( new );
+
+/* Initialise the reference count (of Object pointers in use). */
+         new->ref_count = 1;
+
+/* Initialise the ID strings. */
+         new->id = NULL;
+         new->ident = NULL;
+
+/* Use default values for unspecified attributes. */
+         new->usedefs = CHAR_MAX;
+
+/* Increment the count of active Objects in the virtual function table.
+   Use the count as a unique identifier (unique within the class) for
+   the Object. */
+         new->iref = vtab->nobject++;
+
+/* Initialise the pointer to an external object that acts as a proxy for
+   the AST Object within foreign language interfaces. */
+         new->proxy = NULL;
+      }
+
+/* If an error occurred, clean up by deleting the new Object. Otherwise
+   lock the object for use by the currently executing thread. */
+      if ( !astOK ) {
+         new = astDelete( new );
+
+#ifdef THREAD_SAFE
+      } else {
+         if( pthread_mutex_init( &(new->mutex1), NULL ) != 0 && astOK ) {
+            astError( AST__INTER, "astInitObject(%s): Failed to "
+                      "initialise POSIX mutex1 for the new Object.", status,
+                      vtab->class );
+         }
+         if( pthread_mutex_init( &(new->mutex2), NULL ) != 0 && astOK ) {
+            astError( AST__INTER, "astInitObject(%s): Failed to "
+                      "initialise POSIX mutex2 for the new Object.", status,
+                      vtab->class );
+         }
+         new->locker = -1;
+         new->globals = NULL;
+         (void) ManageLock( new, AST__LOCK, 0, NULL, status );
+         if( !astOK ) new = astDelete( new );
+#endif
+      }
+   }
+
+/* Return a pointer to the new Object. */
+   return new;
+}
+
+AstObject *astLoadObject_( void *mem, size_t size,
+                           AstObjectVtab *vtab, const char *name,
+                           AstChannel *channel, int *status ) {
+/*
+*+
+*  Name:
+*     astLoadObject
+
+*  Purpose:
+*     Load an Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astLoadObject( void *mem, size_t size,
+*                               AstObjectVtab *vtab, const char *name,
+*                               AstChannel *channel )
+
+*  Class Membership:
+*     Object loader.
+
+*  Description:
+*     This function is provided to load a new Object using data read
+*     from a Channel, and to allocate memory for it if necessary.
+*
+*     If the "init" flag is set, it also initialises the contents of a
+*     virtual function table for an Object at the start of the memory
+*     passed via the "vtab" parameter.
+
+*  Parameters:
+*     mem
+*        A pointer to the memory into which the Object is to be
+*        loaded.  This must be of sufficient size to accommodate the
+*        Object data (sizeof(Object)) plus any data used by derived
+*        classes. If a value of NULL is given, this function will
+*        allocate the memory itself using the "size" parameter to
+*        determine its size.
+*     size
+*        The amount of memory used by the Object (plus derived class
+*        data).  This will be used to allocate memory if a value of
+*        NULL is given for the "mem" parameter. This value is also
+*        stored in the Object structure, so a valid value must be
+*        supplied even if not required for allocating memory.
+*
+*        If the "vtab" parameter is NULL, the "size" value is ignored
+*        and sizeof(AstObject) is used instead.
+*     vtab
+*        Pointer to the start of the virtual function table to be
+*        associated with the new Object. If this is NULL, a pointer to
+*        the (static) virtual function table for the Object class is
+*        used instead.
+*     name
+*        Pointer to a constant null-terminated character string which
+*        contains the name of the class to which the new Object
+*        belongs (it is this pointer value that will subsequently be
+*        returned by the astGetClass method).
+*
+*        If the "vtab" parameter is NULL, the "name" value is ignored
+*        and a pointer to the string "Object" is used instead.
+
+*  Returned Value:
+*     A pointer to the new Object.
+
+*  Notes:
+*     - A null pointer will be returned if this function is invoked
+*     with the global error status set, or if it should fail for any
+*     reason.
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   AstObject *new;               /* Pointer to the new Object */
+
+/* Initialise. */
+   new = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return new;
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(channel);
+
+/* If a NULL virtual function table has been supplied, then this is
+   the first loader to be invoked for this Object. In this case the
+   Object belongs to this class, so supply appropriate values for
+   initialising it and its virtual function table. */
+   if ( !vtab ) {
+      size = sizeof( AstObject );
+      vtab = &class_vtab;
+      name = "Object";
+
+/* If required, initialise the virtual function table for this class. */
+      if ( !class_init ) {
+         astInitObjectVtab( vtab, name );
+         class_init = 1;
+      }
+   }
+
+/* There is no parent class to load, so simply initialise a new Object
+   structure as if a new Object were being created from scratch. */
+   new = astInitObject( mem, size, 0, vtab, name );
+   if ( astOK ) {
+
+/* Read input data. */
+/* ================ */
+/* Request the input Channel to read all the input data appropriate to
+   this class into the internal "values list". */
+      astReadClassData( channel, "Object" );
+
+/* Now read each individual data item from this list and use it to
+   initialise the appropriate instance variable(s) for this class. */
+      new->id = astReadString( channel, "id", NULL );
+      new->ident = astReadString( channel, "ident", NULL );
+      new->usedefs = astReadInt( channel, "usedfs", CHAR_MAX );
+
+/* We simply read the values for the read-only attributes (just in
+   case they've been un-commented in the external representation) and
+   discard them. This prevents any possibility of error due to un-read
+   input. */
+      (void) astReadInt( channel, "refcnt", 0 );
+      (void) astReadInt( channel, "nobj", 0 );
+
+/* Initialise the pointer to an external object that acts as a proxy for
+   the AST Object within foreign language interfaces. */
+      new->proxy = NULL;
+
+/* If an error occurred, clean up by deleting the new Object. */
+      if ( !astOK ) new = astDelete( new );
+   }
+
+/* Return the new Object pointer. */
+   return new;
+}
+
+/* Virtual function interfaces. */
+/* ============================ */
+/* These provide the external interface to the virtual functions defined by
+   this class. Each simply checks the global error status and then locates and
+   executes the appropriate member function, using the function pointer stored
+   in the object's virtual function table (this pointer is located using the
+   astMEMBER macro defined in "object.h").
+
+   Note that the member function may not be the one defined here, as it may
+   have been over-ridden by a derived class. However, it should still have the
+   same interface. */
+void astClear_( AstObject *this, const char *attrib, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Object,Clear))( this, attrib, status );
+}
+void astClearAttrib_( AstObject *this, const char *attrib, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Object,ClearAttrib))( this, attrib, status );
+}
+void astDump_( AstObject *this, AstChannel *channel, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Object,Dump))( this, channel, status );
+}
+
+#if defined(THREAD_SAFE)
+int astManageLock_( AstObject *this, int mode, int extra, AstObject **fail,
+                    int *status ) {
+   if( !this ) return 0;
+   return (**astMEMBER(this,Object,ManageLock))( this, mode, extra, fail, status );
+}
+#endif
+
+int astEqual_( AstObject *this, AstObject *that, int *status ) {
+   if ( !astOK ) return 0;
+   if( this == that ) return 1;
+   return (**astMEMBER(this,Object,Equal))( this, that, status );
+}
+const char *astGetAttrib_( AstObject *this, const char *attrib, int *status ) {
+   if ( !astOK ) return NULL;
+   return (**astMEMBER(this,Object,GetAttrib))( this, attrib, status );
+}
+void astSetAttrib_( AstObject *this, const char *setting, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Object,SetAttrib))( this, setting, status );
+}
+void astShow_( AstObject *this, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Object,Show))( this, status );
+}
+int astTestAttrib_( AstObject *this, const char *attrib, int *status ) {
+   if ( !astOK ) return 0;
+   return (**astMEMBER(this,Object,TestAttrib))( this, attrib, status );
+}
+void astEnvSet_( AstObject *this, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Object,EnvSet))( this, status );
+}
+void astVSet_( AstObject *this, const char *settings, char **text, va_list args, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Object,VSet))( this, settings, text, args, status );
+}
+int astGetObjSize_( AstObject *this, int *status ) {
+   if ( !astOK || !this ) return 0;
+   return (**astMEMBER(this,Object,GetObjSize))( this, status );
+}
+void astCleanAttribs_( AstObject *this, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Object,CleanAttribs))( this, status );
+}
+AstObject *astCast_( AstObject *this, AstObject *obj, int *status ) {
+   if ( !astOK ) return NULL;
+   return (**astMEMBER(this,Object,Cast))( this, obj, status );
+}
+int astSame_( AstObject *this, AstObject *that, int *status ) {
+   if ( !astOK ) return 0;
+   return (**astMEMBER(this,Object,Same))( this, that, status );
+}
+int astHasAttribute_( AstObject *this, const char *attrib, int *status ) {
+   if ( !astOK ) return 0;
+   return (**astMEMBER(this,Object,HasAttribute))( this, attrib, status );
+}
+
+/* External interface. */
+/* =================== */
+/* The following relates to the external interface to Objects and not
+   specifically to the implementation of the Object class itself
+   (although it contains external functions which replace the internal
+   versions defined earlier). */
+
+
+/* Type Definitions. */
+/* ----------------- */
+/* Define the Handle structure. This is attached to Objects when they
+   are accessed via the public (external, user-callable) interface.
+   Handles provide a buffer between the Object identifiers issued to
+   external users and the naked C pointers used to handle Objects
+   internally. They also implement the context levels used by
+   astBegin, astEnd, astExempt and astExport (which are only available
+   to external users). */
+typedef struct Handle {
+   AstObject *ptr;               /* C Pointer to the associated Object */
+   int context;                  /* Context level for this Object */
+   int check;                    /* Check value to ensure validity */
+
+#if defined(THREAD_SAFE)
+   int thread;                   /* Identifier for owning thread */
+#endif
+
+#if defined(MEM_DEBUG)
+   int id;                       /* The id associated with the memory block
+                                    holding the Object last associated with
+                                    this handle. */
+   AstObjectVtab *vtab;          /* Pointer to the firtual function table of
+                                    the Object last associated with this
+                                    handle. */
+#endif
+
+/* Links between Handles are implemented using integer offsets rather
+   than through pointers. */
+   int flink;                    /* Backward link to previous Handle */
+   int blink;                    /* Forward link to next Handle */
+
+/* Information that records where the Handle was created. */
+   const char *routine;          /* Routine name */
+   const char *file;             /* File name */
+   int line;                     /* Line number */
+
+} Handle;
+
+/* Define a union with an overlapping int and AstObject*. This is used
+   to transfer an integer bit pattern into and out of a pointer
+   variable used to store an Object identifier. This avoids any
+   implementation dependent aspects of integer-to-pointer
+   conversions. */
+typedef union IdUnion {
+   AstObject *pointer;
+   int integer;
+} IdUnion;
+
+/* Define a union which allows a bit pattern to be accessed as a
+   signed or unsigned int. */
+typedef union MixedInts {
+   int i;
+   unsigned u;
+} MixedInts;
+
+/* Static Variables. */
+/* ----------------- */
+/* The array of Handle structures is a pool of resources available to all
+   threads. Each thread has its own conext level and its own "active_handles"
+   array to identify the first Handle at each context level. */
+static Handle *handles = NULL; /* Pointer to allocated array of Handles */
+static int free_handles = -1; /* Offset to head of free Handle list */
+static int nhandles = 0; /* Number of Handles in "handles" array */
+static unsigned nids = 0; /* Number of IDs issued to external users */
+
+#if defined(THREAD_SAFE)
+static int unowned_handles = -1; /* Offset to head of unowned Handle
+                                    list. In a single threaded environment,
+                                    all handles must be owned by a thread. */
+#endif
+
+#ifdef MEM_DEBUG
+static int Watched_Handle = -1; /* A handle index to be watched. Activity
+                                   on this handle is reported using
+                                   astHandleUse and astHandleAlarm. */
+#endif
+
+
+/* External Interface Function Prototypes. */
+/* --------------------------------------- */
+/* MYSTATIC should normally be set to "static" to make the following
+   function have local symbols. But it may be set to blank for debugging
+   purposes in order to enable these functions to appear in a backtrace
+   such as produced by the astBacktrace function. */
+#define MYSTATIC
+
+/* Private functions associated with the external interface. */
+MYSTATIC AstObject *AssocId( int, int * );
+MYSTATIC int CheckId( AstObject *, int, int * );
+MYSTATIC void AnnulHandle( int, int * );
+MYSTATIC void InitContext( int * );
+MYSTATIC void InsertHandle( int, int *, int * );
+MYSTATIC void RemoveHandle( int, int *, int * );
+
+#if defined(MEM_DEBUG)
+MYSTATIC void CheckList( int *, int * );
+MYSTATIC void CheckInList( int, int *, int, int * );
+MYSTATIC int CheckThread( int, int *, int * );
+MYSTATIC const char *HandleString( int, char * );
+MYSTATIC const char *HeadString( int *, char * );
+#endif
+
+
+/* The following functions have public prototypes only (i.e. no
+   protected prototypes), so we must provide local prototypes for use
+   within this module. */
+AstObject *astDeleteId_( AstObject *, int * );
+void astBegin_( void );
+void astEnd_( int * );
+void astExemptId_( AstObject *, int * );
+void astImportId_( AstObject *, int * );
+void astSetId_( void *, const char *, ... );
+void astLockId_( AstObject *, int, int * );
+void astUnlockId_( AstObject *, int, int * );
+
+
+/* External Interface Functions. */
+/* ----------------------------- */
+AstKeyMap *astActiveObjects_( const char *class, int subclass, int current,
+                              int *status ) {
+/*
+c++
+*  Name:
+*     astActiveObjects
+
+*  Purpose:
+*     Return pointers for all active Objects.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstKeyMap *astActiveObjects( const char *class, int subclass,
+*                                  int current )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns a KeyMap holding currently active AST Object
+*     pointers. Each entry in the KeyMap will have a key that is an AST
+*     class name such as "FrameSet", "SkyFrame", "ZoomMap", etc. The
+*     value of the entry will be a 1-dimensional list of pointers for
+*     objects of the same class. Note, the returned pointers should NOT
+*     be annulled when they are no longer needed.
+*
+*     The pointers to return in the KeyMap may be restricted either by
+*     class or by context level using the function arguments.
+
+*  Parameters:
+*     class
+*        If NULL, then the returned KeyMap will contain pointers ofr
+*        Objects of all classes. If not NULL, then "class" should be a
+*        pointer to a null-terminated string holding the name of an AST
+*        class. The returned KeyMap will contain pointers only for the
+*        specified class. See also "subclass".
+*     subclass
+*        A Boolean flag indicating if all subclasses of the class
+*        specified by "class" should be included in the returned KeyMap.
+*        If zero, then subclass objects are not returned. Otherwise they
+*        are returned. The supplied "subclass" value is ignored if
+*        "class" is NULL.
+*     current
+*        A Boolean flag indicating if the returned list of pointers
+*        should be restricted to pointers issued within the current AST
+*        object context (see astBegin and astEnd).
+
+*  Returned Value:
+*     astActiveObjects()
+*        A pointer to a new KeyMap holding the required object pointers.
+*        They KeyMap pointer should be annulled when it is no longer
+*        needed, but the object pointers within the KeyMap should not be
+*        annulled. A NULL pointer is returned if an error has occurred
+*        prior to calling this function.
+*
+*        The values stored in the KeyMap should be accessed as generic C
+*        pointers using the KeyMap "P" data type (e.g. using function
+*        astMapGetlemP etc).
+
+*  Notes:
+*     - This function will only return objects locked by the currently
+*     executing thread.
+*     - The KeyMap pointer returned by this function is not included in the
+*     list of active objects stored in the KeyMap.
+*     - Objects that were created using the Fortran interface will have a
+*     null "file" value and will have a routine name equal to the upper case
+*     Fortran routine that issued the pointer (e.g. "AST_CLONE", "AST_FRAME",
+*     etc).
+
+c--
+*/
+
+/* Local Variables: */
+   AstKeyMap *result;         /* Returned KeyMap */
+   astDECLARE_GLOBALS         /* Thread-specific global data */
+   int i;                     /* Loop count */
+   int ihandle;               /* Offset of Handle to be annulled */
+   AstObjectVtab *req_vtab;   /* Vtab for requested class */
+   Handle *handle;            /* Pointer to current Handle */
+   int generation_gap;        /* Hereditary relationshp between two classes */
+
+/* Check the global error status. */
+   if ( !astOK ) return NULL;
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Create an empty KeyMap to hold the results. */
+   result = astKeyMap( " ", status );
+
+/* If we will need to check if each object is a subclass of a specified
+   class, we need a pointer to the VTAB descriibing the specified class. */
+   req_vtab = NULL;
+   if( class && subclass ) {
+
+/* Loop round the vtab structures created by the currently executing thread. */
+      for( i = 0; i < nvtab; i++ ) {
+
+/* If the current vtab is for a class that matches the requested class,
+   store a pointer to the vtab. */
+         if( !strcmp( class, known_vtabs[ i ]->class ) ) {
+            req_vtab = known_vtabs[ i ];
+            break;
+         }
+      }
+   }
+
+/* Get exclusive access to the handles array. */
+   LOCK_MUTEX2;
+
+/* Get the index of the first Handle to check. If we are checking only the
+   current context level, then get this index from the appropriate element
+   of the active_handles array. Otherwise, we check the whole of the
+   handles array, starting at element zero. */
+   if( current && active_handles ) {
+      ihandle = active_handles[ context_level ];
+   } else {
+      ihandle = 0;
+   }
+
+/* Loop over the Handles array, starting from the above element. */
+   handle = handles + ihandle;
+   for( ; ihandle < nhandles; ihandle++,handle++ ) {
+
+/* Skip Handles that have no associated object. */
+      if( !handle->ptr ) continue;
+
+/* Skip handles that are in an unrequired context. */
+      if( current && handle->context != context_level ) continue;
+
+#if defined(THREAD_SAFE)
+/* Skip handles that are not locked for use by the current thread. */
+      if( handle->thread != AST__THREAD_ID ) continue;
+#endif
+
+/* If required, check that the current handle is for an object of the
+   specified class. */
+      if( class ) {
+
+/* Skip the handle if no VTAB was found for the requested class. */
+         if( !req_vtab ) continue;
+
+/* Get the generation gap between the current handle's object and the
+   specified class. */
+         generation_gap = astClassCompare( astVTAB( handle->ptr ), req_vtab );
+
+/* Skip the handle if it is not for the specified class or a subclass. */
+         if( generation_gap < 0 || generation_gap == AST__COUSIN ||
+                           ( generation_gap > 0 && !subclass ) ) continue;
+      }
+
+/* Get the integer identifier associated with the handle, convert it to a
+   pointer and append to the end of the KeyMap entry describing the handle's
+   class. */
+      astMapPutElemP( result, astGetClass( handle->ptr ), -1,
+                      astI2P( handle->check ) );
+   }
+
+/* Relinquish access to the handles array. */
+   UNLOCK_MUTEX2;
+
+/* Return the KeyMap. */
+   return result;
+}
+
+MYSTATIC void AnnulHandle( int ihandle, int *status ) {
+/*
+*  Name:
+*     AnnulHandle
+
+*  Purpose:
+*     Annul a Handle and its associated Object pointer.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void AnnulHandle( int ihandle, int *status )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function annuls an active Handle by annulling the Object
+*     pointer it is associated with, deactivating the Handle and
+*     returning it to the free Handle list for re-use.
+*
+*     The reference count for the associated Object is decremented by
+*     this function and the Object will be deleted if this reference
+*     count falls to zero.
+
+*  Parameters:
+*     ihandle
+*        Array offset that identifies the Handle to be annulled in the
+*        "handles" array. This is fully validated by this function.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Notes:
+*     - The Handle supplied should be active, otherwise an error will
+*     result and the Handle will not be touched (but no error report
+*     will be made if the global error status has already been set).
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   AstObject *ptr;               /* Object pointer */
+   int context;                  /* Context level where Handle was issued */
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Check that the handle offset supplied is valid and report an error
+   if it is not (but only if the global error status has not already
+   been set). */
+   if ( ( ihandle < 0 ) || ( ihandle >= nhandles ) ) {
+      if ( astOK ) {
+         astError( AST__INHAN, "astAnnulHandle: Invalid attempt to annul an "
+                   "Object Handle (no. %u).", status, ihandle );
+         astError( AST__INHAN, "This Handle number is not valid (possible "
+                   "internal programming error)." , status);
+      }
+
+/* If OK, obtain the Handle's context level. */
+   } else {
+      context = handles[ ihandle ].context;
+
+/* If this indicates that the Handle isn't active, then report an
+   error (but only if the global error status has not already been
+   set). We allow handles that are currently not owned by any thread to
+   be annulled. */
+      if ( context < 0 && context != UNOWNED_CONTEXT ) {
+         if ( astOK ) {
+            astError( AST__INHAN, "astAnnulHandle: Invalid attempt to annul "
+                      "an Object Handle (no. %u).", status, ihandle );
+            astError( AST__INHAN, "This Handle is not active (possible "
+                      "internal programming error)." , status);
+         }
+
+/* If the Handle is active, annul its Object pointer. The astAnnul
+   function may call Delete functions supplied by any class, and these
+   Delete functions may involve annulling external Object IDs, which in
+   turn requires access to the handles array. For this reason, we release
+   the mutex that protects access to the handles arrays so that it can
+   potentially be re-aquired within astAnnul without causing deadlock. */
+      } else {
+
+#ifdef MEM_DEBUG
+         astHandleUse( ihandle, "annulled using check value %d ",
+                       handles[ ihandle ].check  );
+#endif
+
+         ptr = handles[ ihandle ].ptr;
+         UNLOCK_MUTEX2;
+         ptr = astAnnul( ptr );
+         LOCK_MUTEX2;
+
+/* Remove the Handle from the active list for its context level. */
+         if( context == UNOWNED_CONTEXT ) {
+
+#if defined(THREAD_SAFE)
+            RemoveHandle( ihandle, &unowned_handles, status );
+#else
+            if( astOK ) astError( AST__INTER, "AnnulHandle: reference to "
+                         "'unowned_handles' in a non-thread-safe context "
+                         "(internal AST programming error).", status );
+#endif
+
+         } else if( active_handles ) {
+            RemoveHandle( ihandle, &active_handles[ context ], status );
+
+         } else if( astOK ){
+            astError( AST__INTER, "AnnulHandle: active_handles array has "
+                      "not been initialised (internal AST programming error).",
+                      status );
+         }
+
+/* Reset the Handle's "context" value (making it inactive) and its "check"
+   value (so it is no longer associated with an identifier value). */
+         handles[ ihandle ].ptr = NULL;
+         handles[ ihandle ].context = INVALID_CONTEXT;
+         handles[ ihandle ].check = 0;
+#if defined(THREAD_SAFE)
+         handles[ ihandle ].thread = -1;
+#endif
+
+/* Place the modified Handle on the free Handles list ready for re-use. */
+         InsertHandle( ihandle, &free_handles, status );
+
+      }
+   }
+}
+
+AstObject *astAnnulId_( AstObject *this_id, int *status ) {
+/*
+*+
+*  Name:
+*     AnnulId
+
+*  Purpose:
+*     Annul an external Object identifier.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astAnnulId( AstObject *this )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function implements the external (public) interface to the
+*     astAnnul method. It accepts an active Object identifier, which
+*     it annuls, causing the associated Handle to be deactivated and
+*     returned to the free Handles list for re-use. It also causes the
+*     reference count of the associated Object to be decremented and
+*     the Object to be deleted if this reference count falls to zero.
+
+*  Parameters:
+*     this
+*        The Object identifier to be annulled.
+
+*  Returned Value:
+*     A NULL C pointer is always returned (this should be translated
+*     into an identifier value of zero for external use).
+
+*  Notes:
+*     - This function attempts to execute even if the global error
+*     status is set.
+*     - The identifier supplied should be associated with an active
+*     Object, otherwise an error will result (but no error report will
+*     be made if the global error status has already been set).
+*     - This function is invoked via the astAnnul macro for external use.
+*     For internal use (from protected code which needs to handle external
+*     IDs) it should be invoked via the astAnnulId macro (since astAnnul
+*     expects a true C pointer as its argument when used internally).
+*-
+*/
+
+/* Obtain the Object pointer from the ID supplied and validate the
+   pointer to ensure it identifies a valid Object (this generates an
+   error if it doesn't). Note, we use "astMakePointer_NoLockCheck",
+   rather than the usual "astMakePointer" since a thread should be able
+   to renounce interest in an object without needing to own the object.
+   If we used "astMakePointer" then a thread could not annul a pointer
+   unless it owned the object. But having annulled the pointer it could
+   then not unlock the object for use by another thread (since the
+   pointer it would need to do this has just been annulled). */
+   if ( !astIsAObject( astMakePointer_NoLockCheck( this_id ) ) ) return NULL;
+
+/* Obtain the Handle offset for this Object and annul the Handle and
+   its associated Object pointer. Report an error if the handle is
+   currently owned by a different thread. That is, the *Object* need
+   not be locked by the current thread (as indicated by the use of
+   astMakePointer above), but the *handle* must be owned by the current
+   thread. */
+   LOCK_MUTEX2;
+   AnnulHandle( CheckId( this_id, 1, status ), status );
+   UNLOCK_MUTEX2;
+
+/* Always return a NULL pointer value. */
+   return NULL;
+}
+
+MYSTATIC AstObject *AssocId( int ihandle, int *status ) {
+/*
+*  Name:
+*     AssocId
+
+*  Purpose:
+*     Associate an identifier value with a Handle.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *AssocId( int ihandle )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function takes a zero-based offset into the "handles" array
+*     that identifies a Handle associated with an active Object. It
+*     encodes this into an identifier value to be issued to an
+*     external user to identify that Handle and its Object, and then
+*     associates this identifier value with the Handle.
+
+*  Parameters:
+*     ihandle
+*        Offset in the "handles" array that identifies the Handle,
+*        which should be active (i.e. associated with an active
+*        Object). This function will modify the "check" field in this
+*        Handle to associate it with the identifier value it returns.
+
+*  Returned Value:
+*     The resulting identifier value.
+
+*  Notes:
+*     - The returned identifier value is, in fact, an int.  This
+*     allows the value to be passed easily to other languages
+*     (e.g. Fortran) and stored as an integer without loss of
+*     information.
+*     - The value is stored within C code as type AstObject*.  This
+*     means that C code (e.g. function prototypes, etc.) need not be
+*     aware that an identifier (as opposed to an Object pointer) is
+*     being used, even though the actual bit patterns will be
+*     different. The same C code can then be used for both internal
+*     and external purposes so long as care is taken to convert
+*     between the two representations at appropriate points.
+*     - The reverse operation (conversion of an ID back to a handle
+*     offset) is performed by CheckId.
+*     - A zero identifier value will be returned if this function is
+*     invoked with the global status set or if it should fail for any
+*     reason.
+*/
+
+/* Local Variables: */
+   AstObject *result;            /* Pointer value to return */
+   MixedInts test;               /* Union for testing encoding */
+   MixedInts work;               /* Union for encoding ID value */
+
+/* Initialise. */
+   result = astI2P( 0 );
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Copy the Handle offset and clear the lowest 8 bits by shifting
+   left. */
+   work.i = ihandle;
+   work.u = work.u << 8U;
+
+/* Make a copy of the result shifted right again. Test if any bits
+   have been lost in this process. If so, there are too many Handles
+   in use at once to encode them into IDs, so report an error. */
+   test.u = work.u >> 8U;
+   if ( test.i != ihandle ) {
+      astError( AST__XSOBJ, "AssocId(%s): There are too many AST Objects in "
+                "use at once.", status, astGetClass( handles[ ihandle ].ptr ) );
+
+/* If OK, scramble the value by exclusive-ORing with the bit pattern
+   in AST__FAC (a value unique to this library), also shifted left by
+   8 bits. This makes it even less likely that numbers from other
+   sources will be accepted in error as valid IDs. */
+   } else {
+      work.u ^= ( ( (unsigned) AST__FAC ) << 8U );
+
+/* Fill the lowest 8 bits with a count of the total number of IDs
+   issued so far (which we increment here). This makes each ID unique,
+   so that an old one that identifies a Handle that has been annulled
+   and re-used (i.e. associated with a new ID) can be spotted.  We
+   only use the lowest 8 bits of this count because this provides
+   adequate error detection to reveal programming errors and we do not
+   need higher security than this. We also prevent a count of zero
+   being used, as this could result in a zero identifier value (this
+   being reserved as the "null" value). */
+      if ( ++nids > 255U ) nids = 1U;
+      work.u |= nids;
+
+/* Store the value as a check count in the Handle. This will be used
+   to validate the ID in future. */
+      handles[ ihandle ].check = work.i;
+
+/* Pack the value into the pointer to be returned. */
+      result = astI2P( work.i );
+   }
+
+/* Return the result. */
+   return result;
+}
+
+void astBegin_( void ) {
+/*
+*++
+*  Name:
+c     astBegin
+f     AST_BEGIN
+
+*  Purpose:
+*     Begin a new AST context.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     void astBegin
+f     CALL AST_BEGIN( STATUS )
+
+*  Class Membership:
+*     Object class function.
+
+*  Description:
+c     This macro invokes a function to begin a new AST context.
+c     Any Object pointers
+f     This routine begins a new AST context. Any Object pointers
+*     created within this context will be annulled when it is later
+c     ended using astEnd (just as if astAnnul had been invoked),
+f     ended using AST_END (just as if AST_ANNUL had been invoked),
+c     unless they have first been exported using astExport or rendered
+c     exempt using astExempt. If
+f     unless they have first been exported using AST_EXPORT or rendered
+f     exempt using AST_EXEMPT. If
+*     annulling a pointer causes an Object's RefCount attribute to
+*     fall to zero (which happens when the last pointer to it is
+*     annulled), then the Object will be deleted.
+
+f  Parameters:
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Applicability:
+*     Object
+c        This macro applies to all Objects.
+f        This routine applies to all Objects.
+
+*  Notes:
+c     - astBegin attempts to execute even if the AST error status
+c     is set on entry.
+f     - This routine attempts to execute even if STATUS is set to an
+f     error value.
+c     - Contexts delimited by astBegin and astEnd may be nested to any
+c     depth.
+f     - Contexts delimited by AST_BEGIN and AST_END may be nested to any
+f     depth.
+*--
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   int stat;                     /* Copy of global status */
+   int *status;                  /* Pointer to inherited status value */
+
+/* Get a pointer to thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Now that the thread-specific data has been initialised, we can get a
+   pointer to the threads inherited status value. */
+   status = astGetStatusPtr;
+
+/* Save and clear the global status so that memory allocation can be
+   performed within this function even under error conditions. */
+   stat = astStatus;
+   astClearStatus;
+
+/* Ensure that the active_handles array has been initialised. */
+   if ( !active_handles ) InitContext( status );
+
+/* Extend the "active handles" array to accommodate a new context
+   level. This array contains integer offsets into the "handles" array
+   to identify the handle which is at the head of the list of active
+   handles for each context level. */
+   astBeginPM;
+   active_handles = astGrow( active_handles, context_level + 2,
+                             sizeof( int ) );
+   astEndPM;
+
+/* Initialise the array element for the new context level to indicate
+   an empty Handle list. */
+   if ( astOK ) active_handles[ ++context_level ] = -1;
+
+/* Restore the original global status value. */
+   astSetStatus( stat );
+}
+
+MYSTATIC int CheckId( AstObject *this_id, int lock_check, int *status ) {
+/*
+*  Name:
+*     CheckId
+
+*  Purpose:
+*     Check an identifier value and convert it into a Handle offset.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     int CheckId( AstObject *this, int lock_check, int *status )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function takes an identifier value encoded by AssocId and
+*     validates it to ensure it is associated with an active
+*     Handle. If valid, it converts it back into a zero-based offset
+*     which may be used to access the Handle in the "handles"
+*     array. Otherwise, an error is reported.
+
+*  Parameters:
+*     this
+*        The identifier value to be decoded.
+*     lock_check
+*        Should an error be reported if the handle is in an Object
+*        context for a different thread?
+*     status
+*        Pointer to the inherited status variable.
+
+*  Returned Value:
+*     The resulting Handle offset, or -1 if the identifier is not
+*     valid or any other error occurs.
+
+*  Notes:
+*     - This function attempts to execute even if the global error
+*     status is set, but no further error report will be made if it
+*     fails under these circumstances.
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   MixedInts work;               /* Union for decoding ID value */
+   int id;                       /* ID value as an int */
+   int ihandle;                  /* Result to return */
+
+#ifdef MEM_DEBUG
+   int oldok = astOK;
+#endif
+
+/* Initialise. */
+   ihandle = -1;
+
+/* Get a pointer to thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Retrieve the integer Object identifier value from the pointer
+   supplied. */
+   id = astP2I( this_id );
+
+/* Check if a value of zero has been supplied and report an error if
+   it has. */
+   if ( !id ) {
+      if ( astOK ) {
+         astError( AST__OBJIN, "Invalid Object pointer given (value is "
+                   "zero)." , status);
+      }
+
+/* If OK, reverse the encoding process performed by AssocId to
+   retrieve the Handle offset. */
+   } else {
+      work.i = id;
+      work.u = ( work.u ^ ( ( (unsigned) AST__FAC ) << 8U ) ) >> 8U;
+
+/* Check that the offset obtained doesn't extend beyond the limits of
+   the "handles" array. Report an error if it does. */
+      if ( ( work.i < 0 ) || ( work.i >= nhandles ) ) {
+         if ( astOK ) {
+            astError( AST__OBJIN, "Invalid Object pointer given (value is "
+                      "%d).", status, id );
+         }
+
+/* See if the "check" field matches the ID value and the Handle is
+   valid (i.e. is associated with an active Object). If not, the
+   Handle has been annulled and possibly re-used, so report an
+   error. */
+      } else if ( ( handles[ work.i ].check != id ) ||
+                  ( handles[ work.i ].context == INVALID_CONTEXT ) ) {
+         if ( astOK ) {
+            astError( AST__OBJIN, "Invalid Object pointer given (value is "
+                      "%d).", status, id  );
+            astError( AST__OBJIN, "This pointer has been annulled, or the "
+                      "associated Object deleted." , status);
+         }
+#if defined(THREAD_SAFE)
+      } else if(  lock_check && handles[ work.i ].context != UNOWNED_CONTEXT &&
+                                handles[ work.i ].thread != AST__THREAD_ID ) {
+         if ( astOK ) {
+            astError( AST__OBJIN, "Invalid Object pointer given (value is "
+                      "%d).", status, id  );
+            astError( AST__OBJIN, "This pointer is currently owned by "
+                      "another thread (possible programming error)." , status);
+         }
+#endif
+
+/* If OK, set the Handle offset to be returned. */
+      } else {
+         ihandle = work.i;
+      }
+
+#ifdef MEM_DEBUG
+      if ( oldok && !astOK && ( work.i >= 0 ) && ( work.i < nhandles ) ) {
+         char buf[200];
+         astError( astStatus, "Handle properties: %s ", status,
+                   HandleString( work.i, buf ) );
+      }
+#endif
+
+   }
+
+/* Return the result. */
+   return ihandle;
+}
+
+void astCreatedAtId_( AstObject *this_id, const char **routine,
+                      const char **file, int *line, int *status ){
+/*
+c++
+*  Name:
+*     astCreatedAt
+
+*  Purpose:
+*     Return the routine, file and line number at which an Object was
+*     created.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astCreatedAt( AstObject *this, const char **routine,
+*                        const char **file, int *line )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     This function returns pointers to two strings containing the
+*     name of the routine or function within which the object was created
+*     and the name of the source file containing that routine. It also
+*     returns the number of the line within the file at which the object
+*     was created. It is intended for use in debugging memory leaks etc.
+*
+*     Precisely, the information returned identifies the point at which
+*     the Object's public identifier (i.e. the supplied pointer) was
+*     first issued. This may not correspond to the actual creation of the
+*     Object if the object is contained within some higher level Object.
+*     For instance, if the astGetFrame method is used to get a pointer to
+*     a Frame within a FrameSet, the information returned by this
+*     function if supplied with the Frame pointer would identify the call
+*     to astGetFrame, rather than the line at which the FrameSet created
+*     its internal copy of the Frame. Likewise, if this function is used
+*     to get information from an Object pointer returned by astClone, the
+*     information will describe the call to astClone, not the call that
+*     created the original Object.
+
+*  Parameters:
+*     this
+*        Pointer to the Object.
+*     routine
+*        Address of a pointer to a null terminated C string in which to
+*        return the routine name (the string will reside in static memory).
+*        The pointer will be set to NULL on exit if no routine name is
+*        available.
+*     file
+*        Address of a pointer to a null terminated C string in which to
+*        return the file name (the string will reside in static memory).
+*        The pointer will be set to NULL on exit if no file name is
+*        available.
+*     line
+*        Address of an int in which to store the line number in the file.
+*        A line number of zero is returned if no line number is available.
+
+*  Notes:
+*     - NULL pointers and a line number of zero are returned if an error
+*     has already occurred prior to calling this function.
+
+c--
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   int ihandle;                  /* Result to return */
+
+/* Initialise */
+   *routine = NULL;
+   *file = NULL;
+   *line = 0;
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Gain exclusive access to the handles array. */
+   LOCK_MUTEX2;
+
+/* Obtain the Handle offset for this Object. */
+   ihandle = CheckId( this_id, 1, status );
+   if ( ihandle != -1 ) {
+
+/* Copy the required pointers etc to the supplied addresses. */
+      *routine = handles[ ihandle ].routine;
+      *file = handles[ ihandle ].file;
+      *line = handles[ ihandle ].line;
+   }
+
+/* Unlock the mutex that guards access to the handles array */
+   UNLOCK_MUTEX2;
+
+}
+
+AstObject *astDeleteId_( AstObject *this_id, int *status ) {
+/*
+*+
+*  Name:
+*     astDeleteId
+
+*  Purpose:
+*     Delete an Object via an identifier.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astDeleteId_( AstObject *this )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function implements the external (public) interface to the
+*     astDelete method. It accepts an active Object identifier and
+*     deletes the associated Object. Before doing so, it annuls all
+*     active identifiers associated with the object, deactivates their
+*     Handles and returns these Handles to the free Handles list for
+*     re-use.
+
+*  Parameters:
+*     this
+*        An identifier for the Object to be deleted.
+
+*  Returned Value:
+*     A NULL C pointer is always returned (this should be translated
+*     into an identifier value of zero for external use).
+
+*  Notes:
+*     - This function attempts to execute even if the global error
+*     status is set.
+*     - The identifier supplied should be associated with an active
+*     Object, otherwise an error will result (but no error report will
+*     be made if the global error status has already been set).
+*     - Although this function is documented as "private" and should
+*     not be invoked directly from outside this class, it is not a
+*     static function and has a public prototype. This is because it
+*     must be invoked via the astDelete macro (defined in the
+*     "object.h" include file) as part of the public interface.
+*-
+*/
+
+/* Local Variables: */
+   AstObject *this;              /* Pointer to Object */
+   int i;                        /* Loop counter for Handles */
+   int ihandle;                  /* Object Handle offset */
+
+/* Obtain the Object pointer from the ID supplied and validate the
+   pointer to ensure it identifies a valid Object (this generates an
+   error if it doesn't). */
+   if ( !astIsAObject( this = astMakePointer( this_id ) ) ) return NULL;
+
+/* Gain exclusive access to the handles array. */
+   LOCK_MUTEX2;
+
+/* Obtain the Handle offset for this Object. */
+   ihandle = CheckId( this_id, 1, status );
+   if ( ihandle != -1 ) {
+
+/* Since the Object is to be deleted, we must annul all identifiers
+   that refer to it.  Loop to inspect each currently allocated Handle
+   in the "handles" array. */
+      for ( i = 0; i < nhandles; i++ ) {
+
+/* Select active handles and test if their Object pointer refers to
+   the Object to be deleted. */
+         if ( ( handles[ i ].context != INVALID_CONTEXT ) &&
+              ( handles[ i ].ptr == this ) ) {
+
+/* If so, explicitly set the reference count for the Object to 2 so
+   that it will not be deleted (yet) when we annul the pointer
+   associated with the Handle. */
+            handles[ i ].ptr->ref_count = 2;
+
+/* Annul the Handle, which frees its resources, decrements the Object
+   reference count and makes any ID associated with the Handle become
+   invalid. */
+            AnnulHandle( i, status );
+         }
+      }
+
+/* If required, tell the user that the handle's object has been deleted. */
+#ifdef MEM_DEBUG
+      astHandleUse( ihandle, "object-deleted" );
+#endif
+   }
+
+   UNLOCK_MUTEX2;
+
+/* When all Handles associated with the Object have been annulled,
+   delete the object itself. This over-rides the reference count and
+   causes any remaining pointers to the Object (e.g. in internal code
+   or within other Objects) to become invalid. */
+   this = astDelete( this );
+
+/* Always return a NULL pointer value. */
+   return NULL;
+}
+
+void astEnd_( int *status ) {
+/*
+*++
+*  Name:
+c     astEnd
+f     AST_END
+
+*  Purpose:
+*     End an AST context.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     void astEnd
+f     CALL AST_END( STATUS )
+
+*  Class Membership:
+*     Object class function.
+
+*  Description:
+c     This macro invokes a function to end an AST context which was
+f     This routine ends an AST context which was
+c     begun with a matching invocation of astBegin. Any Object
+f     begun with a matching invocation of AST_BEGIN. Any Object
+*     pointers created within this context will be annulled (just as
+c     if astAnnul had been invoked) and will cease to be valid
+f     if AST_ANNUL had been invoked) and will cease to be valid
+*     afterwards, unless they have previously been exported using
+c     astExport or rendered exempt using astExempt.
+f     AST_EXPORT or rendered exempt using AST_EXEMPT.
+*     If annulling a pointer causes an Object's RefCount attribute to
+*     fall to zero (which happens when the last pointer to it is
+*     annulled), then the Object will be deleted.
+
+*  Parameters:
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Applicability:
+*     Object
+c        This macro applies to all Objects.
+f        This routine applies to all Objects.
+
+*  Notes:
+c     - astEnd attempts to execute even if the AST error status is set.
+f     - This routine attempts to execute even if STATUS is set to an
+f     error value.
+c     - Contexts delimited by astBegin and astEnd may be nested to any
+c     depth.
+f     - Contexts delimited by AST_BEGIN and AST_END may be nested to any
+f     depth.
+*--
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   int ihandle;                  /* Offset of Handle to be annulled */
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Check that the current context level is at least 1, otherwise there
+   has been no matching use of astBegin, so report an error (unless
+   the global status has already been set). */
+   if ( context_level < 1 ) {
+      if ( astOK ) {
+         astError( AST__ENDIN, "astEnd: Invalid use of astEnd without a "
+                   "matching astBegin." , status);
+      }
+
+/* If OK, loop while there are still active Handles associated with
+   the current context level. First gain exclusive access to the handles
+   array. */
+   } else if ( active_handles ) {
+      LOCK_MUTEX2;
+      while ( ( ihandle = active_handles[ context_level ] ) != -1 ) {
+
+/* Annul the Handle at the head of the active Handles list. */
+         AnnulHandle( ihandle, status );
+
+/* It is just posible that under error conditions inactive Handles
+   might get left in the active_handles list and AnnulHandle would
+   then fail. Since this would result in an infinite loop, we check to
+   see if the handle we have just annulled is still in the list. If
+   so, transfer it to the free Handles list for re-use. */
+         if ( ihandle == active_handles[ context_level ] ) {
+            RemoveHandle( ihandle, &active_handles[ context_level ], status );
+            InsertHandle( ihandle, &free_handles, status );
+         }
+      }
+
+/* Ensure the context level is decremented unless it was zero to start
+   with. */
+      context_level--;
+
+/* Relinquish access to the handles array. */
+      UNLOCK_MUTEX2;
+   }
+
+}
+
+void astExemptId_( AstObject *this_id, int *status ) {
+/*
+*++
+*  Name:
+c     astExempt
+f     AST_EXEMPT
+
+*  Purpose:
+*     Exempt an Object pointer from AST context handling.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     void astExempt( AstObject *this )
+f     CALL AST_EXEMPT( THIS, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+c     This function exempts an Object pointer from AST context
+f     This routine exempts an Object pointer from AST context
+c     handling, as implemented by astBegin and astEnd. This means that
+f     handling, as implemented by AST_BEGIN and AST_END. This means that
+c     the pointer will not be affected when astEnd is invoked and will
+f     the pointer will not be affected when AST_END is called and will
+*     remain active until the end of the program, or until explicitly
+c     annulled using astAnnul.
+f     annulled using AST_ANNUL.
+*
+c     If possible, you should avoid using this function when writing
+f     If possible, you should avoid using this routine when writing
+*     applications. It is provided mainly for developers of other
+*     libraries, who may wish to retain references to AST Objects in
+*     internal data structures, and who therefore need to avoid the
+c     effects of astBegin and astEnd.
+f     effects of AST_BEGIN and AST_END.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Object pointer to be exempted from context handling.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Applicability:
+*     Object
+c        This function applies to all Objects.
+f        This routine applies to all Objects.
+*--
+
+*  Implementation Notes:
+*     - This function does not exist in the "protected" interface to
+*     the Object class and is not available to other class
+*     implementations.
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   int context;                  /* Handle context level */
+   int ihandle;                  /* Offset of Handle in "handles" array */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Obtain the Object pointer from the ID supplied and validate the
+   pointer to ensure it identifies a valid Object. */
+   (void) astCheckObject( astMakePointer( this_id ) );
+   if ( astOK ) {
+
+/* Gain exclusive access to the handles array. */
+      LOCK_MUTEX2;
+
+/* Obtain the Handle offset for this Object. */
+      ihandle = CheckId( this_id, 1, status );
+      if ( ihandle != -1 ) {
+
+/* Extract the context level at which the Object was created. */
+         context = handles[ ihandle ].context;
+
+/* Set the new context level to zero, where it cannot be affected by
+   ending any context. */
+         handles[ ihandle ].context = 0;
+
+/* Remove the object's Handle from its original active Handles list
+   and insert it into the list appropriate to its new context
+   level. */
+
+#if defined(THREAD_SAFE)
+         if( context == UNOWNED_CONTEXT ) {
+            RemoveHandle( ihandle, &unowned_handles, status );
+         } else {
+            RemoveHandle( ihandle, &active_handles[ context ], status );
+         }
+#else
+         RemoveHandle( ihandle, &active_handles[ context ], status );
+#endif
+
+         InsertHandle( ihandle, &active_handles[ 0 ], status );
+
+/* If required, tell the user that the handle has been exempted. */
+#ifdef MEM_DEBUG
+         astHandleUse( ihandle, "exempted" );
+#endif
+      }
+
+      UNLOCK_MUTEX2;
+   }
+}
+
+void astExportId_( AstObject *this_id, int *status ) {
+/*
+*++
+*  Name:
+c     astExport
+f     AST_EXPORT
+
+*  Purpose:
+*     Export an Object pointer to an outer context.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     void astExport( AstObject *this )
+f     CALL AST_EXPORT( THIS, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+c     This function exports an Object pointer from the current AST context
+f     This routine exports an Object pointer from the current AST context
+*     into the context that encloses the current one. This means that
+*     the pointer will no longer be annulled when the current context
+c     is ended (with astEnd), but only when the next outer context (if
+f     is ended (with AST_END), but only when the next outer context (if
+*     any) ends.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Object pointer to be exported.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Applicability:
+*     Object
+c        This function applies to all Objects.
+f        This routine applies to all Objects.
+
+*  Notes:
+c     - It is only sensible to apply this function to pointers that
+f     - It is only sensible to apply this routine to pointers that
+*     have been created within (or exported to) the current context
+c     and have not been rendered exempt using astExempt.
+f     and have not been rendered exempt using AST_EXEMPT.
+*     Applying it to an unsuitable Object pointer has no effect.
+*--
+
+*  Implementation Notes:
+*     - This function does not exist in the "protected" interface to
+*     the Object class and is not available to other class
+*     implementations.
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   int context;                  /* Handle context level */
+   int ihandle;                  /* Offset of Handle in "handles" array */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Obtain the Object pointer from the ID supplied and validate the
+   pointer to ensure it identifies a valid Object. */
+   (void) astCheckObject( astMakePointer( this_id ) );
+   if ( astOK ) {
+
+/* Gain exclusive access to the handles array. */
+      LOCK_MUTEX2;
+
+/* Obtain the Handle offset for this Object. */
+      ihandle = CheckId( this_id, 1, status );
+      if ( ihandle != -1 ) {
+
+/* Check that the current context level is at least 1 and report an
+   error if it is not. */
+         if ( context_level < 1 ) {
+            if( astOK ) astError( AST__EXPIN, "astExport(%s): Attempt to export an Object "
+                                  "from context level zero.", status,
+                                  astGetClass( handles[ ihandle ].ptr ) );
+
+/* Extract the context level at which the Object was created. */
+         } else {
+            context = handles[ ihandle ].context;
+
+/* Check that the Object's existing context level is high enough to be
+   affected by being exported to the next outer context level. If not,
+   do nothing. */
+            if ( context > ( context_level - 1 ) ) {
+
+/* Set the new context level. */
+               handles[ ihandle ].context = context_level - 1;
+
+/* Remove the object's Handle from its original active Handles list
+   and insert it into the list appropriate to its new context
+   level. */
+               RemoveHandle( ihandle, &active_handles[ context ], status );
+               InsertHandle( ihandle, &active_handles[ context_level - 1 ],
+                             status );
+
+/* If required, tell the user that the handle has been exempted. */
+#ifdef MEM_DEBUG
+               astHandleUse( ihandle, "exported from context level %d",
+                              context_level );
+#endif
+            }
+         }
+      }
+      UNLOCK_MUTEX2;
+   }
+}
+
+void astImportId_( AstObject *this_id, int *status ) {
+/*
+*++
+*  Name:
+c     astImport
+f     AST_IMPORT
+
+*  Purpose:
+*     Import an Object pointer to the current context.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     void astImport( AstObject *this )
+f     CALL AST_IMPORT( THIS, STATUS )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+c     This function
+f     This routine
+*     imports an Object pointer that was created in a higher or lower
+*     level context, into the current AST context.
+*     This means that the pointer will be annulled when the current context
+c     is ended (with astEnd).
+f     is ended (with AST_END).
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Object pointer to be imported.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Applicability:
+*     Object
+c        This function applies to all Objects.
+f        This routine applies to all Objects.
+
+*--
+
+*  Implementation Notes:
+*     - This function does not exist in the "protected" interface to
+*     the Object class and is not available to other class
+*     implementations.
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   int context;                  /* Handle context level */
+   int ihandle;                  /* Offset of Handle in "handles" array */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Obtain the Object pointer from the ID supplied and validate the
+   pointer to ensure it identifies a valid Object. */
+   (void) astCheckObject( astMakePointer( this_id ) );
+   if ( astOK ) {
+
+/* Gain exclusive access to the handles array. */
+      LOCK_MUTEX2;
+
+/* Obtain the Handle offset for this Object. */
+      ihandle = CheckId( this_id, 1, status );
+      if ( ihandle != -1 ) {
+
+/* Extract the context level at which the Object was created. */
+         context = handles[ ihandle ].context;
+
+/* Do nothing if the Identifier already belongs to the current context. */
+         if( context != context_level ) {
+
+/* Set the new context level. */
+            handles[ ihandle ].context = context_level;
+
+/* Remove the object's Handle from its original active Handles list
+   and insert it into the list appropriate to its new context
+   level. */
+            RemoveHandle( ihandle, &active_handles[ context ], status );
+            InsertHandle( ihandle, &active_handles[ context_level ], status );
+
+/* If required, tell the user that the handle has been imported. */
+#ifdef MEM_DEBUG
+            astHandleUse( ihandle, "imported into context level %d",
+                           context_level );
+#endif
+         }
+      }
+      UNLOCK_MUTEX2;
+   }
+}
+
+void astLockId_( AstObject *this_id, int wait, int *status ) {
+/*
+c++
+*  Name:
+*     astLock
+
+*  Purpose:
+*     Lock an Object for exclusive use by the calling thread.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astLock( AstObject *this, int wait )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     The thread-safe public interface to AST is designed so that an
+*     error is reported if any thread attempts to use an Object that it
+*     has not previously locked for its own exclusive use using this
+*     function. When an Object is created, it is initially locked by the
+*     thread that creates it, so newly created objects do not need to be
+*     explicitly locked. However, if an Object pointer is passed to
+*     another thread, the original thread must first unlock it (using
+*     astUnlock) and the new thread must then lock it (using astLock)
+*     before the new thread can use the Object.
+*
+*     The "wait" parameter determines what happens if the supplied Object
+*     is curently locked by another thread when this function is invoked.
+
+*  Parameters:
+*     this
+*        Pointer to the Object to be locked.
+*     wait
+*        If the Object is curently locked by another thread then this
+*        function will either report an error or block. If a non-zero value
+*        is supplied for "wait", the calling thread waits until the object
+*        is available for it to use. Otherwise, an error is reported and
+*        the function returns immediately without locking the Object.
+
+*  Applicability:
+*     Object
+*        This function applies to all Objects.
+
+*  Notes:
+*     - The astAnnul function is exceptional in that it can be used on
+*     pointers for Objects that are not currently locked by the calling
+*     thread. All other AST functions will report an error.
+*     - The Locked object will belong to the current AST context.
+*     - This function returns without action if the Object is already
+*     locked by the calling thread.
+*     - If simultaneous use of the same object is required by two or more
+*     threads, astCopy should be used to to produce a deep copy of
+*     the Object for each thread. Each copy should then be unlocked by
+*     the parent thread (i.e. the thread that created the copy), and then
+*     locked by the child thread (i.e. the thread that wants to use the
+*     copy).
+*     - This function is only available in the C interface.
+*     - This function returns without action if the AST library has
+*     been built without POSIX thread support (i.e. the "-with-pthreads"
+*     option was not specified when running the "configure" script).
+c--
+*/
+
+/* This function odes nothing if thread support is not enabvled. */
+#if defined(THREAD_SAFE)
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   AstObject *fail;              /* Pointer to Object that failed to lock */
+   AstObject *this;              /* Pointer to Object */
+   int ihandle;                  /* Index of supplied objetc handle */
+   int lstat;                    /* Local status value */
+
+/* Obtain the Object pointer from the ID supplied and validate the
+   pointer to ensure it identifies a valid Object (this generates an
+   error if it doesn't). Note, we use the "astMakePointer_NoLockCheck",
+   since the usual "astMakePointer" macro invokes astCheckLock to report
+   an error if the Object is not currently locked by the calling thread. */
+   if ( !astIsAObject( this = astMakePointer_NoLockCheck( this_id ) ) ) return;
+
+/* Ensure the global data for this class is accessable. Do not use the
+   globals pointer stored in "*this" because "*this" may be locked by
+   another thread and so we would pick up the wrong globals. */
+   astGET_GLOBALS(NULL);
+
+/* Ensure the running thread has sole access to the static handles arrays. */
+   LOCK_MUTEX2;
+
+/* Ensure the Handles arrays have been initialised. */
+   if ( !active_handles ) InitContext( status );
+
+/* Get the Handle index for the supplied object identifier. No error is
+   reported if the handle is not curently associated with a thread.
+   However, an error is reported if the Handle is associated with any
+   thread other than the running thread. */
+   ihandle = CheckId( this_id, 1, status );
+
+/* We've finished with the handles arrays, for the moment. */
+   UNLOCK_MUTEX2;
+
+/* Check the object pointer was valid. */
+   if( ihandle != -1 ){
+
+/* The protected astManageLock function implements the public functions,
+   astLock and astUnlock. */
+      lstat = astManageLock( this, AST__LOCK, wait, &fail );
+      if( astOK ) {
+         if( lstat == 1 ) {
+            if( fail == this ) {
+               astError( AST__LCKERR, "astLock(%s): Failed to lock the %s because"
+                         " it is already locked by another thread (programming "
+                         "error).", status, astGetClass( this ),
+                         astGetClass( this ) );
+
+            } else {
+               astError( AST__LCKERR, "astLock(%s): Failed to lock the %s because"
+                         " a %s contained within it is already locked by another "
+                         "thread (programming error).", status,
+                         astGetClass( this ), astGetClass( this ),
+                         astGetClass( fail ) );
+            }
+
+         } else if( lstat == 2 ) {
+            astError( AST__LCKERR, "astLock(%s): Failed to lock a POSIX mutex.", status,
+                      astGetClass( this ) );
+
+/* If the Object is now locked for the running thread... */
+         } else {
+
+/* We need access to the handles arrays again. */
+            LOCK_MUTEX2;
+
+/* If the supplied handle is not currently assigned to any thread, assign
+   it to the running thread. */
+            if( handles[ ihandle ].context == UNOWNED_CONTEXT ) {
+               RemoveHandle( ihandle, &unowned_handles, status );
+
+#if defined(MEM_DEBUG)
+               astHandleUse( ihandle, "locked by thread %d at context level %d",
+                             handles[ ihandle ].thread, context_level );
+#endif
+
+               handles[ ihandle ].thread = AST__THREAD_ID;
+               handles[ ihandle ].context = context_level;
+               InsertHandle( ihandle, &active_handles[ context_level ],
+                                status );
+            }
+
+/* Finished with the handles arrays again. */
+            UNLOCK_MUTEX2;
+         }
+      }
+   }
+#endif
+}
+
+void astUnlockId_( AstObject *this_id, int report, int *status ) {
+/*
+c++
+*  Name:
+*     astUnlock
+
+*  Purpose:
+*     Unlock an Object for use by other threads.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astUnlock( AstObject *this, int report )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     Unlocks an Object previously locked using astLock, so that other
+*     threads can use the Object. See astLock for further details.
+
+*  Parameters:
+*     this
+*        Pointer to the Object to be unlocked.
+*     report
+*        If non-zero, an error will be reported if the supplied Object,
+*        or any Object contained within the supplied Object, is not
+*        currently locked by the running thread. If zero, such Objects
+*        will be left unchanged, and no error will be reported.
+
+*  Applicability:
+*     Object
+*        This function applies to all Objects.
+
+*  Notes:
+*     - This function attempts to execute even if the global error
+*     status is set, but no further error report will be made if it
+*     subsequently fails under these circumstances.
+*     - All unlocked Objects are excluded from AST context handling until
+*     they are re-locked using astLock.
+*     - This function is only available in the C interface.
+*     - This function returns without action if the Object is not currently
+*     locked by any thread. If it is locked by the running thread, it is
+*     unlocked. If it is locked by another thread, an error will be reported
+*     if "error" is non-zero.
+*     - This function returns without action if the AST library has
+*     been built without POSIX thread support (i.e. the "-with-pthreads"
+*     option was not specified when running the "configure" script).
+c--
+*/
+
+/* This function odes nothing if thread support is not enabvled. */
+#if defined(THREAD_SAFE)
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   AstErrorContext error_context;/* Info about the current error context */
+   AstObject *fail;              /* Pointer to Object that failed */
+   AstObject *this;              /* Pointer to Object */
+   int ihandle;                  /* Index of supplied objetc handle */
+   int lstat;                    /* Local status value */
+
+/* Obtain the Object pointer from the ID supplied and validate the
+   pointer to ensure it identifies a valid Object (this generates an
+   error if it doesn't). Note, we use the "astMakePointer_NoLockCheck",
+   since the usual "astMakePointer" macro invokes astCheckLock to report
+   an error if the Object is not currently locked by the calling thread. */
+   if ( !astIsAObject( this = astMakePointer_NoLockCheck( this_id ) ) ) return;
+
+/* Ensure the global data for this class is accessable. */
+   astGET_GLOBALS(this);
+
+/* Start a new error reporting context. This saves any existing error status
+   and then clear the status value. It also defer further error reporting. */
+   astErrorBegin( &error_context );
+
+/* Ensure the running thread has sole access to the static handles arrays. */
+   LOCK_MUTEX2;
+
+/* Ensure the Handles arrays have been initialised. */
+   if ( !active_handles ) InitContext( status );
+
+/* Get the Handle index for the supplied object identifier. Report an
+   error if the handle is associated with a different thread (no error
+   if the handle has no associated thread or is associated with the
+   current thread). */
+   ihandle = CheckId( this_id, 1, status );
+
+/* Break the associated of the handle with the current thread so that the
+   handle is not assigned to any thread. We do this before unlocking the
+   Object structure (using astManageLock) since as soon as astManageLock
+   returns, another thread that is waiting for the object to be unlocked
+   may start up and modify the handle properties. */
+   if( ihandle >= 0 && handles[ ihandle ].context >= 0 ) {
+      RemoveHandle( ihandle, &active_handles[ handles[ ihandle ].context ],
+                    status );
+#if defined(MEM_DEBUG)
+      astHandleUse( ihandle, "unlocked from thread %d at context "
+                    "level %d", handles[ ihandle ].thread,
+                    handles[ ihandle ].context );
+#endif
+      handles[ ihandle ].thread = -1;
+      handles[ ihandle ].context = UNOWNED_CONTEXT;
+      InsertHandle( ihandle, &unowned_handles, status );
+   }
+
+/* We've finished with the handles arrays, for the moment. */
+   UNLOCK_MUTEX2;
+
+/* Check the supplied object pointer was valid. */
+   if( ihandle != -1 ){
+
+/* The protected astManageLock function implements the public functions,
+   astLock and astUnlock. */
+      lstat = astManageLock( this, AST__UNLOCK, 0, &fail );
+      if( astOK ) {
+         if( lstat == 1 ) {
+            if( report ) {
+               if( fail == this ) {
+                  astError( AST__LCKERR, "astUnlock(%s): Failed to unlock the %s "
+                            "because it is locked by another thread (programming "
+                            "error).", status, astGetClass( this ),
+                            astGetClass( this ) );
+
+               } else {
+                  astError( AST__LCKERR, "astUnlock(%s): Failed to unlock the %s "
+                            "because a %s contained within it is locked by another "
+                            "thread (programming error).", status,
+                            astGetClass( this ), astGetClass( this ),
+                            astGetClass( fail ) );
+               }
+            }
+
+         } else if( lstat == 3 ) {
+            astError( AST__LCKERR, "astUnlock(%s): Failed to unlock a POSIX mutex.", status,
+                      astGetClass( this ) );
+
+         }
+      }
+   }
+
+/* End the error reporting context. If an error has occurred within this
+   function, then this will display the deferred error messages so long
+   as there was no error condition on entry to this function. If there
+   was an error condition on entry, then the original status value will be
+   re-instated. */
+   astErrorEnd( &error_context );
+
+#endif
+}
+
+AstObject *astI2P_( int integer, int *status ) {
+/*
+*+
+*  Name:
+*     astI2P
+
+*  Purpose:
+*     Pack an integer Object ID into a pointer.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astI2P( int integer )
+
+*  Class Membership:
+*     Object class function.
+
+*  Description:
+*     This function accepts an integer (int) value representing an
+*     Object identifier and packs its bit pattern into a pointer value
+*     (from which it may subsequently be retrieved using astP2I).
+*
+*     These functions should be used to avoid any dependency on
+*     integer-to-pointer conversions (given that the values are not
+*     true pointers) which might affect the exchange of Object
+*     identifier values with other languages, such as Fortran 77,
+*     where they are stored as integers.
+
+*  Parameters:
+*     integer
+*        The integer value to be stored.
+
+*  Returned Value:
+*     The resulting pointer value (which is not usually a valid C pointer).
+
+*  Notes:
+*     - This function does not perform error checking and does not
+*     generate errors.
+*     - This is a protected function in the sense that it is not
+*     intended that external users should invoke it directly.  It is
+*     accessible from external code, however, in order that public
+*     macros invoked from that code can make use of it.
+*-
+*/
+
+/* Local Variables: */
+   IdUnion temp;                 /* Overlapping int and pointer */
+
+/* Clear the pointer value in the "temp" IdUnion and then set the
+   integer part of it to the value to be stored. */
+   temp.pointer = zero_ptr;
+   temp.integer = integer;
+
+/* Return the resulting pointer value. */
+   return temp.pointer;
+}
+
+MYSTATIC void InitContext( int *status ) {
+/*
+*  Name:
+*     InitContext
+
+*  Purpose:
+*     Initialise the first AST context level.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void InitContext( int *status )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function initialises the first AST context level (the level
+*     before any call to astBegin has been made). It should be invoked
+*     once, before any use is made of context levels.
+
+*  Parameters:
+*     status
+*        Pointer to the inherited status variable.
+
+*  Parameters:
+*     None.
+
+*  Notes:
+*     - This function does nothing after the first successful invocation.
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Check that the active_handles array hasn't already been allocated. */
+   if ( !active_handles ) {
+
+/* Allocate and initialise the "active_handles" array. */
+
+      astBeginPM;
+      active_handles = astMalloc( sizeof( int ) );
+      astEndPM;
+
+      if ( astOK ) active_handles[ 0 ] = -1;
+   }
+}
+
+MYSTATIC void InsertHandle( int ihandle, int *head, int *status ) {
+/*
+*  Name:
+*     InsertHandle
+
+*  Purpose:
+*     Insert a Handle into a list.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void InsertHandle( int ihandle, int *head, int *status )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function inserts a Handle structure into a doubly linked
+*     list of such structures composed of elements drawn from the
+*     "handles" array. The new list member is inserted in front of the
+*     member previously occupying the "head of list" position.
+
+*  Parameters:
+*     ihandle
+*        Offset in the "handles" array that identifies the handle to
+*        be added to the list.
+*     head
+*        Address of an int which holds the offset in the "handles"
+*        array of the element at the head of the list (or -1 if the
+*        list is empty). This value will be updated to identify the
+*        new list member.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Notes:
+*     - This function does not perform error chacking and does not
+*     generate errors.
+*     - The lists generated by this function use integer offsets into
+*     the "handles" array for their links, rather than pointers. This
+*     is because the array may be re-located in memory when it needs
+*     to be extended, so pointers to its element would not remain
+*     valid.
+*     - The list elements are drawn from the "handles" array in the
+*     first place so that they can be addressed by small integers (the
+*     offset in the array). This allows references to Handles to be
+*     encoded along with security information into an integer that is
+*     sufficiently short to be exported to other languages
+*     (e.g. Fortran) which might not be able to accommodate
+*     full-length C pointers.
+*/
+
+
+#if defined(MEM_DEBUG)
+   char buf[80];
+   astHandleUse( ihandle, "about to be inserted into %s (%d)",
+                 HeadString( head, buf ), head );
+   CheckList( head, status );
+   CheckInList( ihandle, head, 0, status );
+#endif
+
+/* Check a head pointer was supplied (may not be if an error has
+   occurred). */
+   if( ! head ) return;
+
+/* If the list is empty, the sole new element points at itself. */
+   if ( *head == -1 ) {
+      handles[ ihandle ].flink = ihandle;
+      handles[ ihandle ].blink = ihandle;
+
+/* Otherwise, insert the new element in front of the element at the
+   head of the list. */
+   } else {
+      handles[ ihandle ].flink = *head;
+      handles[ ihandle ].blink = handles[ *head ].blink;
+      handles[ ( handles[ *head ].blink) ].flink = ihandle;
+      handles[ *head ].blink = ihandle;
+   }
+
+/* Update the list head to identify the new element. */
+   *head = ihandle;
+
+#if defined(MEM_DEBUG)
+   CheckList( head, status );
+   astHandleUse( ihandle, "has been inserted into %s", buf );
+#endif
+}
+
+AstObject *astMakeId_( AstObject *this, int *status ) {
+/*
+*+
+*  Name:
+*     astMakeId
+
+*  Purpose:
+*     Issue an identifier for an Object.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astMakeId( AstObject *this )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function takes a normal C pointer to an Object and
+*     associates an identifier with it.
+
+*  Parameters:
+*     this
+*        Pointer to an Object. Note that this function copies this
+*        value (it is not cloned), so the caller should not annul the
+*        pointer afterwards.
+
+*  Returned Value:
+*     The resulting identifier value.
+
+*  Notes:
+*     - An identifier value of zero will be returned and the supplied
+*     Object pointer will be annulled if this function is invoked with
+*     the global error status set or if it should fail for any reason.
+*     - A zero identifier value will also be returned if a NULL object
+*     pointer is supplied, but this will not provoke an error.
+*     - This is a protected function in the sense that it is not
+*     intended that external users should invoke it directly.  It is
+*     accessible from external code, however, in order that public
+*     macros invoked from that code can make use of it.
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Thread-specific global data */
+   AstObject *id;                /* ID value to return */
+   int ihandle;                  /* Handle offset */
+
+/* Initialise. */
+   id = astI2P( 0 );
+   ihandle = 0;
+
+/* Check the global error status. */
+   if ( astOK ) {
+
+/* Get a pointer to Thread-specific global data. */
+      astGET_GLOBALS(this);
+
+/* Gain exclusive access to the handles array. */
+      LOCK_MUTEX2;
+
+/* If a non-NULL Object pointer was given, we must obtain a Handle
+   structure to associate with it (otherwise a zero identifier value
+   is returned without error). */
+      if ( this ) {
+
+/* If the free Handles list is not empty, obtain a Handle from it. */
+         if ( free_handles != -1 ) {
+            ihandle = free_handles;
+            RemoveHandle( ihandle, &free_handles, status );
+
+/* Otherwise, allocate a new Handle by extending the "handles" array
+   and using the offset of the new element. */
+         } else {
+
+            astBeginPM;
+            handles = astGrow( handles, nhandles + 1, sizeof( Handle ) );
+            astEndPM;
+
+            if ( astOK ) {
+               ihandle = nhandles++;
+
+               handles[ ihandle ].ptr = NULL;
+               handles[ ihandle ].context = INVALID_CONTEXT;
+               handles[ ihandle ].check = 0;
+               handles[ ihandle ].flink = -1;
+               handles[ ihandle ].blink = -1;
+               handles[ ihandle ].line = 0;
+               handles[ ihandle ].file = NULL;
+               handles[ ihandle ].routine = NULL;
+#if defined(THREAD_SAFE)
+               handles[ ihandle ].thread = 0;
+#endif
+
+#if defined(MEM_DEBUG)
+               handles[ ihandle ].id = 0;
+               handles[ ihandle ].vtab = NULL;
+#endif
+            }
+         }
+
+/* If the first AST context level has not yet been initialised, invoke
+   InitContext to initialise it and allocate memory for the
+   "active_handles" array which stores context information. */
+         if ( astOK ) {
+            if ( !active_handles ) InitContext( status );
+
+/* Store the Object pointer and current context level in the Handle. */
+            if ( astOK ) {
+               handles[ ihandle ].ptr = this;
+               handles[ ihandle ].context = context_level;
+#if defined(THREAD_SAFE)
+               handles[ ihandle ].thread = AST__THREAD_ID;
+#endif
+
+/* Store information that records where the Handle is created - routine
+   name, file name and line number. */
+               astGetAt( &handles[ ihandle ].routine,
+                         &handles[ ihandle ].file,
+                         &handles[ ihandle ].line );
+
+/* Store extra debugging information in the handle if enabled */
+#if defined(MEM_DEBUG)
+               handles[ ihandle ].id = astMemoryId( this );
+               handles[ ihandle ].vtab = this->vtab;
+               astHandleUse( ihandle, "associated with a %s (id %d)",
+                              astGetClass( this ), astMemoryId( this ));
+#endif
+
+/* Insert the Handle into the active Handles list for the current
+   context level. */
+               InsertHandle( ihandle, &active_handles[ context_level ], status );
+
+/* Associate an identifier value with the Handle. */
+               id = AssocId( ihandle, status );
+
+/* If an error occurred, clean up by annulling the Handle. This
+   ensures that the Object pointer is annulled and returns the unused
+   Handle to the Free Handle list. */
+               if ( !astOK ) {
+                  AnnulHandle( ihandle, status );
+                  this = NULL;
+               }
+
+/* If the Handle wasn't used (because of an earlier error), return it
+   to the free Handles list. */
+            } else {
+               InsertHandle( ihandle, &free_handles, status );
+            }
+         }
+      }
+      UNLOCK_MUTEX2;
+   }
+
+/* If a bad status value was either supplied or generated within this
+   function, then annul the supplied pointer (unless it is NULL). */
+   if ( !astOK && this ) (void) astAnnul( this );
+
+/* Return the identifier value. */
+   return id;
+}
+
+AstObject *astMakePointer_( AstObject *this_id, int *status ) {
+/*
+*+
+*  Name:
+*     astMakePointer
+
+*  Purpose:
+*     Obtain a true C pointer from an Object identifier.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astMakePointer( AstObject *this )
+
+*  Class Membership:
+*     Object class function.
+
+*  Description:
+*     This function accepts an external Object identifier and returns
+*     a true C Object pointer that may be de-referenced to access the
+*     Object's data and methods.
+
+*  Parameters:
+*     this
+*        The identifier value.
+
+*  Returned Value:
+*     The true C pointer value.
+
+*  Notes:
+*     - In a thread-safe context, an error is reported if the supplied
+*     Object has not been locked by the calling thread (using astLock)
+*     prior to invoking this function.
+*     - The object reference count is not modified by this function,
+*     so the returned pointer should not be annulled by the caller.
+*     - Typically, this function should be used whenever a public
+*     function must accept identifier values directly (rather than
+*     having them translated automatically into pointers during
+*     argument validation by the astCheck<Class> range of functions).
+*     - Note that this function will NOT accept a true C pointer as an
+*     argument, even when invoked from internal code (with astCLASS
+*     defined). An identifier value MUST be supplied, and an error
+*     will result if it is not associated with an active Object.
+*     - This function attempts to execute even if the global error
+*     status is set, but no further error report will be made if it
+*     subsequently fails under these circumstances.
+*     - This is a protected function in the sense that it is not
+*     intended that external users should invoke it directly.  It is
+*     accessible from external code, however, in order that public
+*     macros invoked from that code can make use of it.
+*-
+*/
+
+/* Local Variables: */
+   AstObject *ptr;               /* Pointer value to return */
+   int ihandle;                  /* Handle offset in "handles" array */
+
+/* Initialise. */
+   ptr = NULL;
+
+/* Gain exclusive access to the handles array. */
+   LOCK_MUTEX2;
+
+/* Validate the identifier supplied and derive the Handle offset. */
+   ihandle = CheckId( this_id, 1, status );
+
+/* If the identifier was valid, extract the Object pointer from the
+   Handle. */
+   if ( ihandle != -1 ) ptr = handles[ ihandle ].ptr;
+
+   UNLOCK_MUTEX2;
+
+/* Return the result. */
+   return ptr;
+}
+
+AstObject *astMakePointer_NoLockCheck_( AstObject *this_id, int *status ) {
+/*
+*+
+*  Name:
+*     astMakePointer_NoLockCheck
+
+*  Purpose:
+*     Obtain a true C pointer from an Object identifier.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "object.h"
+*     AstObject *astMakePointer_NoLockCheck( AstObject *this )
+
+*  Class Membership:
+*     Object class function.
+
+*  Description:
+*     This function accepts an external Object identifier and returns
+*     a true C Object pointer that may be de-referenced to access the
+*     Object's data and methods.
+*
+*     It is identicial to astMakePointer except that it does not check
+*     that the supplied Object is locked by the running thread.
+
+*  Parameters:
+*     this
+*        The identifier value.
+
+*  Returned Value:
+*     The true C pointer value.
+
+*  Notes:
+*     - The object reference count is not modified by this function,
+*     so the returned pointer should not be annulled by the caller.
+*     - Typically, this function should be used whenever a public
+*     function must accept identifier values directly (rather than
+*     having them translated automatically into pointers during
+*     argument validation by the astCheck<Class> range of functions).
+*     - Note that this function will NOT accept a true C pointer as an
+*     argument, even when invoked from internal code (with astCLASS
+*     defined). An identifier value MUST be supplied, and an error
+*     will result if it is not associated with an active Object.
+*     - This function attempts to execute even if the global error
+*     status is set, but no further error report will be made if it
+*     subsequently fails under these circumstances.
+*     - This is a protected function in the sense that it is not
+*     intended that external users should invoke it directly.  It is
+*     accessible from external code, however, in order that public
+*     macros invoked from that code can make use of it.
+*-
+*/
+
+/* Local Variables: */
+   AstObject *ptr;               /* Pointer value to return */
+   int ihandle;                  /* Handle offset in "handles" array */
+
+/* Initialise. */
+   ptr = NULL;
+
+/* Gain exclusive access to the handles array. */
+   LOCK_MUTEX2;
+
+/* Validate the identifier supplied and derive the Handle offset. */
+   ihandle = CheckId( this_id, 0, status );
+
+/* If the identifier was valid, extract the Object pointer from the
+   Handle. */
+   if ( ihandle != -1 ) ptr = handles[ ihandle ].ptr;
+
+   UNLOCK_MUTEX2;
+
+/* Return the result. */
+   return ptr;
+}
+
+int astP2I_( AstObject *pointer, int *status ) {
+/*
+*+
+*  Name:
+*     astP2I
+
+*  Purpose:
+*     Extract an integer Object ID from a pointer.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+*     #include "object.h"
+*     int astP2I( AstObject *pointer )
+
+*  Class Membership:
+*     Object class function.
+
+*  Description:
+*     This function retrieves an integer (int) value representing an
+*     Object identifier from a pointer value (into which it has
+*     previously been packed using astI2P).
+*
+*     These functions should be used to avoid any dependency on
+*     integer-to-pointer conversions (given that the values are not
+*     true pointers) which might affect the exchange of Object
+*     identifier values with other languages, such as Fortran 77,
+*     where they are stored as integers.
+
+*  Parameters:
+*     pointer
+*       The pointer value into which the ID has previously been packed.
+
+*  Returned Value:
+*     The extracted Object identifier value as an integer (int).
+
+*  Notes:
+*     - This function does not perform error checking and does not
+*     generate errors.
+*     - This is a protected function in the sense that it is not
+*     intended that external users should invoke it directly.  It is
+*     accessible from external code, however, in order that public
+*     macros invoked from that code can make use of it.
+*-
+*/
+
+/* Local Variables: */
+   IdUnion temp;                 /* Overlapping int and pointer */
+
+/* Store the pointer value supplied. */
+   temp.pointer = pointer;
+
+/* Return the integer part of it. */
+   return temp.integer;
+}
+
+MYSTATIC void RemoveHandle( int ihandle, int *head, int *status ) {
+/*
+*  Name:
+*     RemoveHandle
+
+*  Purpose:
+*     Remove a Handle from a list.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void RemoveHandle( int ihandle, int *head )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function removes a Handle structure from a doubly linked
+*     list of such structures composed of elements drawn from the
+*     "handles" array. The "head of list" position is updated if
+*     necessary.
+
+*  Parameters:
+*     ihandle
+*        Offset in the "handles" array that identifies the Handle to
+*        be removed from the list (note that the Handle must actually
+*        be in the list, although this function does not check this).
+*     head
+*        Address of an int which holds the offset in the "handles"
+*        array of the element at the head of the list. This value will
+*        be updated if necessary to identify the new list head (or set
+*        to -1 if removing the Handle causes the list to become
+*        empty).
+
+*  Notes:
+*     - This function does not perform error chacking and does not
+*     generate errors.
+*     - See the InsertHandle function for details of how and why lists
+*     of Handles are constructed.
+*/
+
+
+#if defined(MEM_DEBUG)
+   char buf[80];
+   astHandleUse( ihandle, "about to be removed from %s", HeadString( head, buf ) );
+   CheckList( head, status );
+   CheckInList( ihandle, head, 1, status );
+#endif
+
+/* Check a head pointer was supplied (may not be if an error has
+   occurred). */
+   if( ! head ) return;
+
+/* Remove the Handle from the list by re-establishing links between
+   the elements on either side of it. */
+   handles[ ( handles[ ihandle ].blink ) ].flink = handles[ ihandle ].flink;
+   handles[ ( handles[ ihandle ].flink ) ].blink = handles[ ihandle ].blink;
+
+/* If the element removed was at the head of the list, update the head
+   of list offset to identify the following element. */
+   if ( ihandle == *head ) {
+      *head = handles[ ihandle ].flink;
+
+/* If the head of list still identifies the removed element, then note
+   that the list is now empty. */
+      if ( *head == ihandle ) *head = -1;
+   }
+
+/* Make the removed element point at itself. */
+   handles[ ihandle ].flink = ihandle;
+   handles[ ihandle ].blink = ihandle;
+
+#if defined(MEM_DEBUG)
+   astHandleUse( ihandle, "has been removed from %s", buf );
+   CheckList( head, status );
+#endif
+}
+
+void astSetId_( void *this_id_void, const char *settings, ... ) {
+/*
+*  Name:
+*     astSetId_
+
+*  Purpose:
+*     Set values for an Object's attributes via an identifier.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "object.h"
+*     void astSetId_( AstObject *this, const char *settings, ... )
+
+*  Class Membership:
+*     Object member function.
+
+*  Description:
+*     This function implements the axternal interface to the astSet
+*     method (q.v.). It accepts an Object identifier, but otherwise
+*     behaves identically to astSet.
+
+*  Parameters:
+*     this
+*        Object identifier.
+*     settings
+*        Pointer to a null-terminated string containing a
+*        comma-separated list of attribute settings.
+*     ...
+*        Optional arguments which supply values to be substituted for
+*        any "printf"-style format specifiers that appear in the
+*        "settings" string.
+
+*  Notes:
+*     - Because this function has a variable argument list, it is
+*     invoked by a macro that evaluates to a function pointer (not a
+*     function invocation) and no checking or casting of arguments is
+*     performed before the function is invoked. Because of this, the
+*     Object identifier is of type (void *) and is converted and
+*     validated within the function itself.
+*/
+
+/* Local Variables: */
+   AstObject *this;              /* Pointer to the Object structure */
+   int *status;                  /* Pointer to inherited status variable */
+   va_list args;                 /* Variable argument list */
+
+/* Get a pointer to the integer holding the inherited status value. */
+   status = astGetStatusPtr;
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Obtain the Object pointer from the ID supplied and validate the
+   pointer to ensure it identifies a valid Object. */
+   this = astCheckObject( astMakePointer( this_id_void ) );
+   if ( astOK ) {
+
+/* Obtain the variable argument list and pass all arguments to the
+   astVSet method for interpretation. */
+      va_start( args, settings );
+      astVSet( this, settings, NULL, args );
+      va_end( args );
+   }
+}
+
+int astThreadId_( AstObject *this_id, int ptr, int *status ) {
+/*
+c++
+*  Name:
+*     astThread
+
+*  Purpose:
+*     Determine the thread that owns an Object.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+*     #include "object.h"
+*     int astThread( AstObject *this, int ptr )
+
+*  Class Membership:
+*     Object method.
+
+*  Description:
+*     Returns an integer that indicates whether the supplied Object (or
+*     Object pointer) is currently unlocked, or is currently locked by
+*     the running thread, or another thread.
+
+*  Parameters:
+*     this
+*        Pointer to the Object to be checked.
+*     ptr
+*        If non-zero, returns information about the supplied Object
+*        pointer, rather than the Object structure itself. See "Object
+*        Pointers and Structures" below.
+
+*  Returned Value:
+*     astThread()
+*        A value of AST__UNLOCKED is returned if the Object (or pointer)
+*        is currently unlocked (i.e. has been unlocked using astUnlock
+*        but has not yet been locked using astLock). A value of
+*        AST__RUNNING is returned if the Object (or pointer) is currently
+*        locked by the running thread. A value of AST__OTHER is returned
+*        if the Object (or pointer) is currently locked by the another
+*        thread.
+
+*  Object Pointers and Structures:
+*     At any one time, an AST Object can have several distinct pointers,
+*     any one of which can be used to access the Object structure. For
+*     instance, the astClone function will produce a new distinct pointer
+*     for a given Object. In fact, an AST "pointer" is not a real pointer
+*     at all - it is an identifier for a "handle" structure, encoded to
+*     make it look like a pointer. Each handle contains (amongst othere
+*     things) a "real" pointer to the Object structure. This allows more
+*     than one handle to refer to the same Object structure. So when you
+*     call astClone (for instance) you get back an identifier for a new
+*     handle that refers to the same Object as the supplied handle.
+*
+*     In order to use an Object for anything useful, it must be locked
+*     for use by the running thread (either implicitly at creation or
+*     explicitly using astLock). The identity of the thread is stored in
+*     both the Object structure, and in the handle that was passed to
+*     astLock (or returned by the constructor function). Thus it is
+*     possible for a thread to have active pointers for Objects that are
+*     currently locked by another thread. In general, if such a pointer is
+*     passed to an AST function an error will be reported indicating that
+*     the Object is currently locked by another thread. The two exceptions
+*     to this is that astAnnul can be used to annull such a pointer, and
+*     this function can be used to return information about the pointer.
+*
+*     The other practical consequence of this is that when astEnd is
+*     called, all active pointers currently owned by the running thread
+*     (at the current context level) are annulled. This includes pointers
+*     for Objects that are currently locked by other threads.
+*
+*     If the "ptr" parameter is zero, then the returned value describes
+*     the Object structure itself. If "ptr" is non-zero, then the returned
+*     value describes the supplied Object pointer (i.e. handle), rather
+*     than the Object structure.
+
+*  Notes:
+*     - This function attempts to execute even if the global error
+*     status is set, but no further error report will be made if it
+*     subsequently fails under these circumstances.
+*     - This function is only available in the C interface.
+*     - This function always returns AST__RUNNING if the AST library has
+*     been built without POSIX thread support (i.e. the "-with-pthreads"
+*     option was not specified when running the "configure" script).
+c--
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS       /* Thread-specific global data */
+   int result;              /* The returned value */
+
+#if defined(THREAD_SAFE)
+
+/* More local Variables: */
+   AstObject *this;
+   int ihandle;
+   int check;
+
+/* Ensure global variables are accessable. */
+   astGET_GLOBALS(NULL);
+#endif
+
+/* Initialise the returned value */
+   result = AST__RUNNING;
+
+/* Nothing more to do if AST was not build with thread support. */
+#if defined(THREAD_SAFE)
+
+/* If the ownership of the handle is being queried... */
+   if( ptr ) {
+
+/* Lock the mutex that guards access to the handles array */
+      LOCK_MUTEX2;
+
+/* Check the supplied object identifier is valid and get the
+   corresponding index into the handles array. */
+      ihandle = CheckId( this_id, 1, status );
+      if( ihandle != -1 ) {
+
+/* Set the returned value on the basis of the threa didentifier stored in
+   the handle structure. */
+         if( handles[ ihandle ].thread == -1 ) {
+            result = AST__UNLOCKED;
+         } else if( handles[ ihandle ].thread != AST__THREAD_ID ) {
+            result = AST__OTHER;
+         }
+      }
+
+/* Unlock the mutex that guards access to the handles array */
+      UNLOCK_MUTEX2;
+
+/* Otherwise, the ownership of the Object is being queried. Obtain the
+   Object pointer from the ID supplied and validate the pointer to ensure
+   it identifies a valid Object (this generates an error if it doesn't).
+   Note, we use the "astMakePointer_NoLockCheck", since the usual
+   "astMakePointer" macro invokes astCheckLock to report an error if the
+   Object is not currently locked by the calling thread. */
+   } else if( astIsAObject( this = astMakePointer_NoLockCheck( this_id ) ) ) {
+
+/* Determine which thread (if any) has the object locked, and set an
+   appropriate return value. */
+      check = astManageLock( this, AST__CHECKLOCK, 0, NULL );
+
+      if( check == 5 ) {
+         result = AST__OTHER;
+      } else if( check == 6 ) {
+         result = AST__UNLOCKED;
+      }
+   }
+
+#endif
+
+/* Return the result. */
+   return result;
+}
+
+int astVersion_( int *status ) {
+/*
+*++
+*  Name:
+c     astVersion
+f     AST_VERSION
+
+*  Purpose:
+*     Return the version of the AST library being used.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     int astVersion
+f     RESULT = AST_VERSION()
+
+*  Class Membership:
+*     Object class function.
+
+*  Description:
+c     This macro invokes a function which
+f     This function
+*     returns an integer representing the version of the AST library
+*     being used. The library version is formatted as a string such as
+*     "2.0-7" which contains integers representing the "major version" (2),
+*     the "minor version" (0) and the "release" (7). The integer returned
+*     by this function combines all three integers together into a single
+*     integer using the expresion:
+*
+*     (major version)*1E6 + (minor version)*1E3 + (release)
+
+*  Returned Value:
+c     astVersion
+f     AST_VERSION = INTEGER
+*        The major version, minor version and release numbers for the AST
+*        library, encoded as a single integer.
+
+*  Applicability:
+*     Object
+c        This macro applies to all Objects.
+f        This routine applies to all Objects.
+
+*--
+*/
+
+   return (int) AST__VMAJOR*1E6 + AST__VMINOR*1E3 + AST__RELEASE;
+}
+
+int astEscapes_( int new_value, int *status ) {
+/*
+*++
+*  Name:
+c     astEscapes
+f     AST_ESCAPES
+
+*  Purpose:
+*     Control whether graphical escape sequences are included in strings.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "object.h"
+c     int astEscapes( int new_value )
+f     RESULT = AST_ESCAPES( NEWVAL, STATUS )
+
+*  Class Membership:
+*     Object class function.
+
+*  Description:
+*     The Plot class defines a set of escape sequences which can be
+*     included within a text string in order to control the appearance of
+*     sub-strings within the text. See the Escape attribute for a
+*     description of these escape sequences. It is usually inappropriate
+*     for AST to return strings containing such escape sequences when
+*     called by application code. For instance, an application which
+*     displays the value of the Title attribute of a Frame usually does
+*     not want the displayed string to include potentially long escape
+*     sequences which a human read would have difficuly interpreting.
+*     Therefore the default behaviour is for AST to strip out such escape
+*     sequences when called by application code. This default behaviour
+*     can be changed using this function.
+
+*  Parameters:
+c     new_value
+f     NEWVAL = INTEGER (Given)
+*        A flag which indicates if escapes sequences should be included
+*        in returned strings. If zero is supplied, escape sequences will
+*        be stripped out of all strings returned by any AST function. If
+*        a positive value is supplied, then any escape sequences will be
+*        retained in the value returned to the caller. If a negative
+*        value is supplied, the current value of the flag will be left
+*        unchanged.
+
+*  Returned Value:
+c     astEscapes
+f     AST_ESCAPES = INTEGER
+*        The value of the flag on entry to this function.
+
+*  Applicability:
+*     Object
+c        This macro applies to all Objects.
+f        This routine applies to all Objects.
+
+*  Notes:
+*     - This function also controls whether the
+c     astStripEscapes
+f     AST_STRIPESCAPES
+*     function removes escape sequences from the supplied string, or
+*     returns the supplied string without change.
+*     - This function attempts to execute even if an error has already
+*     occurred.
+
+*--
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS
+   int old_val;
+
+/* Get a pointer to Thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Save the old value. */
+   old_val = retain_esc;
+
+/* Set the new value. */
+   if( new_value > 0 ) {
+      retain_esc = 1;
+
+   } else if( new_value == 0 ) {
+      retain_esc = 0;
+   }
+
+/* Return the old value. */
+   return old_val;
+}
+
+
+#if defined(MEM_DEBUG)
+
+/* Check each handle in a list is uniquely connected to one other handle
+   in both the forward and backward directions. */
+
+void CheckList( int *head, int *status ) {
+   int ok;
+   int ihandle;
+   char buf[200];
+   astDECLARE_GLOBALS
+   if( !astOK ) return;
+
+   astGET_GLOBALS(NULL);
+
+   ok = 1;
+   if ( *head != -1 ) {
+      ihandle = *head;
+      if( handles[ handles[ ihandle ].blink ].flink != ihandle ||
+          handles[ handles[ ihandle ].flink ].blink != ihandle ) {
+         ok = 0;
+
+      } else {
+         if( CheckThread( ihandle, head, status ) ) {
+            ihandle= handles[ *head ].blink;
+            while( ihandle != *head ) {
+               if( handles[ handles[ ihandle ].blink ].flink != ihandle ||
+                   handles[ handles[ ihandle ].flink ].blink != ihandle ||
+                   CheckThread( ihandle, head, status ) == 0 ) {
+                  ok = 0;
+                  break;
+               }
+               ihandle= handles[ ihandle ].blink;
+            }
+         }
+      }
+   }
+
+   if( !ok ) {
+      printf("CheckList error in %s\n", HeadString( head, buf ) );
+      printf("   Central handle: %s\n", HandleString( ihandle, buf ) );
+
+      if( handles[ handles[ ihandle ].blink ].flink != ihandle ) {
+         printf("   Central handle->blink: %s\n",
+                 HandleString( handles[ ihandle ].blink, buf ) );
+         printf("   Central handle->blink->flink: %s\n",
+                 HandleString( handles[ handles[ ihandle ].blink ].flink, buf ) );
+      }
+
+      if( handles[ handles[ ihandle ].flink ].blink != ihandle ) {
+         printf("   Central handle->flink: %s\n",
+                 HandleString( handles[ ihandle ].flink, buf ) );
+         printf("   Central handle->flink->blink: %s\n",
+                 HandleString( handles[ handles[ ihandle ].flink ].blink, buf ) );
+      }
+   }
+
+}
+
+
+/* Check if a specified handle is, or is not, in a given list of handles. */
+
+void CheckInList( int ihandle, int *head, int in, int *status ){
+   char list[80], buf[200];
+   int found = 0;
+   if( !astOK ) return;
+
+   if ( *head != -1 ) {
+      if( ihandle == *head ) {
+         found = 1;
+      } else {
+         if( CheckThread( ihandle, head, status ) ) {
+            int jhandle= handles[ *head ].blink;
+            while( jhandle != *head ) {
+               if( ihandle == jhandle ) {
+                  found = 1;
+                  break;
+               }
+               jhandle= handles[ jhandle ].blink;
+            }
+         }
+      }
+   }
+
+   if( in && !found ) {
+      printf("Error: Handle %s not in %s\n", HandleString( ihandle, buf ),
+              HeadString( head, list ) );
+   } else if( !in && found ) {
+      printf("Error: Handle %s is in %s\n", HandleString( ihandle, buf ),
+              HeadString( head, list ) );
+   }
+
+}
+
+/* Check that a handle is owned by the currently executing thread. */
+
+int CheckThread( int ihandle, int *head, int *status ) {
+   int result = 1;
+
+#if defined(THREAD_SAFE)
+
+   char buf[200];
+   astDECLARE_GLOBALS
+   if( !astOK ) return result;
+
+   astGET_GLOBALS(NULL);
+
+   if( *head == unowned_handles  ) {
+      if(  handles[ ihandle ].thread != -1 ) {
+         printf("Handle %s has wrong thread: is %d, should "
+             "be -1 (i.e. unowned)\n", HandleString( ihandle, buf ),
+              handles[ ihandle ].thread );
+
+         result = 0;
+      }
+
+   } else if( *head == free_handles ) {
+      if(  handles[ ihandle ].thread != -1 ) {
+         printf("Handle %s has wrong thread: is %d, should "
+             "be -1 (i.e. free)\n", HandleString( ihandle, buf ),
+              handles[ ihandle ].thread );
+         result = 0;
+      }
+
+   } else if( handles[ ihandle ].thread != AST__THREAD_ID ) {
+      printf("Handle %s has wrong thread: is %d, should "
+             "be %d\n", HandleString( ihandle, buf ),
+              handles[ ihandle ].thread, AST__THREAD_ID );
+      result = 0;
+   }
+
+#endif
+
+   return result;
+}
+
+void astWatchHandle_( int handle ){
+   Watched_Handle = handle;
+}
+
+void astHandleUse_( int handle, const char *verb, ... ){
+   va_list args;
+   if( handle == Watched_Handle ) {
+      va_start( args, verb );
+      astHandleAlarm( verb, args );
+      va_end( args );
+   }
+}
+
+void astHandleAlarm_( const char *verb, va_list args ){
+   char buff[200], hbuf[200];
+   astDECLARE_GLOBALS
+   astGET_GLOBALS(NULL);
+
+   vsprintf( buff, verb, args );
+
+#if defined(THREAD_SAFE)
+   printf( "astHandleAlarm: Handle %s %s (current thread is %d).\n\n",
+           HandleString( Watched_Handle, hbuf ), buff, AST__THREAD_ID );
+#else
+   printf( "astHandleAlarm: Handle %s %s.\n\n",
+           HandleString( Watched_Handle, hbuf ), buff );
+#endif
+}
+
+MYSTATIC const char *HandleString( int ihandle, char *buf ){
+#if defined(THREAD_SAFE)
+   astDECLARE_GLOBALS
+   astGET_GLOBALS(NULL);
+
+   if( ihandle >= 0 ) {
+      sprintf( buf, "(index:%d v:%d c:%d t:%d i:%d cl:%s) [cur. thread: %d]",
+               ihandle,
+               handles[ ihandle ].check,
+               handles[ ihandle ].context, handles[ ihandle ].thread,
+               handles[ ihandle ].id,
+               handles[ ihandle ].vtab ? handles[ ihandle ].vtab->class : "<none>",
+               AST__THREAD_ID );
+   } else {
+      sprintf( buf, "(index:%d <invalid>) [cur. thread: %d]", ihandle,
+               AST__THREAD_ID );
+   }
+
+#else
+   if( ihandle >= 0 ) {
+      sprintf( buf, "(index:%d v:%d c:%d i:%d cl:%s)", ihandle,
+               handles[ ihandle ].check,
+               handles[ ihandle ].context, handles[ ihandle ].id,
+               handles[ ihandle ].vtab ? handles[ ihandle ].vtab->class : "<none>" );
+   } else {
+      sprintf( buf, "(index:%d <invalid>)", ihandle );
+   }
+#endif
+   return buf;
+}
+
+MYSTATIC const char *HeadString( int *head, char *list ){
+   int i;
+   astDECLARE_GLOBALS
+   astGET_GLOBALS(NULL);
+
+   if( head == &free_handles ) {
+      strcpy( list, "free_handles" );
+
+#if defined(THREAD_SAFE)
+   } else if( head == &unowned_handles ) {
+      strcpy( list, "unowned_handles" );
+#endif
+
+   } else {
+      *list = 0;
+      for( i = 0; i <= context_level; i++ ) {
+         if( *head == active_handles[ i ] ) {
+            sprintf( list, "active_handles[%d]", i );
+            break;
+         }
+      }
+      if( *list == 0 ) sprintf( list, "unknown handles list with head %d",
+                                *head );
+   }
+   return list;
+}
+
+#endif