upgrade ast 8.7.1

1 files changed, 6458 insertions, 0 deletions

diff --git a/ast/channel.c b/ast/channel.c
new file mode 100644
index 0000000..9219502
--- /dev/null
+++ b/ast/channel.c
@@ -0,0 +1,6458 @@
+/*
+*class++
+*  Name:
+*     Channel
+
+*  Purpose:
+*     Basic (textual) I/O channel.
+
+*  Constructor Function:
+c     astChannel
+f     AST_CHANNEL
+
+*  Description:
+*     The Channel class implements low-level input/output for the AST
+*     library.  Writing an Object to a Channel will generate a textual
+*     representation of that Object, and reading from a Channel will
+*     create a new Object from its textual representation.
+*
+*     Normally, when you use a Channel, you should provide "source"
+c     and "sink" functions which connect it to an external data store
+f     and "sink" routines which connect it to an external data store
+*     by reading and writing the resulting text. By default, however,
+*     a Channel will read from standard input and write to standard
+*     output. Alternatively, a Channel can be told to read or write from
+*     specific text files using the SinkFile and SourceFile attributes,
+*     in which case no sink or source function need be supplied.
+
+*  Inheritance:
+*     The Channel class inherits from the Object class.
+
+*  Attributes:
+*     In addition to those attributes common to all Objects, every
+*     Channel also has the following attributes:
+*
+*     - Comment: Include textual comments in output?
+*     - Full: Set level of output detail
+*     - Indent: Indentation increment between objects
+*     - ReportLevel: Selects the level of error reporting
+*     - SinkFile: The path to a file to which the Channel should write
+*     - Skip: Skip irrelevant data?
+*     - SourceFile: The path to a file from which the Channel should read
+*     - Strict: Generate errors instead of warnings?
+
+*  Functions:
+c     In addition to those functions applicable to all Objects, the
+c     following functions may also be applied to all Channels:
+f     In addition to those routines applicable to all Objects, the
+f     following routines may also be applied to all Channels:
+*
+c     - astWarnings: Return warnings from the previous read or write
+c     - astPutChannelData: Store data to pass to source or sink functions
+c     - astRead: Read an Object from a Channel
+c     - astWrite: Write an Object to a Channel
+f     - AST_WARNINGS: Return warnings from the previous read or write
+f     - AST_READ: Read an Object from a Channel
+f     - AST_WRITE: Write an Object to a Channel
+
+*  Copyright:
+*     Copyright (C) 1997-2006 Council for the Central Laboratory of the
+*     Copyright (C) 2009 Science & Technology Facilities Council.
+*     All Rights Reserved.
+*     Research Councils
+
+*  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)
+
+*  History:
+*     12-AUG-1996 (RFWS):
+*        Original version.
+*     6-SEP-1996:
+*        Finished initial implementation.
+*     11-DEC-1996 (RFWS):
+*        Added support for foreign language source and sink functions.
+*     28-APR-1997 (RFWS):
+*        Prevent "-0" being written (use "0" instead).
+*     27-NOV-2002 (DSB):
+*        Added astWriteInvocations.
+*     8-JAN-2003 (DSB):
+*        - Changed private InitVtab method to protected astInitChannelVtab
+*        method.
+*        - Modified to use protected Vtab initialisation methods when
+*        loading an Object.
+*     1-NOV-2003 (DSB):
+*        Change the initialiser so that it accepts source and sink
+*        wrapper functions as arguments (for use by derived classes).
+*     16-AUG-2006 (DSB):
+*        - Document non-destructive nature of unsuccessful astRead calls
+*        on a FitsChan.
+*     3-OCT-2008 (DSB):
+*        Added "Strict" attribute.
+*     11-DEC-2008 (DSB):
+*        Added astPutChannelData and astChannelData functions.
+*     16-JAN-2009 (DSB):
+*        Added astAddWarning and astWarnings.
+*     11-JUN-2009 (DSB):
+*        Enable astChannelData to be used from within astRead.
+*     7-DEC-2009 (DSB):
+*        Added Indent attribute.
+*     12-FEB-2010 (DSB):
+*        Represent AST__BAD externally using the string "<bad>".
+*     23-JUN-2011 (DSB):
+*        Added attributes SinkFile and SourceFile.
+*     2-OCT-2012 (DSB):
+*        Report an error if an Inf or NaN value is read from the external
+*        source.
+*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 Channel
+
+/* Define a string containing the maximum length of keywords used to
+   identify values in the external representation of data. This is
+   deliberately kept small so as to simplify integration with
+   standards such as FITS. */
+#define MAX_NAME "8"
+
+/* Max length of string returned by GetAttrib */
+#define GETATTRIB_BUFF_LEN 50
+
+/* String used to represent AST__BAD externally. */
+#define BAD_STRING "<bad>"
+
+/* Include files. */
+/* ============== */
+/* Interface definitions. */
+/* ---------------------- */
+
+#include "globals.h"             /* Thread-safe global data access */
+#include "error.h"               /* Error reporting facilities */
+#include "memory.h"              /* Memory allocation facilities */
+#include "object.h"              /* Base Object class */
+#include "channel.h"             /* Interface definition for this class */
+#include "loader.h"              /* Interface to the global loader */
+#include "keymap.h"              /* Storing arbitrary data in an AST Object */
+#include "pointset.h"            /* For AST__BAD */
+
+/* Error code definitions. */
+/* ----------------------- */
+#include "ast_err.h"             /* AST error codes */
+
+/* C header files. */
+/* --------------- */
+#include <ctype.h>
+#include <errno.h>
+#include <float.h>
+#include <limits.h>
+#include <stdarg.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <string.h>
+
+/* Module Variables. */
+/* ================= */
+
+/* Address of this static variable is used as a unique identifier for
+   member of this class. */
+static int class_check;
+
+/* Pointers to parent class methods which are extended by this class. */
+static const char *(* parent_getattrib)( AstObject *, const char *, int * );
+static int (* parent_testattrib)( AstObject *, const char *, int * );
+static void (* parent_clearattrib)( AstObject *, const char *, int * );
+static void (* parent_setattrib)( AstObject *, const char *, int * );
+
+/* Define macros for accessing each item of thread specific global data. */
+#ifdef THREAD_SAFE
+
+/* Define how to initialise thread-specific globals. */
+#define GLOBAL_inits \
+   globals->Class_Init = 0; \
+   globals->AstReadClassData_Msg = 0; \
+   globals->GetAttrib_Buff[ 0 ] = 0; \
+   globals->Items_Written = 0; \
+   globals->Current_Indent = 0; \
+   globals->Nest = -1; \
+   globals->Nwrite_Invoc = 0; \
+   globals->Object_Class = NULL; \
+   globals->Values_List = NULL; \
+   globals->Values_Class = NULL; \
+   globals->Values_OK = NULL; \
+   globals->End_Of_Object = NULL; \
+   globals->Channel_Data  = NULL;
+
+/* Create the function that initialises global data for this module. */
+astMAKE_INITGLOBALS(Channel)
+
+/* Define macros for accessing each item of thread specific global data. */
+#define class_init astGLOBAL(Channel,Class_Init)
+#define class_vtab astGLOBAL(Channel,Class_Vtab)
+#define astreadclassdata_msg astGLOBAL(Channel,AstReadClassData_Msg)
+#define getattrib_buff astGLOBAL(Channel,GetAttrib_Buff)
+#define items_written  astGLOBAL(Channel,Items_Written)
+#define current_indent astGLOBAL(Channel,Current_Indent)
+#define nest           astGLOBAL(Channel,Nest)
+#define nwrite_invoc   astGLOBAL(Channel,Nwrite_Invoc)
+#define object_class   astGLOBAL(Channel,Object_Class)
+#define values_list    astGLOBAL(Channel,Values_List)
+#define values_class   astGLOBAL(Channel,Values_Class)
+#define values_ok      astGLOBAL(Channel,Values_OK)
+#define end_of_object  astGLOBAL(Channel,End_Of_Object)
+#define channel_data   astGLOBAL(Channel,Channel_Data)
+
+
+
+static pthread_mutex_t mutex2 = PTHREAD_MUTEX_INITIALIZER;
+#define LOCK_MUTEX2 pthread_mutex_lock( &mutex2 );
+#define UNLOCK_MUTEX2 pthread_mutex_unlock( &mutex2 );
+
+static pthread_mutex_t mutex3 = PTHREAD_MUTEX_INITIALIZER;
+#define LOCK_MUTEX3 pthread_mutex_lock( &mutex3 );
+#define UNLOCK_MUTEX3 pthread_mutex_unlock( &mutex3 );
+
+/* If thread safety is not needed, declare and initialise globals at static
+   variables. */
+#else
+
+/* Contextual error message reported in astReadClassData? */
+static int astreadclassdata_msg = 0;
+
+/* Buffer returned by GetAttrib. */
+static char getattrib_buff[ GETATTRIB_BUFF_LEN + 1 ];
+
+/* Count of the number of output items written since the last "Begin"
+   or "IsA" item. */
+static int items_written = 0;
+
+/* Amount of indentation to be applied to the next output item. */
+static int current_indent = 0;
+
+/* Nesting level, used to keep track of data associated with building
+   Objects when they contain other Objects. */
+static int nest = -1;
+
+/* The number of times astWrite has been invoked. */
+static int nwrite_invoc = 0;
+
+/* Pointer to a user-supplied block of memory to be made available to
+   source or sink functions via the astChannelData function. */
+static void *channel_data = NULL;
+
+/***
+   The following items are all pointers to dynamically allocated
+   arrays (stacks) that grow as necessary to accommodate one element
+   for each level of nesting (one more than the value of "nest").
+***/
+
+/* Stack of pointers to null-terminated character strings giving the
+   names of the classes of the Objects being built at each nesting
+   level. */
+static char **object_class = NULL;
+
+/* Stack of pointers to the elements designated as the "heads" of
+   circular, doubly linked lists of name-value associations. */
+static AstChannelValue **values_list = NULL;
+
+/* Stack of pointers to null-terminated character strings giving the
+   names of the classes for which the values held in the values lists
+   are intended. */
+static char **values_class = NULL;
+
+/* Stack of flags indicating whether the values held in the values
+   lists are intended for the class loaders currently executing to
+   build Objects at each nesting level. */
+static int *values_ok = NULL;
+
+/* Stack of flags indicating whether "End" items have been read for
+   the Objects being built at each nesting level. */
+static int *end_of_object = NULL;
+
+
+/* Define the class virtual function table and its initialisation flag
+   as static variables. */
+static AstChannelVtab class_vtab;   /* Virtual function table */
+static int class_init = 0;       /* Virtual function table initialised? */
+#define LOCK_MUTEX2
+#define UNLOCK_MUTEX2
+#define LOCK_MUTEX3
+#define UNLOCK_MUTEX3
+
+#endif
+
+/* External Interface Function Prototypes. */
+/* ======================================= */
+/* The following functions have public prototypes only (i.e. no
+   protected prototypes), so we must provide local prototypes for use
+   within this module. */
+AstChannel *astChannelForId_( const char *(*)( void ),
+                              char *(*)( const char *(*)( void ), int * ),
+                              void (*)( const char * ),
+                              void (*)( void (*)( const char * ),
+                                        const char *, int * ),
+                              const char *, ... );
+AstChannel *astChannelId_( const char *(*)( void ), void (*)( const char * ), const char *, ... );
+
+/* Prototypes for Private Member Functions. */
+/* ======================================== */
+static AstObject *Read( AstChannel *, int * );
+static AstObject *ReadObject( AstChannel *, const char *, AstObject *, int * );
+static AstChannelValue *FreeValue( AstChannelValue *, int * );
+static AstChannelValue *LookupValue( const char *, int * );
+static AstKeyMap *Warnings( AstChannel *, int * );
+static char *GetNextText( AstChannel *, int * );
+static char *InputTextItem( AstChannel *, int * );
+static char *ReadString( AstChannel *, const char *, const char *, int * );
+static char *SourceWrap( const char *(*)( void ), int * );
+static const char *GetAttrib( AstObject *, const char *, int * );
+static double ReadDouble( AstChannel *, const char *, double, int * );
+static int GetComment( AstChannel *, int * );
+static int GetFull( AstChannel *, int * );
+static int GetSkip( AstChannel *, int * );
+static int GetStrict( AstChannel *, int * );
+static int ReadInt( AstChannel *, const char *, int, int * );
+static int TestAttrib( AstObject *, const char *, int * );
+static int TestComment( AstChannel *, int * );
+static int TestFull( AstChannel *, int * );
+static int TestSkip( AstChannel *, int * );
+static int TestStrict( AstChannel *, int * );
+static int Use( AstChannel *, int, int, int * );
+static int Write( AstChannel *, AstObject *, int * );
+static void AddWarning( AstChannel *, int, const char *, const char *, int * );
+static void AppendValue( AstChannelValue *, AstChannelValue **, int * );
+static void ClearAttrib( AstObject *, const char *, int * );
+static void ClearComment( AstChannel *, int * );
+static void ClearFull( AstChannel *, int * );
+static void ClearSkip( AstChannel *, int * );
+static void ClearStrict( AstChannel *, int * );
+static void ClearValues( AstChannel *, int * );
+static void Copy( const AstObject *, AstObject *, int * );
+static void Delete( AstObject *, int * );
+static void Dump( AstObject *, AstChannel *, int * );
+static void GetNextData( AstChannel *, int, char **, char **, int * );
+static void OutputTextItem( AstChannel *, const char *, int * );
+static void PutChannelData( AstChannel *, void *, int * );
+static void PutNextText( AstChannel *, const char *, int * );
+static void ReadClassData( AstChannel *, const char *, int * );
+static void RemoveValue( AstChannelValue *, AstChannelValue **, int * );
+static void SetAttrib( AstObject *, const char *, int * );
+static void SetComment( AstChannel *, int, int * );
+static void SetFull( AstChannel *, int, int * );
+static void SetSkip( AstChannel *, int, int * );
+static void SetStrict( AstChannel *, int, int * );
+static void SinkWrap( void (*)( const char * ), const char *, int * );
+static void Unquote( AstChannel *, char *, int * );
+static void WriteBegin( AstChannel *, const char *, const char *, int * );
+static void WriteDouble( AstChannel *, const char *, int, int, double, const char *, int * );
+static void WriteEnd( AstChannel *, const char *, int * );
+static void WriteInt( AstChannel *, const char *, int, int, int, const char *, int * );
+static void WriteIsA( AstChannel *, const char *, const char *, int * );
+static void WriteObject( AstChannel *, const char *, int, int, AstObject *, const char *, int * );
+static void WriteString( AstChannel *, const char *, int, int, const char *, const char *, int * );
+
+static int GetReportLevel( AstChannel *, int * );
+static int TestReportLevel( AstChannel *, int * );
+static void ClearReportLevel( AstChannel *, int * );
+static void SetReportLevel( AstChannel *, int, int * );
+
+static int GetIndent( AstChannel *, int * );
+static int TestIndent( AstChannel *, int * );
+static void ClearIndent( AstChannel *, int * );
+static void SetIndent( AstChannel *, int, int * );
+
+static const char *GetSourceFile( AstChannel *, int * );
+static int TestSourceFile( AstChannel *, int * );
+static void ClearSourceFile( AstChannel *, int * );
+static void SetSourceFile( AstChannel *, const char *, int * );
+
+static const char *GetSinkFile( AstChannel *, int * );
+static int TestSinkFile( AstChannel *, int * );
+static void ClearSinkFile( AstChannel *, int * );
+static void SetSinkFile( AstChannel *, const char *, int * );
+
+/* Member functions. */
+/* ================= */
+static void AddWarning( AstChannel *this, int level, const char *msg,
+                        const char *method, int *status ) {
+/*
+*+
+*  Name:
+*     astAddWarning
+
+*  Purpose:
+*     Add a warning to a Channel.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astAddWarning( AstChannel *this, int level, const char *msg,
+*                         const char *method, int status, ... )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function stores a warning message inside a Channel. These
+*     messages can be retirieved using astWarnings.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     level
+*        Ignore the warning if the ReportLevel attribute value is less
+*        than "level".
+*     msg
+*        The wanting message to store. It may contain printf format
+*        specifiers. If a NULL pointer is supplied, all warnings
+*        currently stored in the Channel are removed.
+*     method
+*        The method name.
+*     status
+*        Inherited status value.
+*     ...
+*        Extra values to substitute into the message string as
+*        replacements for the printf format specifiers.
+*-
+
+*  Note: The expansion of the printf format specifiers is done in the
+*     astAddWarning_ wrapper function. The AddWarning functions defined by
+*     each class receives the fully expanded message and does not have a
+*     variable argument list. The variable argument list is included in the
+*     above prologue in order to document the wrapper function.
+
+*/
+
+/* Local Variables: */
+   int i;          /* Message index */
+   char *a;        /* Pointer to copy of message */
+
+/* If a NULL pointer was supplied, free all warnings currently in the
+   Channel. Do this before checking the inherited status so that it works
+   even if an error has occurred. */
+   if( !msg ) {
+      for( i = 0; i < this->nwarn; i++ ) {
+         (this->warnings)[ i ] = astFree( (this->warnings)[ i ] );
+      }
+      this->warnings = astFree( this->warnings );
+      this->nwarn = 0;
+      return;
+   }
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Only proceed if the message level is sufficiently important. */
+   if( astGetReportLevel( this ) >= level ) {
+
+/* If we are being strict, issue an error rather than a warning. */
+      if( astGetStrict( this ) ) {
+         if( astOK ) {
+            astError( AST__BADIN, "%s(%s): %s", status, method,
+                      astGetClass( this ), msg );
+         }
+
+/* Otherwise, we store a copy of the message in the Channel. */
+      } else {
+
+/* Allocate memory and store a copy of th supplied string in it. */
+         a = astStore( NULL, msg, strlen( msg ) + 1 );
+
+/* Expand the array of warning pointers in ther Channel structure. */
+         this->warnings = astGrow( this->warnings, this->nwarn + 1,
+                                   sizeof( char * ) );
+
+/* If all is OK so far, store the new warning pointer, and increment the
+   number of warnings in the Channel. */
+         if( astOK ) {
+            (this->warnings)[ (this->nwarn)++ ] = a;
+
+/* Otherwise, attempt to free the memory holding the copy of the warning. */
+         } else {
+            a = astFree( a );
+         }
+      }
+   }
+}
+
+static void AppendValue( AstChannelValue *value, AstChannelValue **head, int *status ) {
+/*
+*  Name:
+*     AppendValue
+
+*  Purpose:
+*     Append a Value structure to a list.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void AppendValue( AstChannelValue *value, AstChannelValue **head, int *status )
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function appends a Value structure to a doubly linked
+*     circular list of such structures. The new list element is
+*     inserted just in front of the element occupying the "head of
+*     list" position (i.e. it becomes the new last element in the
+*     list).
+
+*  Parameters:
+*     value
+*        Pointer to the new element. This must not already be in the
+*        list.
+*     head
+*        Address of a pointer to the element at the head of the list
+*        (this pointer should be NULL if the list is initially
+*        empty). This pointer will only be updated if a new element is
+*        being added to an empty list.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Notes:
+*     - This function does not perform error chacking and does not
+*     generate errors.
+*/
+
+/* If the list is initially empty, the sole new element points at
+   itself. */
+   if ( !*head ) {
+      value->flink = value;
+      value->blink = value;
+
+/* Update the list head to identify the new element. */
+      *head = value;
+
+/* Otherwise, insert the new element in front of the element at the
+   head of the list. */
+   } else {
+      value->flink = *head;
+      value->blink = ( *head )->blink;
+      ( *head )->blink = value;
+      value->blink->flink = value;
+   }
+}
+
+void *astChannelData_( void ) {
+/*
+c++
+*  Name:
+*     astChannelData
+
+*  Purpose:
+*     Return a pointer to user-supplied data stored with a Channel.
+
+*  Type:
+*     Public macro.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void *astChannelData
+
+*  Class Membership:
+*     Channel macro.
+
+*  Description:
+*     This macro is intended to be used within the source or sink
+*     functions associated with a Channel. It returns any pointer
+*     previously stored in the Channel (that is, the Channel that has
+*     invoked the source or sink function) using astPutChannelData.
+*
+*     This mechanism is a thread-safe alternative to passing file
+*     descriptors, etc, via static global variables.
+
+*  Returned Value:
+*     astChannelData
+*        The pointer previously stored with the Channel using
+*        astPutChannelData. A NULL pointer will be returned if no such
+*        pointer has been stored with the Channel.
+
+*  Applicability:
+*     Channel
+*        This macro applies to all Channels.
+
+*  Notes:
+*     - This routine is not available in the Fortran 77 interface to
+*     the AST library.
+c--
+*/
+   astDECLARE_GLOBALS
+   astGET_GLOBALS(NULL);
+   return channel_data;
+}
+
+static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) {
+/*
+*  Name:
+*     ClearAttrib
+
+*  Purpose:
+*     Clear an attribute value for a Channel.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void ClearAttrib( AstObject *this, const char *attrib, int *status )
+
+*  Class Membership:
+*     Channel member function (over-rides the astClearAttrib protected
+*     method inherited from the Object class).
+
+*  Description:
+*     This function clears the value of a specified attribute for a
+*     Channel, so that the default value will subsequently be used.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     attrib
+*        Pointer to a null terminated string specifying the attribute
+*        name.  This should be in lower case with no surrounding white
+*        space.
+*     status
+*        Pointer to the inherited status variable.
+*/
+
+/* Local Variables: */
+   AstChannel *this;              /* Pointer to the Channel structure */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Obtain a pointer to the Channel structure. */
+   this = (AstChannel *) this_object;
+
+/* Check the attribute name and clear the appropriate attribute. */
+
+/* Comment. */
+/* -------- */
+   if ( !strcmp( attrib, "comment" ) ) {
+      astClearComment( this );
+
+/* Full. */
+/* ----- */
+   } else if ( !strcmp( attrib, "full" ) ) {
+      astClearFull( this );
+
+/* Indent. */
+/* ------- */
+   } else if ( !strcmp( attrib, "indent" ) ) {
+      astClearIndent( this );
+
+/* ReportLevel. */
+/* ------------ */
+   } else if ( !strcmp( attrib, "reportlevel" ) ) {
+      astClearReportLevel( this );
+
+/* Skip. */
+/* ----- */
+   } else if ( !strcmp( attrib, "skip" ) ) {
+      astClearSkip( this );
+
+/* SourceFile. */
+/* ----------- */
+   } else if ( !strcmp( attrib, "sourcefile" ) ) {
+      astClearSourceFile( this );
+
+/* SinkFile. */
+/* --------- */
+   } else if ( !strcmp( attrib, "sinkfile" ) ) {
+      astClearSinkFile( this );
+
+/* Strict. */
+/* ------- */
+   } else if ( !strcmp( attrib, "strict" ) ) {
+      astClearStrict( this );
+
+/* If the attribute is still not recognised, pass it on to the parent
+   method for further interpretation. */
+   } else {
+      (*parent_clearattrib)( this_object, attrib, status );
+   }
+}
+
+static void ClearValues( AstChannel *this, int *status ) {
+/*
+*  Name:
+*     ClearValues
+
+*  Purpose:
+*     Clear the current values list.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void ClearValues( AstChannel *this, int *status )
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function clears any (un-read) Value structures remaining in
+*     the current values list (i.e. at the current nesting level). It
+*     should be invoked after all required values have been read.
+*
+*     If the values list has not been read, or if any remaining values
+*     are found (i.e. the list is not empty) then this indicates an
+*     unrecognised input class or an input value that has not been
+*     read by a class loader. This implies an error in the loader, or
+*     bad input data, so an error is reported.
+*
+*     All resources used by any remaining Value structures are freed
+*     and the values list is left in an empty state.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel being read. This is only used for
+*        constructing error messages. It must not be NULL.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Notes:
+*     - This function attempts to execute even if the global error
+*     status is set on entry, although no further error report will be
+*     made if it subsequently fails under these circumstances.
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+   AstChannelValue **head;       /* Address of pointer to values list */
+   AstChannelValue *value;       /* Pointer to value list element */
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* If "values_class" is non-NULL, then the values list has previously
+   been filled with Values for a class. */
+   if ( values_class[ nest ] ) {
+
+/* If "values_ok" is zero, however, then these Values have not yet
+   been read by a class loader. This must be due to a bad class name
+   associated with them or because the class data are not available in
+   the correct order. If we are using strict error reporting, then report
+   an error (unless the error status is already set). */
+      if ( astGetStrict( this ) && !values_ok[ nest ] && astOK ) {
+         astError( AST__BADIN,
+                   "astRead(%s): Invalid class structure in input data.", status,
+                   astGetClass( this ) );
+         astError( AST__BADIN,
+                   "Class \"%s\" is invalid or out of order within a %s.", status,
+                   values_class[ nest ], object_class[ nest ] );
+      }
+
+/* Free the memory holding the class string. */
+      values_class[ nest ] = astFree( values_class[ nest ] );
+   }
+
+/* Reset the "values_ok" flag. */
+   values_ok[ nest ] = 0;
+
+/* Now clear any Values remaining in the values list. Obtain the
+   address of the pointer to the head of this list (at the current
+   nesting level) and loop to remove Values from the list while it is
+   not empty. */
+   head = values_list + nest;
+   while ( *head ) {
+
+/* Obtain a pointer to the first element. */
+      value = *head;
+
+/* Issue a warning. */
+      if ( value->is_object ) {
+         astAddWarning( this, 1, "The Object \"%s = <%s>\" was "
+                        "not recognised as valid input.", "astRead", status,
+                        value->name, astGetClass( value->ptr.object ) );
+      } else {
+         astAddWarning( this, 1, "The value \"%s = %s\" was not "
+                        "recognised as valid input.", "astRead", status,
+                        value->name, value->ptr.string );
+      }
+
+/* Remove the Value structure from the list (which updates the head of
+   list pointer) and free its resources. */
+      RemoveValue( value, head, status );
+      value = FreeValue( value, status );
+   }
+}
+
+static AstChannelValue *FreeValue( AstChannelValue *value, int *status ) {
+/*
+*  Name:
+*     FreeValue
+
+*  Purpose:
+*     Free a dynamically allocated Value structure.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     AstChannelValue *FreeValue( AstChannelValue *value, int *status )
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function frees a dynamically allocated Value structure,
+*     releasing all resources used by it. The structure contents must
+*     have been correctly initialised.
+
+*  Parameters:
+*     value
+*        Pointer to the Value structure to be freed.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Returned Value:
+*     A NULL pointer is always returned.
+
+*  Notes:
+*     - This function attempts to execute even if the global error
+*     status is set on entry, although no further error report will be
+*     made if it subsequently fails under these circumstances.
+*/
+
+/* Check that a non-NULL pointer has been supplied. */
+   if ( value ) {
+
+/* If the "name" component has been allocated, then free it. */
+      if ( value->name ) value->name = astFree( value->name );
+
+/* If the "ptr" component identifies an Object, then annul the Object
+   pointer. */
+      if ( value->is_object ) {
+         if ( value->ptr.object ) {
+            value->ptr.object = astAnnul( value->ptr.object );
+         }
+
+/* Otherwise, if it identifies a string, then free the string. */
+      } else {
+         if ( value->ptr.string ) {
+            value->ptr.string = astFree( value->ptr.string );
+         }
+      }
+
+/* Free the Value structure itself. */
+      value = astFree( value );
+   }
+
+/* Return a NULL pointer. */
+   return NULL;
+}
+
+static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) {
+/*
+*  Name:
+*     GetAttrib
+
+*  Purpose:
+*     Get the value of a specified attribute for a Channel.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     const char *GetAttrib( AstObject *this, const char *attrib, int *status )
+
+*  Class Membership:
+*     Channel member function (over-rides the protected astGetAttrib
+*     method inherited from the Object class).
+
+*  Description:
+*     This function returns a pointer to the value of a specified
+*     attribute for a Channel, formatted as a character string.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     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.
+*     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 Channel, 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 Channel. 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            /* Declare the thread specific global data */
+   AstChannel *this;             /* Pointer to the Channel structure */
+   const char *result;           /* Pointer value to return */
+   int comment;                  /* Comment attribute value */
+   int full;                     /* Full attribute value */
+   int indent;                   /* Indent attribute value */
+   int report_level;             /* ReportLevel attribute value */
+   int skip;                     /* Skip attribute value */
+   int strict;                   /* Report errors insead of warnings? */
+
+/* Initialise. */
+   result = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this_object);
+
+/* Obtain a pointer to the Channel structure. */
+   this = (AstChannel *) this_object;
+
+/* 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. */
+
+/* Comment. */
+/* -------- */
+   if ( !strcmp( attrib, "comment" ) ) {
+      comment = astGetComment( this );
+      if ( astOK ) {
+         (void) sprintf( getattrib_buff, "%d", comment );
+         result = getattrib_buff;
+      }
+
+/* Full. */
+/* ----- */
+   } else if ( !strcmp( attrib, "full" ) ) {
+      full = astGetFull( this );
+      if ( astOK ) {
+         (void) sprintf( getattrib_buff, "%d", full );
+         result = getattrib_buff;
+      }
+
+/* Indent. */
+/* ------- */
+   } else if ( !strcmp( attrib, "indent" ) ) {
+      indent = astGetIndent( this );
+      if ( astOK ) {
+         (void) sprintf( getattrib_buff, "%d", indent );
+         result = getattrib_buff;
+      }
+
+/* ReportLevel. */
+/* ------------ */
+   } else if ( !strcmp( attrib, "reportlevel" ) ) {
+      report_level = astGetReportLevel( this );
+      if ( astOK ) {
+         (void) sprintf( getattrib_buff, "%d", report_level );
+         result = getattrib_buff;
+      }
+
+/* Skip. */
+/* ----- */
+   } else if ( !strcmp( attrib, "skip" ) ) {
+      skip = astGetSkip( this );
+      if ( astOK ) {
+         (void) sprintf( getattrib_buff, "%d", skip );
+         result = getattrib_buff;
+      }
+
+/* SourceFile. */
+/* ----------- */
+   } else if ( !strcmp( attrib, "sourcefile" ) ) {
+      result = astGetSourceFile( this );
+
+/* SinkFile. */
+/* --------- */
+   } else if ( !strcmp( attrib, "sinkfile" ) ) {
+      result = astGetSinkFile( this );
+
+/* Strict. */
+/* ------- */
+   } else if ( !strcmp( attrib, "strict" ) ) {
+      strict = astGetStrict( this );
+      if ( astOK ) {
+         (void) sprintf( getattrib_buff, "%d", strict );
+         result = getattrib_buff;
+      }
+
+/* If the attribute name was not recognised, pass it on to the parent
+   method for further interpretation. */
+   } else {
+      result = (*parent_getattrib)( this_object, attrib, status );
+   }
+
+/* Return the result. */
+   return result;
+
+}
+
+static void GetNextData( AstChannel *this, int skip, char **name,
+                         char **val, int *status ) {
+/*
+*+
+*  Name:
+*     astGetNextData
+
+*  Purpose:
+*     Read the next item of data from a data source.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astGetNextData( AstChannel *this, int skip, char **name,
+*                          char **val )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function reads the next item of input data from a data
+*     source associated with a Channel and returns the result.
+*
+*     It is layered conceptually on the astGetNextText method, but
+*     instead of returning the raw input text, it decodes it and
+*     returns name/value pairs ready for use. Note that in some
+*     derived classes, where the data are not stored as text, this
+*     function may not actually use astGetNextText, but will access
+*     the data directly.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     skip
+*        A non-zero value indicates that a new Object is to be read,
+*        and that all input data up to the next "Begin" item are to be
+*        skipped in order to locate it. This is useful if the data
+*        source contains AST objects interspersed with other data (but
+*        note that these other data cannot appear inside AST Objects,
+*        only between them).
+*
+*        A zero value indicates that all input data are significant
+*        and the next item will therefore be read and an attempt made
+*        to interpret it whatever it contains. Any other data
+*        inter-mixed with AST Objects will then result in an error.
+*     name
+*        An address at which to store a pointer to a null-terminated
+*        dynamically allocated string containing the name of the next
+*        item in the input data stream. This name will be in lower
+*        case with no surrounding white space.  It is the callers
+*        responsibilty to free the memory holding this string (using
+*        astFree) when it is no longer required.
+*
+*        A NULL pointer value will be returned (without error) to
+*        indicate when there are no further input data items to be
+*        read.
+*     val
+*        An address at which to store a pointer to a null-terminated
+*        dynamically allocated string containing the value associated
+*        with the next item in the input data stream. No case
+*        conversion is performed on this string and all white space is
+*        potentially significant.  It is the callers responsibilty to
+*        free the memory holding this string (using astFree) when it
+*        is no longer required.
+*
+*        The returned pointer will be NULL if an Object data item is
+*        read (see the "Data Representation" section).
+
+*  Data Representation:
+*     The returned data items fall into the following categories:
+*
+*     - Begin: Identified by the name string "begin", this indicates
+*     the start of an Object definition. The associated value string
+*     gives the class name of the Object being defined.
+*
+*     - IsA: Identified by the name string "isa", this indicates the
+*     end of the data associated with a particular class structure
+*     within the definiton of a larger Object. The associated value
+*     string gives the name of the class whose data have just been
+*     read.
+*
+*     - End: Identified by the name string "end", this indicates the
+*     end of the data associated with a complete Object
+*     definition. The associated value string gives the class name of
+*     the Object whose definition is being ended.
+*
+*     - Non-Object: Identified by any other name string plus a
+*     non-NULL "val" pointer, this gives the value of a non-Object
+*     structure component (instance variable). The name identifies
+*     which instance variable it is (within the context of the class
+*     whose data are being read) and the value is encoded as a string.
+*
+*     - Object: Identified by any other name string plus a NULL "val"
+*     pointer, this identifies the value of an Object structure
+*     component (instance variable).  The name identifies which
+*     instance variable it is (within the context of the class whose
+*     data are being read) and the value is given by subsequent data
+*     items (so the next item should be a "Begin" item).
+
+*  Notes:
+*     - NULL pointer values will be returned if this function is
+*     invoked with the global error status set, or if it should fail
+*     for any reason.
+*     - This method is provided primarily so that derived classes may
+*     over-ride it in order to read from alternative data sources. It
+*     provides a higher-level interface than astGetNextText, so is
+*     suitable for classes that either need to read textual data in a
+*     different format, or to read from non-textual data sources.
+*-
+*/
+
+/* Local Variables: */
+   char *line;                   /* Pointer to input text line */
+   int done;                     /* Data item read? */
+   int i;                        /* Loop counter for string characters */
+   int len;                      /* Length of input text line */
+   int nc1;                      /* Offset to start of first field */
+   int nc2;                      /* Offset to end of first field */
+   int nc3;                      /* Offset to start of second field */
+   int nc;                       /* Number of charaters read by "astSscanf" */
+
+/* Initialise the returned values. */
+   *name = NULL;
+   *val = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Read the next input line as text (the loop is needed to allow
+   initial lines to be skipped if the "skip" flag is set). */
+   done = 0;
+   while ( !done && ( line = InputTextItem( this, status ) ) && astOK ) {
+
+/* If OK, determine the line length. */
+      len = strlen( line );
+
+/* Non-Object value. */
+/* ----------------- */
+/* Test for lines of the form " name = value" (or similar), where the
+   name is no more than MAX_NAME characters long (the presence of a
+   value on the right hand side indicates that this is a non-Object
+   value, encoded as a string). Ignore these lines if the "skip" flag
+   is set. */
+      if ( nc = 0,
+           ( !skip
+             && ( 0 == astSscanf( line,
+                               " %n%*" MAX_NAME "[^ \t=]%n = %n%*[^\n]%n",
+                               &nc1, &nc2, &nc3, &nc ) )
+             && ( nc >= len ) ) ) {
+
+/* Note we have found a data item. */
+         done = 1;
+
+/* Extract the name and value fields. */
+         *name = astString( line + nc1, nc2 - nc1 );
+         *val = astString( line + nc3, len - nc3 );
+
+/* If OK, truncate the value to remove any trailing white space. */
+         if ( astOK ) {
+            i = len - nc3 - 1;
+            while ( ( i >= 0 ) && isspace( ( *val )[ i ] ) ) i--;
+            ( *val )[ i + 1 ] = '\0';
+
+/* Also remove any quotes from the string. */
+            Unquote( this, *val, status );
+         }
+
+/* Object value. */
+/* ------------- */
+/* Test for lines of the form " name = " (or similar), where the name
+   is no more than MAX_NAME characters long (the absence of a value on
+   the right hand side indicates that this is an Object, whose
+   definition follows on subsequent input lines). Ignore these lines
+   if the "skip" flag is set. */
+      } else if ( nc = 0,
+                  ( !skip
+                    && ( 0 == astSscanf( line,
+                                      " %n%*" MAX_NAME "[^ \t=]%n = %n",
+                                      &nc1, &nc2, &nc ) )
+                    && ( nc >= len ) ) ) {
+
+/* Note we have found a data item. */
+         done = 1;
+
+/* Extract the name field but leave the value pointer as NULL. */
+         *name = astString( line + nc1, nc2 - nc1 );
+
+/* Begin. */
+/* ------ */
+/* Test for lines of the form " Begin Class " (or similar). */
+      } else if ( nc = 0,
+             ( ( 0 == astSscanf( line,
+                             " %*1[Bb]%*1[Ee]%*1[Gg]%*1[Ii]%*1[Nn] %n%*s%n %n",
+                              &nc1, &nc2, &nc ) )
+               && ( nc >= len ) ) ) {
+
+/* Note we have found a data item. */
+         done = 1;
+
+/* Set the returned name to "begin" and extract the associated class
+   name for the value. Store both of these in dynamically allocated
+   strings. */
+         *name = astString( "begin", 5 );
+         *val = astString( line + nc1, nc2 - nc1 );
+
+/* IsA. */
+/* ---- */
+/* Test for lines of the form " IsA Class " (or similar). Ignore these
+   lies if the "skip" flag is set. */
+      } else if ( nc = 0,
+                  ( !skip
+                    && ( 0 == astSscanf( line,
+                                      " %*1[Ii]%*1[Ss]%*1[Aa] %n%*s%n %n",
+                                      &nc1, &nc2, &nc ) )
+                    && ( nc >= len ) ) ) {
+
+/* Note we have found a data item. */
+         done = 1;
+
+/* Set the returned name to "isa" and extract the associated class
+   name for the value. */
+         *name = astString( "isa", 3 );
+         *val = astString( line + nc1, nc2 - nc1 );
+
+/* End. */
+/* ---- */
+/* Test for lines of the form " End Class " (or similar). Ignore these
+   lines if the "skip" flag is set. */
+      } else if ( nc = 0,
+                  ( !skip
+                    && ( 0 == astSscanf( line,
+                                      " %*1[Ee]%*1[Nn]%*1[Dd] %n%*s%n %n",
+                                      &nc1, &nc2, &nc ) )
+                    && ( nc >= len ) ) ) {
+
+/* Note we have found a data item. */
+         done = 1;
+
+/* If found, set the returned name to "end" and extract the associated
+   class name for the value. */
+         *name = astString( "end", 3 );
+         *val = astString( line + nc1, nc2 - nc1 );
+
+/* If the input line didn't match any of the above and the "skip" flag
+   is not set, then report an error. */
+      } else if ( !skip ) {
+         astError( AST__BADIN,
+                   "astRead(%s): Cannot interpret the input data: \"%s\".", status,
+                   astGetClass( this ), line );
+      }
+
+/* Free the memory holding the input data as text. */
+      line = astFree( line );
+   }
+
+/* If successful, convert the name to lower case. */
+   if ( astOK && *name ) {
+      for ( i = 0; ( *name )[ i ]; i++ ) {
+         ( *name )[ i ] = tolower( ( *name )[ i ] );
+      }
+   }
+
+/* If an error occurred, ensure that any memory allocated is freed and
+   that NULL pointer values are returned. */
+   if ( !astOK ) {
+      *name = astFree( *name );
+      *val = astFree( *val );
+   }
+}
+
+static char *GetNextText( AstChannel *this, int *status ) {
+/*
+*+
+*  Name:
+*     GetNextText
+
+*  Purpose:
+*     Read the next line of input text from a data source.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     char *astGetNextText( AstChannel *this )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function reads the next "raw" input line of text from the
+*     data source associated with a Channel.
+*
+*     Each line is returned as a pointer to a null-terminated string
+*     held in dynamic memory, and it is the caller's responsibility to
+*     free this memory (using astFree) when it is no longer
+*     required. A NULL pointer is returned if there are no more input
+*     lines to be read.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+
+*  Returned Value:
+*     Pointer to a null-terminated string containing the input line
+*     (held in dynamically allocated memory, which must be freed by
+*     the caller when no longer required). A NULL pointer is returned
+*     if there are no more input lines to be read.
+
+*  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.
+*     - This method is provided primarily so that derived classes may
+*     over-ride it in order to read from alternative (textual) data
+*     sources.
+*-
+*/
+
+/* Local Constants: */
+#define MIN_CHARS 81             /* Initial size for allocating memory */
+#define ERRBUF_LEN 80
+
+/* Local Variables: */
+   FILE *fd;                     /* Input file descriptor */
+   char *errstat;                /* Pointer for system error message */
+   char *line;                   /* Pointer to line data to be returned */
+   char errbuf[ ERRBUF_LEN ];    /* Buffer for system error message */
+   const char *sink_file;        /* Path to output sink file */
+   const char *source_file;      /* Path to source file */
+   int c;                        /* Input character */
+   int len;                      /* Length of input line */
+   int readstat;                 /* "errno" value set by "getchar" */
+   int size;                     /* Size of allocated memory */
+
+/* Initialise. */
+   line = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return line;
+
+/* If the SourceFile attribute of the Channel specifies an input file,
+   but no input file has yet been opened, open it now. Report an error if
+   it is the same as the sink file. */
+   if( astTestSourceFile( this ) && !this->fd_in ) {
+      source_file = astGetSourceFile( this );
+
+      if( this->fd_out ) {
+         sink_file = astGetSinkFile( this );
+         if( astOK && !strcmp( sink_file, source_file ) ) {
+            astError( AST__RDERR, "astRead(%s): Failed to open input "
+                      "SourceFile '%s' - the file is currently being used "
+                      "as the output SinkFile.", status, astGetClass( this ),
+                      source_file );
+         }
+      }
+
+      if( astOK ) {
+         this->fd_in = fopen( source_file, "r" );
+         if( !this->fd_in ) {
+            if ( errno ) {
+#if HAVE_STRERROR_R
+               strerror_r( errno, errbuf, ERRBUF_LEN );
+               errstat = errbuf;
+#else
+               errstat = strerror( errno );
+#endif
+               astError( AST__RDERR, "astRead(%s): Failed to open input "
+                         "SourceFile '%s' - %s.", status, astGetClass( this ),
+                         source_file, errstat );
+            } else {
+               astError( AST__RDERR, "astRead(%s): Failed to open input "
+                         "SourceFile '%s'.", status, astGetClass( this ),
+                         source_file );
+            }
+         }
+
+      }
+   }
+
+/* Source function defined, but no input file. */
+/* ------------------------------------------- */
+/* If no active input file descriptor is stored in the Channel, but
+   a source function (and its wrapper function) is defined for the
+   Channel, use the wrapper function to invoke the source function to
+   read a line of input text. This is returned in a dynamically
+   allocated string. */
+   if ( !this->fd_in && this->source && this->source_wrap ) {
+
+/* About to call an externally supplied function which may not be
+   thread-safe, so lock a mutex first. Also store the channel data
+   pointer in a global variable so that it can be accessed in the source
+   function using macro astChannelData. */
+      astStoreChannelData( this );
+      LOCK_MUTEX3;
+      line = ( *this->source_wrap )( this->source, status );
+      UNLOCK_MUTEX3;
+
+/* Input file defined, or no source function. */
+/* ------------------------------------------ */
+/* Read the line from the input file or from standard input. */
+   } else if( astOK ) {
+      c = '\0';
+      len = 0;
+      size = 0;
+
+/* Choose the file descriptor to use. */
+      fd = this->fd_in ? this->fd_in : stdin;
+
+/* Loop to read input characters, saving any "errno" value that may be
+   set by "getchar" if an error occurs. Quit if an end of file (or
+   error) occurs or if a newline character is read. */
+      while ( errno = 0, c = getc( fd ), readstat = errno,
+              ( c != EOF ) && ( c != '\n' ) ) {
+
+/* If no memory has yet been allocated to hold the line, allocate some
+   now, using MIN_CHARS as the initial line length. */
+         if ( !line ) {
+            line = astMalloc( sizeof( char ) * (size_t) MIN_CHARS );
+            size = MIN_CHARS;
+
+/* If memory has previously been allocated, extend it when necessary
+   to hold the new input character (plus a terminating null) and note
+   the new size. */
+         } else if ( ( len + 2 ) > size ) {
+            line = astGrow( line, len + 2, sizeof( char ) );
+            if ( !astOK ) break;
+            size = (int) astSizeOf( line );
+         }
+
+/* Store the character just read. */
+         line[ len++ ] = c;
+      }
+
+/* If the above loop completed without setting the global error
+   status, check the last character read and use "ferror" to see if a
+   read error occurred. If so, report the error, using the saved
+   "errno" value (but only if one was set). */
+      if ( astOK && ( c == EOF ) && ferror( fd ) ) {
+         if ( readstat ) {
+#if HAVE_STRERROR_R
+            strerror_r( readstat, errbuf, ERRBUF_LEN );
+            errstat = errbuf;
+#else
+            errstat = strerror( readstat );
+#endif
+            astError( AST__RDERR,
+                      "astRead(%s): Read error on standard input - %s.", status,
+                      astGetClass( this ), errstat );
+         } else {
+            astError( AST__RDERR,
+                      "astRead(%s): Read error on standard input.", status,
+                      astGetClass( this ) );
+         }
+      }
+
+/* If an empty line has been read, allocate memory to hold an empty
+   string. */
+      if ( !line && ( c == '\n' ) ) {
+         line = astMalloc( sizeof( char ) );
+      }
+
+/* If memory has been allocated and there has been no error,
+   null-terminate the string of input characters. */
+      if ( line ) {
+         if ( astOK ) {
+            line[ len ] = '\0';
+
+/* If there has been an error, free the allocated memory. */
+         } else {
+            line = astFree( line );
+         }
+      }
+   }
+
+
+/* Return the result pointer. */
+   return line;
+
+/* Undefine macros local to this function. */
+#undef MIN_CHARS
+#undef ERRBUF_LEN
+}
+
+static AstKeyMap *Warnings( AstChannel *this, int *status ){
+/*
+*++
+*  Name:
+c     astWarnings
+f     AST_WARNINGS
+
+*  Purpose:
+*     Returns any warnings issued by the previous read or write operation.
+
+*  Type:
+*     Public virtual function.
+
+*  Synopsis:
+c     #include "channel.h"
+c     AstKeyMap *astWarnings( AstChannel *this )
+f     RESULT = AST_WARNINGS( THIS, STATUS )
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function returns an AST KeyMap object holding the text of any
+*     warnings issued as a result of the previous invocation of the
+c     astRead or astWrite
+f     AST_READ or AST_WRITE
+*     function on the Channel. If no warnings were issued, a
+c     a NULL value
+f     AST__NULL
+*     will be returned.
+*
+*     Such warnings are non-fatal and will not prevent the
+*     read or write operation succeeding. However, the converted object
+*     may not be identical to the original object in all respects.
+*     Differences which would usually be deemed as insignificant in most
+*     usual cases will generate a warning, whereas more significant
+*     differences will generate an error.
+*
+*     The "Strict" attribute allows this warning facility to be switched
+*     off, so that a fatal error is always reported for any conversion
+*     error.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the Channel.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astWarnings()
+f     AST_WARNINGS = INTEGER
+*        A pointer to the KeyMap holding the warning messages, or
+c        NULL
+f        AST__NULL
+*        if no warnings were issued during the previous read operation.
+
+*  Applicability:
+*     Channel
+*        The basic Channel class generates a warning when ever an
+*        un-recognised item is encountered whilst reading an Object from
+*        an external data source. If Strict is zero (the default), then
+*        unexpected items in the Object description are simply ignored,
+*        and any remaining items are used to construct the returned
+*        Object. If Strict is non-zero, an error will be reported and a
+*        NULL Object pointer returned if any unexpected items are
+*        encountered.
+*
+*        As AST continues to be developed, new attributes are added
+*        occasionally to selected classes. If an older version of AST is
+*        used to read external Object descriptions created by a more
+*        recent version of AST, then the Channel class will, by default,
+*        ignore the new attributes, using the remaining attributes to
+*        construct the Object. This is usually a good thing. However,
+*        since external Object descriptions are often stored in plain
+*        text, it is possible to edit them using a text editor. This
+*        gives rise to the possibility of genuine errors in the
+*        description due to finger-slips, typos, or simple
+*        mis-understanding. Such inappropriate attributes will be ignored
+*        if Strict is left at its default zero value. This will cause the
+*        mis-spelled attribute to revert to its default value,
+*        potentially causing subtle changes in the behaviour of
+*        application software. If such an effect is suspected, the Strict
+*        attribute can be set non-zero, resulting in the erroneous
+*        attribute being identified in an error message.
+*     FitsChan
+*        The returned KeyMap will contain warnings for all conditions
+*        listed in the Warnings attribute.
+*     XmlChan
+*        Reports conversion errors that result in what are usally
+*        insignificant  changes.
+
+*  Notes:
+*     - The returned KeyMap uses keys of the form "Warning_1",
+*     "Warning_2", etc.
+*     - A value of
+c     NULL will be returned if this function is invoked with the AST
+c     error status set,
+f     AST__NULL will be returned if this function is invoked with STATUS
+f     set to an error value,
+*     or if it should fail for any reason.
+*--
+*/
+
+/* Local Variables: */
+   AstKeyMap *result;
+   char key[ 20 ];
+   int i;
+
+/* Check the global status, and supplied keyword name. */
+   result = NULL;
+   if( !astOK ) return result;
+
+/* Check there are some warnings to return. */
+   if( this->nwarn && this->warnings ) {
+
+/* Create the KeyMap. */
+      result = astKeyMap( "", status );
+
+/* Loop round all warnings, adding them into the KeyMap. */
+      for( i = 0; i < this->nwarn; i++ ){
+         sprintf( key, "Warning_%d", i + 1 );
+         astMapPut0C( result, key, (this->warnings)[ i ], " " );
+      }
+   }
+
+/* Return the KeyMap. */
+   return result;
+}
+
+AstChannel *astInitChannel_( void *mem, size_t size, int init,
+                             AstChannelVtab *vtab, const char *name,
+                             const char *(* source)( void ),
+                             char *(* source_wrap)( const char *(*)( void ), int * ),
+                             void (* sink)( const char * ),
+                             void (* sink_wrap)( void (*)( const char * ),
+                                                 const char *, int * ), int *status ) {
+/*
+*+
+*  Name:
+*     astInitChannel
+
+*  Purpose:
+*     Initialise a Channel.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     AstChannel *astInitChannel( void *mem, size_t size, int init,
+*                                 AstChannelVtab *vtab, const char *name,
+*                                 const char *(* source)( void ),
+*                                 char *(* source_wrap)( const char *(*)( void ), int * ),
+*                                 void (* sink)( const char * ),
+*                                 void (* sink_wrap)( void (*)( const char * ),
+*                                                     const char *, int * ) )
+
+*  Class Membership:
+*     Channel initialiser.
+
+*  Description:
+*     This function is provided for use by class implementations to
+*     initialise a new Channel object. It allocates memory (if
+*     necessary) to accommodate the Channel plus any additional data
+*     associated with the derived class.  It then initialises a
+*     Channel structure at the start of this memory. If the "init"
+*     flag is set, it also initialises the contents of a virtual
+*     function table for a Channel at the start of the memory passed
+*     via the "vtab" parameter.
+
+*  Parameters:
+*     mem
+*        A pointer to the memory in which the Channel is to be
+*        initialised.  This must be of sufficient size to accommodate
+*        the Channel data (sizeof(Channel)) 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 Channel (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 Channel structure, so a valid value must be
+*        supplied even if not required for allocating memory.
+*     init
+*        A boolean flag indicating if the Channel'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 Channel.
+*     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).
+*     source
+*        Pointer to a "source" function which will be used to obtain
+*        lines of input text. Generally, this will be obtained by
+*        casting a pointer to a source function which is compatible
+*        with the "source_wrap" wrapper function (below). The pointer
+*        should later be cast back to its original type by the
+*        "source_wrap" function before the function is invoked.
+*
+*        If "source" is NULL, the Channel will read from standard
+*        input instead.
+*     source_wrap
+*        Pointer to a function which can be used to invoke the
+*        "source" function supplied (above). This wrapper function is
+*        necessary in order to hide variations in the nature of the
+*        source function, such as may arise when it is supplied by a
+*        foreign (non-C) language interface.
+*
+*        The single parameter of the "source_wrap" function is a
+*        pointer to the "source" function, and it should cast this
+*        function pointer (as necessary) and invoke the function with
+*        appropriate arguments to obtain the next line of input
+*        text. The "source_wrap" function should then return a pointer
+*        to a dynamically allocated, null terminated string containing
+*        the text that was read. The string will be freed (using
+*        astFree) when no longer required and the "source_wrap"
+*        function need not concern itself with this. A NULL pointer
+*        should be returned if there is no more input to read.
+*
+*        If "source_wrap" is NULL, the Channel will read from standard
+*        input instead.
+*     sink
+*        Pointer to a "sink" function which will be used to deliver
+*        lines of output text. Generally, this will be obtained by
+*        casting a pointer to a sink function which is compatible with
+*        the "sink_wrap" wrapper function (below). The pointer should
+*        later be cast back to its original type by the "sink_wrap"
+*        function before the function is invoked.
+*
+*        If "sink" is NULL, the Channel will write to standard output
+*        instead.
+*     sink_wrap
+*        Pointer to a function which can be used to invoke the "sink"
+*        function supplied (above). This wrapper function is necessary
+*        in order to hide variations in the nature of the sink
+*        function, such as may arise when it is supplied by a foreign
+*        (non-C) language interface.
+*
+*        The first parameter of the "sink_wrap" function is a pointer
+*        to the "sink" function, and the second parameter is a pointer
+*        to a const, null-terminated character string containing the
+*        text to be written.  The "sink_wrap" function should cast the
+*        "sink" function pointer (as necessary) and invoke the
+*        function with appropriate arguments to deliver the line of
+*        output text. The "sink_wrap" function then returns void.
+*
+*        If "sink_wrap" is NULL, the Channel will write to standard
+*        output instead.
+
+*  Returned Value:
+*     A pointer to the new Channel.
+
+*  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: */
+   AstChannel *new;              /* Pointer to new Channel */
+
+/* Check the global status. */
+   if ( !astOK ) return NULL;
+
+/* If necessary, initialise the virtual function table. */
+   if ( init ) astInitChannelVtab( vtab, name );
+
+/* Initialise an Object structure (the parent class) as the first
+   component within the Channel structure, allocating memory if
+   necessary. */
+   new = (AstChannel *) astInitObject( mem, size, 0,
+                                       (AstObjectVtab *) vtab, name );
+
+   if ( astOK ) {
+
+/* Initialise the Channel data. */
+/* ---------------------------- */
+/* Save the pointers to the source and sink functions and the wrapper
+   functions that invoke them. */
+      new->source = source;
+      new->source_wrap = source_wrap;
+      new->sink = sink;
+      new->sink_wrap = sink_wrap;
+
+/* Indicate no input or output files have been associated with the
+   Channel. */
+      new->fd_in = NULL;
+      new->fn_in = NULL;
+      new->fd_out = NULL;
+      new->fn_out = NULL;
+
+/* Set all attributes to their undefined values. */
+      new->comment = -INT_MAX;
+      new->full = -INT_MAX;
+      new->indent = -INT_MAX;
+      new->report_level = -INT_MAX;
+      new->skip = -INT_MAX;
+      new->strict = -INT_MAX;
+      new->data = NULL;
+      new->warnings = NULL;
+      new->nwarn = 0;
+
+/* If an error occurred, clean up by deleting the new object. */
+      if ( !astOK ) new = astDelete( new );
+   }
+
+/* Return a pointer to the new object. */
+   return new;
+}
+
+void astInitChannelVtab_(  AstChannelVtab *vtab, const char *name, int *status ) {
+/*
+*+
+*  Name:
+*     astInitChannelVtab
+
+*  Purpose:
+*     Initialise a virtual function table for a Channel.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astInitChannelVtab( AstChannelVtab *vtab, const char *name )
+
+*  Class Membership:
+*     Channel vtab initialiser.
+
+*  Description:
+*     This function initialises the component of a virtual function
+*     table which is used by the Channel class.
+
+*  Parameters:
+*     vtab
+*        Pointer to the virtual function table. The components used by
+*        all ancestral classes will be initialised if they have not already
+*        been initialised.
+*     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            /* Pointer to thread-specific global data */
+   AstObjectVtab *object;        /* Pointer to Object component of Vtab */
+
+/* Check the local error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to the thread specific global data structure. */
+   astGET_GLOBALS(NULL);
+
+/* Initialize the component of the virtual function table used by the
+   parent class. */
+   astInitObjectVtab( (AstObjectVtab *) vtab, name );
+
+/* Store a unique "magic" value in the virtual function table. This
+   will be used (by astIsAChannel) to determine if an object belongs
+   to this class.  We can conveniently use the address of the (static)
+   class_check variable to generate this unique value. */
+   vtab->id.check = &class_check;
+   vtab->id.parent = &(((AstObjectVtab *) vtab)->id);
+
+/* Initialise member function pointers. */
+/* ------------------------------------ */
+/* Store pointers to the member functions (implemented here) that
+   provide virtual methods for this class. */
+   vtab->AddWarning = AddWarning;
+   vtab->ClearComment = ClearComment;
+   vtab->ClearFull = ClearFull;
+   vtab->ClearSkip = ClearSkip;
+   vtab->ClearStrict = ClearStrict;
+   vtab->GetComment = GetComment;
+   vtab->GetFull = GetFull;
+   vtab->GetNextData = GetNextData;
+   vtab->GetNextText = GetNextText;
+   vtab->GetSkip = GetSkip;
+   vtab->GetStrict = GetStrict;
+   vtab->Warnings = Warnings;
+   vtab->PutNextText = PutNextText;
+   vtab->Read = Read;
+   vtab->ReadClassData = ReadClassData;
+   vtab->ReadDouble = ReadDouble;
+   vtab->ReadInt = ReadInt;
+   vtab->ReadObject = ReadObject;
+   vtab->ReadString = ReadString;
+   vtab->SetComment = SetComment;
+   vtab->SetFull = SetFull;
+   vtab->SetSkip = SetSkip;
+   vtab->SetStrict = SetStrict;
+   vtab->TestComment = TestComment;
+   vtab->TestFull = TestFull;
+   vtab->TestSkip = TestSkip;
+   vtab->TestStrict = TestStrict;
+   vtab->Write = Write;
+   vtab->WriteBegin = WriteBegin;
+   vtab->WriteDouble = WriteDouble;
+   vtab->WriteEnd = WriteEnd;
+   vtab->WriteInt = WriteInt;
+   vtab->WriteIsA = WriteIsA;
+   vtab->WriteObject = WriteObject;
+   vtab->WriteString = WriteString;
+   vtab->PutChannelData = PutChannelData;
+
+   vtab->ClearReportLevel = ClearReportLevel;
+   vtab->GetReportLevel = GetReportLevel;
+   vtab->SetReportLevel = SetReportLevel;
+   vtab->TestReportLevel = TestReportLevel;
+
+   vtab->ClearIndent = ClearIndent;
+   vtab->GetIndent = GetIndent;
+   vtab->SetIndent = SetIndent;
+   vtab->TestIndent = TestIndent;
+
+   vtab->ClearSourceFile = ClearSourceFile;
+   vtab->GetSourceFile = GetSourceFile;
+   vtab->SetSourceFile = SetSourceFile;
+   vtab->TestSourceFile = TestSourceFile;
+
+   vtab->ClearSinkFile = ClearSinkFile;
+   vtab->GetSinkFile = GetSinkFile;
+   vtab->SetSinkFile = SetSinkFile;
+   vtab->TestSinkFile = TestSinkFile;
+
+/* Save the inherited pointers to methods that will be extended, and
+   replace them with pointers to the new member functions. */
+   object = (AstObjectVtab *) vtab;
+
+   parent_clearattrib = object->ClearAttrib;
+   object->ClearAttrib = ClearAttrib;
+   parent_getattrib = object->GetAttrib;
+   object->GetAttrib = GetAttrib;
+   parent_setattrib = object->SetAttrib;
+   object->SetAttrib = SetAttrib;
+   parent_testattrib = object->TestAttrib;
+   object->TestAttrib = TestAttrib;
+
+/* Declare the destructor and copy constructor. */
+   astSetDelete( (AstObjectVtab *) vtab, Delete );
+   astSetCopy( (AstObjectVtab *) vtab, Copy );
+
+/* Declare the Dump function for this class. There is no destructor or
+   copy constructor. */
+   astSetDump( vtab, Dump, "Channel", "Basic I/O Channel" );
+
+/* If we have just initialised the vtab for the current class, indicate
+   that the vtab is now initialised, and store a pointer to the class
+   identifier in the base "object" level of the vtab. */
+   if( vtab == &class_vtab ) {
+      class_init = 1;
+      astSetVtabClassIdentifier( vtab, &(vtab->id) );
+   }
+}
+
+static char *InputTextItem( AstChannel *this, int *status ) {
+/*
+*  Name:
+*     InputTextItem
+
+*  Purpose:
+*     Read the next item from a data source as text.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     char *InputTextItem( AstChannel *this )
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function reads the next input data item as text from the
+*     data source associated with a Channel. It is similar to the
+*     astGetNextText method (which it invokes), except that it strips
+*     off any comments along with leading and trailing white
+*     space. Input lines which are empty or do not contain significant
+*     characters (e.g. all comment) are skipped, so that only
+*     significant lines are returned.
+*
+*     Each line is returned as a pointer to a null-terminated string
+*     held in dynamic memory, and it is the caller's responsibility to
+*     free this memory (using astFree) when it is no longer
+*     required. A NULL pointer is returned if there are no more input
+*     lines to be read.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+
+*  Returned Value:
+*     Pointer to a null-terminated string containing the input line
+*     (held in dynamically allocated memory, which must be freed by
+*     the caller when no longer required). A NULL pointer is returned
+*     if there are no more input lines to be read.
+
+*  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: */
+   char *line;                   /* Pointer to line data to be returned */
+   int i;                        /* Loop counter for line characters */
+   int j;                        /* Counter for characters */
+   int len;                      /* Length of result line */
+   int nonspace;                 /* Non-space character encountered? */
+   int quoted;                   /* Character is inside quotes? */
+
+/* Initialise. */
+   line = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return line;
+
+/* Loop to read input lines until one is found which contains useful
+   characters or end of file is reached (or a read error occurs). */
+   while ( !line && ( line = astGetNextText( this ) ) && astOK ) {
+
+/* Loop to remove comments and leading and trailing white space. */
+      len = 0;
+      nonspace = 0;
+      quoted = 0;
+      for ( i = j = 0; line[ i ]; i++ ) {
+
+/* Note quote characters and ignore all text after the first unquoted
+   comment character. */
+         if ( line[ i ] == '"' ) quoted = !quoted;
+         if ( ( line[ i ] == '#' ) && !quoted ) break;
+
+/* Note the first non-space character and ignore everything before
+   it. */
+         if ( ( nonspace = nonspace || !isspace( line[ i ] ) ) ) {
+
+/* Move each character to its new position in the string. */
+            line[ j++ ] = line[ i ];
+
+/* Note the final length of the string (ignoring trailing spaces). */
+            if ( !isspace( line[ i ] ) ) len = j;
+         }
+      }
+
+/* If the string is not empty, terminate it. */
+     if ( len ) {
+        line[ len ] = '\0';
+
+/* Otherwise, free the memory used for the string so that another
+   input line will be read. */
+      } else {
+         line = astFree( line );
+      }
+   }
+
+/* Return the result pointer. */
+   return line;
+
+/* Undefine macros local to this function. */
+#undef MIN_CHARS
+}
+
+static AstChannelValue *LookupValue( const char *name, int *status ) {
+/*
+*  Name:
+*     LookupValue
+
+*  Purpose:
+*     Look up a Value structure by name.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     AstChannelValue *LookupValue( const char *name )
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function searches the current values list (i.e. at the
+*     current nesting level) to identify a Value structure with a
+*     specified name. If one is found, it is removed from the list and
+*     a pointer to it is returned. If no suitable Value can be found,
+*     a NULL pointer is returned instead.
+
+*  Parameters:
+*     name
+*        Pointer to a constant null-terminated character string
+*        containing the name of the required Value. This must be in
+*        lower case with no surrounding white space. Note that names
+*        longer than NAME_MAX characters will not match any Value.
+
+*  Returned value:
+*     Pointer to the required Value structure, or NULL if no suitable
+*     Value exists.
+
+*  Notes:
+*     - The returned pointer refers to a dynamically allocated
+*     structure and it is the callers responsibility to free this when
+*     no longer required. The FreeValue function must be used for this
+*     purpose.
+*     - 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            /* Declare the thread specific global data */
+   AstChannelValue **head;       /* Address of head of list pointer */
+   AstChannelValue *result;      /* Pointer value to return */
+   AstChannelValue *value;       /* Pointer to list element */
+
+/* Initialise. */
+   result = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(NULL);
+
+/* Check that the "values_ok" flag is set. If not, the Values in the
+   values list belong to a different class to that of the current
+   class loader, so we cannot return any Value. */
+   if ( values_ok[ nest ] ) {
+
+/* Obtain the address of the current "head of list" pointer for the
+   values list (at the current nesting level). */
+      head = values_list + nest;
+
+/* Obtain the head of list pointer itself and check the list is not
+   empty. */
+      if ( ( value = *head ) ) {
+
+/* Loop to inspect each list element. */
+         while ( 1 ) {
+
+/* If a name match is found, remove the element from the list, return
+   a pointer to it and quit searching. */
+            if ( !strcmp( name, value->name ) ) {
+               RemoveValue( value, head, status );
+               result = value;
+               break;
+            }
+
+/* Follow the list until we return to the head. */
+            value = value->flink;
+            if ( value == *head ) break;
+         }
+      }
+   }
+
+/* Return the result. */
+   return result;
+}
+
+static void OutputTextItem( AstChannel *this, const char *line, int *status ) {
+/*
+*  Name:
+*     OutputTextItem
+
+*  Purpose:
+*     Output a data item formatted as text.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void OutputTextItem( AstChannel *this, const char *line, int *status )
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function outputs a data item formatted as a text string to
+*     a data sink associated with a Channel. It keeps track of the
+*     number of items written.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     line
+*        Pointer to a constant null-terminated string containing the
+*        data item to be output (no newline character should be
+*        appended).
+*     status
+*        Pointer to the inherited status variable.
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* Write out the line of text using the astPutNextText method (which
+   may be over-ridden). */
+   astPutNextText( this, line );
+
+/* If successful, increment the count of items written. */
+   if ( astOK ) items_written++;
+}
+
+static void PutChannelData( AstChannel *this, void *data, int *status ) {
+/*
+c++
+*  Name:
+*     astPutChannelData
+
+*  Purpose:
+*     Store arbitrary data to be passed to a source or sink function.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astPutChannelData( AstChannel *this, void *data )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function stores a supplied arbitrary pointer in the Channel.
+*     When a source or sink function is invoked by the Channel, the
+*     invoked function can use the astChannelData macro to retrieve the
+*     pointer. This provides a thread-safe alternative to passing file
+*     descriptors, etc, via global static variables.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     data
+*        A pointer to be made available to the source and sink functions
+*        via the astChannelData macro. May be NULL.
+
+*  Applicability:
+*     Channel
+*        All Channels have this function.
+
+*  Notes:
+*     - This routine is not available in the Fortran 77 interface to
+*     the AST library.
+c--
+*/
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Store the pointer. */
+   this->data = data;
+}
+
+static void PutNextText( AstChannel *this, const char *line, int *status ) {
+/*
+*+
+*  Name:
+*     astPutNextText
+
+*  Purpose:
+*     Write a line of output text to a data sink.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astPutNextText( AstChannel *this, const char *line )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function writes an output line of text to a data sink
+*     associated with a Channel.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     line
+*        Pointer to a constant null-terminated string containing the
+*        line of output text to be written (no newline character
+*        should be appended).
+
+*  Notes:
+*     - This method is provided primarily so that derived classes may
+*     over-ride it in order to write to alternative (textual) data
+*     sinks.
+*-
+*/
+
+/* Local Constants: */
+#define ERRBUF_LEN 80
+
+/* Local Variables: */
+   char *errstat;                /* Pointer for system error message */
+   char errbuf[ ERRBUF_LEN ];    /* Buffer for system error message */
+   const char *sink_file;        /* Path to output sink file */
+   const char *source_file;      /* Path to output source file */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* If the SinkFile attribute of the Channel specifies an output file,
+   but no output file has yet been opened, open it now. Report an error
+   if it is the same as the source file. */
+   if( astTestSinkFile( this ) && !this->fd_out ) {
+      sink_file = astGetSinkFile( this );
+
+      if( this->fd_out ) {
+         source_file = astGetSourceFile( this );
+         if( astOK && !strcmp( sink_file, source_file ) ) {
+            astError( AST__WRERR, "astWrite(%s): Failed to open output "
+                      "SinkFile '%s' - the file is currently being used "
+                      "as the input SourceFile.", status, astGetClass( this ),
+                      sink_file );
+         }
+      }
+
+      if( astOK ) {
+         this->fd_out = fopen( sink_file, "w" );
+         if( !this->fd_out ) {
+            if ( errno ) {
+#if HAVE_STRERROR_R
+               strerror_r( errno, errbuf, ERRBUF_LEN );
+               errstat = errbuf;
+#else
+               errstat = strerror( errno );
+#endif
+               astError( AST__WRERR, "astWrite(%s): Failed to open output "
+                         "SinkFile '%s' - %s.", status, astGetClass( this ),
+                         sink_file, errstat );
+            } else {
+               astError( AST__WRERR, "astWrite(%s): Failed to open output "
+                         "SinkFile '%s'.", status, astGetClass( this ),
+                         sink_file );
+            }
+         }
+      }
+   }
+
+/* Check no error occurred above. */
+   if( astOK ) {
+
+/* If an active output file descriptor is stored in the channel, write
+   the text to it, with a newline appended. */
+      if( this->fd_out ) {
+         (void) fprintf( this->fd_out, "%s\n", line );
+
+/* Otherwise, if a sink function (and its wrapper function) is defined for
+   the Channel, use the wrapper function to invoke the sink function to
+   output the text line. Since we are about to call an externally supplied
+   function which may not be thread-safe, lock a mutex first. Also store
+   the channel data pointer in a global variable so that it can be accessed
+   in the source function using macro astChannelData. */
+      } else if ( this->sink && this->sink_wrap ) {
+         astStoreChannelData( this );
+         LOCK_MUTEX2;
+         ( *this->sink_wrap )( *this->sink, line, status );
+         UNLOCK_MUTEX2;
+
+/* Otherwise, simply write the text to standard output with a newline
+   appended. */
+      } else {
+         (void) printf( "%s\n", line );
+      }
+   }
+}
+
+static AstObject *Read( AstChannel *this, int *status ) {
+/*
+*++
+*  Name:
+c     astRead
+f     AST_READ
+
+*  Purpose:
+*     Read an Object from a Channel.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "channel.h"
+c     AstObject *astRead( AstChannel *this )
+f     RESULT = AST_READ( THIS, STATUS )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function reads the next Object from a Channel and returns a
+*     pointer to the new Object.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the Channel.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astRead()
+f     AST_READ = INTEGER
+*        A pointer to the new Object. The class to which this will
+*        belong is determined by the input data, so is not known in
+*        advance.
+
+*  Applicability:
+*     FitsChan
+c        All successful use of astRead on a FitsChan is destructive, so that
+f        All successful use of AST_READ on a FitsChan is destructive, so that
+*        FITS header cards are consumed in the process of reading an Object,
+*        and are removed from the FitsChan (this deletion can be prevented
+*        for specific cards by calling the FitsChan
+c        astRetainFits function).
+f        AST_RETAINFITS routine).
+*        An unsuccessful call of
+c        astRead
+f        AST_READ
+*        (for instance, caused by the FitsChan not containing the necessary
+*        FITS headers cards needed to create an Object) results in the
+*        contents of the FitsChan being left unchanged.
+*     StcsChan
+*        The AST Object returned by a successful use of
+c        astRead
+f        AST_READ
+*        on an StcsChan, will be either a Region or a KeyMap, depending
+*        on the values of the StcsArea, StcsCoords and StcsProps
+*        attributes. See the documentation for these attributes for further
+*        information.
+
+*  Notes:
+*     - A null Object pointer (AST__NULL) will be returned, without
+*     error, if the Channel contains no further Objects to be read.
+*     - A null Object pointer will also be returned if this function
+c     is invoked with the AST error status set, or if it should fail
+f     is invoked with STATUS set to an error value, or if it should fail
+*     for any reason.
+*--
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+   AstLoaderType *loader;        /* Pointer to loader for Object */
+   AstObject *new;               /* Pointer to new Object */
+   char *class;                  /* Pointer to Object class name string */
+   char *name;                   /* Pointer to data item name */
+   int skip;                     /* Skip non-AST data? */
+   int top;                      /* Reading top-level Object definition? */
+
+/* Initialise. */
+   new = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return new;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* Determine if we are reading a top-level (i.e. user-level) Object
+   definition, as opposed to the definition of an Object contained
+   within another Object. This is indicated by the current nesting
+   level. */
+   top = ( nest == -1 );
+
+/* If reading a top-level object, determine if data lying in between
+   Object definitions in the input data stream are to be skipped. */
+   skip = ( top && astGetSkip( this ) );
+
+/* Read the next input data item. If we are reading a top-level Object
+   definition, skip any unrelated data beforehand. Otherwise read the
+   data strictly as it comes (there should be no unrelated data
+   embedded within Object definitions themselves). */
+   astGetNextData( this, skip, &name, &class );
+
+/* If no suitable data item was found (and no error occurred), we have
+   reached the end of data. For a top-level Object a NULL Object
+   pointer is simply returned, but for a nested Object this indicates
+   that part of the Object definition is missing, so report an
+   error. */
+   if ( astOK ) {
+      if ( !name ) {
+         if ( !top ) {
+            astError( AST__EOCHN,
+                      "astRead(%s): End of input encountered while trying to "
+                      "read an AST Object.", status, astGetClass( this ) );
+         }
+
+/* If a data item was found, check it is a "Begin" item. If not, there
+   is a data item missing, so report an error and free all memory. */
+      } else if ( strcmp( name, "begin" ) ) {
+         astError( AST__BADIN,
+                   "astRead(%s): Missing \"Begin\" when expecting an Object.", status,
+                   astGetClass( this ) );
+         name = astFree( name );
+         if ( class ) class = astFree( class );
+
+/* If the required "Begin" item was found, free the memory used for the
+   name string. */
+      } else {
+         name = astFree( name );
+
+/* Use the associated class name to locate the loader for that
+   class. This function will then be used to build the Object. */
+         loader = astGetLoader( class, status );
+
+/* Extend all necessary stack arrays to accommodate entries for the
+   next nesting level (this allocates space if none has yet been
+   allocated). */
+         end_of_object = astGrow( end_of_object, nest + 2, sizeof( int ) );
+         object_class = astGrow( object_class, nest + 2, sizeof( char * ) );
+         values_class = astGrow( values_class, nest + 2, sizeof( char * ) );
+         values_list = astGrow( values_list, nest + 2, sizeof( AstChannelValue * ) );
+         values_ok = astGrow( values_ok, nest + 2, sizeof( int ) );
+
+/* If an error occurred, free the memory used by the class string,
+   which will not now be used. */
+         if ( !astOK ) {
+            class = astFree( class );
+
+/* Otherwise, increment the nesting level and initialise the new stack
+   elements for this new level. This includes clearing the
+   "end_of_object" flag so that ReadClassData can read more data, and
+   storing the class name of the object we are about to read. */
+         } else {
+            nest++;
+            end_of_object[ nest ] = 0;
+            object_class[ nest ] = class;
+            values_class[ nest ] = NULL;
+            values_list[ nest ] = NULL;
+            values_ok[ nest ] = 0;
+
+/* Invoke the loader, which reads the Object definition from the input
+   data stream and builds the Object. Supply NULL/zero values to the
+   loader so that it will substitute values appropriate to its own
+   class. */
+            new = (*loader)( NULL, (size_t) 0, NULL, NULL, this, status );
+
+/* Clear the values list for the current nesting level. If the list
+   has not been read or any Values remain in it, an error will
+   result. */
+            ClearValues( this, status );
+
+/* If no error has yet occurred, check that the "end_of_object" flag
+   has been set. If not, the input data were not correctly terminated,
+   so report an error. */
+            if ( astOK && !end_of_object[ nest ] ) {
+               astError( AST__BADIN,
+                         "astRead(%s): Unexpected end of input (missing end "
+                         "of %s).", status,
+                         astGetClass( this ), object_class[ nest ] );
+            }
+
+/* If an error occurred, report contextual information. Only do this
+   for top-level Objects to avoid multple messages. */
+            if ( !astOK && top ) {
+               astError( astStatus, "Error while reading a %s from a %s.", status,
+                         class, astGetClass( this ) );
+            }
+
+/* Clear the Object's class string, freeing the associated memory
+   (note this is the memory allocated for the "class" string
+   earlier). */
+            object_class[ nest ] = astFree( object_class[ nest ] );
+
+/* Restore the previous nesting level. */
+            nest--;
+         }
+
+/* Once the top-level Object has been built, free the memory used by
+   the stack arrays. */
+         if ( top ) {
+            end_of_object = astFree( end_of_object );
+            object_class = astFree( object_class );
+            values_class = astFree( values_class );
+            values_list = astFree( values_list );
+            values_ok = astFree( values_ok );
+         }
+      }
+   }
+
+/* If an error occurred, clean up by deleting the new Object and
+   return a NULL pointer. */
+   if ( !astOK ) new = astDelete( new );
+
+/* Return the pointer to the new Object. */
+   return new;
+}
+
+static void ReadClassData( AstChannel *this, const char *class, int *status ) {
+/*
+*+
+*  Name:
+*     astReadClassData
+
+*  Purpose:
+*     Read values from a data source for a class loader.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astReadClassData( AstChannel *this, const char *class )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function reads the data for a class from the data source
+*     associated with a Channel, so as to provide values for
+*     initialising the instance variables of that class as part of
+*     building a complete Object. This function should be invoked by
+*     the loader for each class immediately before it attempts to read
+*     these values.
+*
+*     The values read are placed into the current values list by this
+*     function. They may then be read from this list by the class
+*     loader making calls to astReadDouble, astReadInt, astReadObject
+*     and astReadString. The order in which values are read by the
+*     loader is unimportant (although using the same order for reading
+*     as for writing will usually be more efficient) and values are
+*     removed from the list as they are read.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     class
+*        A pointer to a constant null-terminated string containing the
+*        name of the class whose loader is requesting the data (note
+*        this is not usually the same as the class name of the Object
+*        being built). This value allows the class structure of the
+*        input data to be validated.
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+   AstObject *object;            /* Pointer to new Object */
+   AstChannelValue *value;       /* Pointer to Value structure */
+   char *name;                   /* Pointer to data item name string */
+   char *val;                    /* Pointer to data item value string */
+   int done;                     /* All class data read? */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* If the "values_ok" flag is set, this indicates that the values list
+   (at the current nesting level) has been filled by a previous
+   invocation of this function and has then been read by the
+   appropriate class loader. In this case, clear any entries which may
+   remain in the current values list. If any such entries are found,
+   they represent input data that were not read, so an error will
+   result. */
+   if ( values_ok[ nest ] ) ClearValues( this, status );
+
+/* If "values_class" is non-NULL, this indicates that the values list
+   (at the current nesting level) has been filled by a previous
+   invocation of this function, but that the values belong to a class
+   whose loader has not yet tried to read them. In this case, we must
+   continue to keep the values until they are needed, so we do not
+   read any more input data this time. */
+   if ( values_class[ nest ] ) {
+
+/* If the class to which the previously saved values belong matches
+   the class we now want values for, set the "values_ok" flag. This
+   then allows the values to be accessed (by LookupValue). */
+      values_ok[ nest ] = !strcmp( values_class[ nest ], class );
+
+/* If the current values list is empty, we must read in values for the
+   next class that appears in the input data. However, first check
+   that the "end_of_object" flag has not been set. If it has, we have
+   already reached the end of this Object's data, so there is some
+   kind of problem with the order in which class loaders have been
+   invoked. This will probably never happen, but report an error if
+   necessary. */
+   } else if ( end_of_object[ nest ] ) {
+      astError( AST__LDERR,
+                "astRead(%s): Invalid attempt to read further %s data "
+                "following an end of %s.", status,
+                astGetClass( this ), class, object_class[ nest ] );
+      astError( AST__LDERR,
+                "Perhaps the wrong class loader has been invoked?" , status);
+
+/* If we need new values, loop to read input data items until the end
+   of the data for a class is reached. */
+   } else {
+      done = 0;
+      while ( astOK && !done ) {
+
+/* Read the next input data item. */
+         astGetNextData( this, 0, &name, &val );
+         if ( astOK ) {
+
+/* Unexpected end of input. */
+/* ------------------------ */
+/* If no "name" value is returned, we have reached the end of the
+   input data stream without finding the required end of class
+   terminator, so report an error. */
+            if ( !name ) {
+               astError( AST__EOCHN,
+                         "astRead(%s): Unexpected end of input (missing end "
+                         "of %s).", status,
+                         astGetClass( this ), object_class[ nest ] );
+
+/* "IsA" item. */
+/* ----------- */
+/* Otherwise, if an "IsA" item was read, it indicates the end of the
+   data for a class. Store the pointer to the name of this class in
+   "values_class" and note whether this is the class whose data we
+   wanted in "values_ok". If the data we have read do not belong to
+   the class we wanted, they will simply be kept until the right class
+   comes looking for them. */
+            } else if ( !strcmp( name, "isa" ) ) {
+               values_class[ nest ] = val;
+               values_ok[ nest ] = !strcmp( val, class );
+
+/* Free the memory holding the name string. */
+               name = astFree( name );
+
+/* Note we have finished reading class data. */
+               done = 1;
+
+/* "End" item. */
+/* ----------- */
+/* If an "End" item was read, it indicates the end of the data both
+   for a class and for the current Object definition as a whole. Set
+   the "end_of_object" flag (for the current nesting level) which
+   prevents any further data being read for this Object. This flag is
+   also used (by Read) to check that an "End" item was actually
+   read. */
+            } else if ( !strcmp( name, "end" ) ) {
+               end_of_object[ nest ] = 1;
+
+/* Check that the class name in the "End" item matches that of the
+   Object being built. If so, store the pointer to the name of this
+   class in "values_class" and note whether this is the class whose
+   data we wanted in "values_ok". If the data we have read do not
+   belong to the class we wanted, they will simply be kept until the
+   right class comes looking for them. */
+               if ( !strcmp( val, object_class[ nest ] ) ) {
+                  values_class[ nest ] = val;
+                  values_ok[ nest ] = !strcmp( class, val );
+
+/* If the "End" item contains the wrong class name (i.e. not matching
+   the corresponding "Begin" item), then report an error. */
+               } else {
+                  astError( AST__BADIN,
+                            "astRead(%s): Bad class structure in input data.", status,
+                            astGetClass( this ) );
+                  astError( AST__BADIN,
+                            "End of %s read when expecting end of %s.", status,
+                            val, object_class[ nest ] );
+
+/* Free the memory used by the class string, which will not now be
+   used. */
+                  val = astFree( val );
+               }
+
+/* Free the memory holding the name string. */
+               name = astFree( name );
+
+/* Note we have finished reading class data. */
+               done = 1;
+
+/* String value. */
+/* ------------- */
+/* If any other name is obtained and "val" is not NULL, we have read a
+   non-Object value, encoded as a string. Allocate memory for a Value
+   structure to describe it. */
+            } else if ( val ) {
+               value = astMalloc( sizeof( AstChannelValue ) );
+               if ( astOK ) {
+
+/* Store pointers to the name and value string in the Value structure
+   and note this is not an Object value. */
+                  value->name = name;
+                  value->ptr.string = val;
+                  value->is_object = 0;
+
+/* Append the Value structure to the values list for the current
+   nesting level. */
+                  AppendValue( value, values_list + nest, status );
+
+/* If an error occurred, free the memory holding the "name" and "val"
+   strings. */
+               } else {
+                  name = astFree( name );
+                  val = astFree( val );
+               }
+
+/* Object value. */
+/* ------------- */
+/* If "val" is NULL, we have read an Object item, and the Object
+   definition should follow. Allocate memory for a Value structure to
+   describe it. */
+            } else {
+               value = astMalloc( sizeof( AstChannelValue ) );
+
+/* Invoke astRead to read the Object definition from subsequent data
+   items and to build the Object, returning a pointer to it. This will
+   result in recursive calls to the current function, but as these
+   will use higher nesting levels they will not interfere with the
+   current invocation. */
+               astreadclassdata_msg = 0;
+               object = astRead( this );
+               if ( astOK ) {
+
+/* Store pointers to the name and Object in the Value structure and
+   note this is an Object value. */
+                  value->name = name;
+                  value->ptr.object = object;
+                  value->is_object = 1;
+
+/* Append the Value structure to the values list for the current
+   nesting level. */
+                  AppendValue( value, values_list + nest, status );
+
+/* If an error occurred, report a contextual error maessage and set
+   the "astreadclassdata_msg" flag (this prevents multiple messages if this function is
+   invoked recursively to deal with nested Objects). */
+               } else {
+                  if ( !astreadclassdata_msg ) {
+                     astError( astStatus,
+                               "Failed to read the \"%s\" Object value.", status,
+                               name );
+                     astreadclassdata_msg = 1;
+                  }
+
+/* Free the memory holding the "name" string and any Value structure
+   that was allocated. */
+                  name = astFree( name );
+                  value = astFree( value );
+               }
+            }
+         }
+      }
+   }
+}
+
+static double ReadDouble( AstChannel *this, const char *name, double def, int *status ) {
+/*
+*+
+*  Name:
+*     astReadDouble
+
+*  Purpose:
+*     Read a double value as part of loading a class.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     double astReadDouble( AstChannel *this, const char *name, double def )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function searches the current values list of a Channel to
+*     identify a double value with a specified name. If such a value
+*     is found, it is returned, otherwise a default value is returned
+*     instead.
+*
+*     This function should only be invoked from within the loader
+*     function associated with a class, in order to return a double
+*     value to be assigned to an instance variable. It must be
+*     preceded by a call to the astReadClassData function, which loads
+*     the values associated with the class into the current values
+*     list from the input data source.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     name
+*        Pointer to a constant null-terminated character string
+*        containing the name of the required value. This must be in
+*        lower case with no surrounding white space. Note that names
+*        longer than 6 characters will not match any value.
+*     def
+*        If no suitable value can be found (e.g. it is absent from the
+*        data stream being read), then this value will be returned
+*        instead.
+
+*  Returned Value:
+*     The required value, or the default if the value was not found.
+
+*  Notes:
+*     - A value of 0.0 will be returned if this function is invoked
+*     with the global error status set, or if it should fail for any
+*     reason.
+*-
+*/
+
+/* Local Variables: */
+   AstChannelValue *value;       /* Pointer to required Value structure */
+   double result;                /* Value to be returned */
+   int nc;                       /* Number of characters read by astSscanf */
+
+/* Initialise. */
+   result = 0.0;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Search for a Value structure with the required name in the current
+   values list.*/
+   value = LookupValue( name, status );
+   if ( astOK ) {
+
+/* If a Value was found, check that it describes a string (as opposed
+   to an Object). */
+      if ( value ) {
+         if ( !value->is_object ) {
+
+/* If so, then attempt to decode the string to give a double value,
+   checking that the entire string is read (and checking for the magic string
+   used to represent bad values). If this fails, then the wrong name has
+   probably been given, or the input data are corrupt, so report an error. */
+            nc = 0;
+            if ( ( 0 == astSscanf( value->ptr.string, " " BAD_STRING " %n",
+                                                      &nc ) )
+                    && ( nc >= (int) strlen( value->ptr.string ) ) ) {
+               result = AST__BAD;
+
+            } else if ( !( ( 1 == astSscanf( value->ptr.string, " %lf %n",
+                                                      &result, &nc ) )
+                    && ( nc >= (int) strlen( value->ptr.string ) ) ) ) {
+               astError( AST__BADIN,
+                         "astRead(%s): The value \"%s = %s\" cannot "
+                         "be read as a double precision floating point "
+                         "number.", status, astGetClass( this ),
+                         value->name, value->ptr.string );
+
+            } else if( !astISFINITE( result ) ) {
+               astError( AST__BADIN,
+                         "astRead(%s): Illegal double precision floating "
+                         "point value \"%s\" read for \"%s\".", status,
+                         astGetClass( this ), value->ptr.string, value->name );
+
+            }
+
+/* Report a similar error if the Value does not describe a string. */
+         } else {
+            astError( AST__BADIN,
+                      "astRead(%s): The Object \"%s = <%s>\" cannot "
+                      "be read as a double precision floating point number.", status,
+                      astGetClass( this ),
+                      value->name, astGetClass( value->ptr.object ) );
+         }
+
+/* Free the Value structure and the resources it points at. */
+         value = FreeValue( value, status );
+
+/* If no suitable Value structure was found, then use the default
+   value instead. */
+      } else {
+         result = def;
+      }
+   }
+
+/* Return the result. */
+   return result;
+}
+
+static int ReadInt( AstChannel *this, const char *name, int def, int *status ) {
+/*
+*+
+*  Name:
+*     astReadInt
+
+*  Purpose:
+*     Read an int value as part of loading a class.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     int astReadInt( AstChannel *this, const char *name, int def )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function searches the current values list of a Channel to
+*     identify an int value with a specified name. If such a value is
+*     found, it is returned, otherwise a default value is returned
+*     instead.
+*
+*     This function should only be invoked from within the loader
+*     function associated with a class, in order to return an int
+*     value to be assigned to an instance variable. It must be
+*     preceded by a call to the astReadClassData function, which loads
+*     the values associated with the class into the current values
+*     list from the input data source.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     name
+*        Pointer to a constant null-terminated character string
+*        containing the name of the required value. This must be in
+*        lower case with no surrounding white space. Note that names
+*        longer than 6 characters will not match any value.
+*     def
+*        If no suitable value can be found (e.g. it is absent from the
+*        data stream being read), then this value will be returned
+*        instead.
+
+*  Returned Value:
+*     The required value, or the default if the value was not found.
+
+*  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: */
+   AstChannelValue *value;       /* Pointer to required Value structure */
+   int nc;                       /* Number of characters read by astSscanf */
+   int result;                   /* Value to be returned */
+
+/* Initialise. */
+   result = 0;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Search for a Value structure with the required name in the current
+   values list.*/
+   value = LookupValue( name, status );
+   if ( astOK ) {
+
+/* If a Value was found, check that it describes a string (as opposed
+   to an Object). */
+      if ( value ) {
+         if ( !value->is_object ) {
+
+/* If so, then attempt to decode the string to give an int value,
+   checking that the entire string is read. If this fails, then the
+   wrong name has probably been given, or the input data are corrupt,
+   so report an error. */
+            nc = 0;
+            if ( !( ( 1 == astSscanf( value->ptr.string, " %d %n",
+                                                      &result, &nc ) )
+                    && ( nc >= (int) strlen( value->ptr.string ) ) ) ) {
+               astError( AST__BADIN,
+                         "astRead(%s): The value \"%s = %s\" cannot "
+                         "be read as an integer.", status, astGetClass( this ),
+                         value->name, value->ptr.string );
+            }
+
+/* Report a similar error if the Value does not describe a string. */
+         } else {
+            astError( AST__BADIN,
+                      "astRead(%s): The Object \"%s = <%s>\" cannot "
+                      "be read as an integer.", status, astGetClass( this ),
+                      value->name, astGetClass( value->ptr.object ) );
+         }
+
+/* Free the Value structure and the resources it points at. */
+         value = FreeValue( value, status );
+
+/* If no suitable Value structure was found, then use the default
+   value instead. */
+      } else {
+         result = def;
+      }
+   }
+
+/* Return the result. */
+   return result;
+}
+
+static AstObject *ReadObject( AstChannel *this, const char *name,
+                              AstObject *def, int *status ) {
+/*
+*+
+*  Name:
+*     astReadObject
+
+*  Purpose:
+*     Read a (sub)Object as part of loading a class.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     AstObject *astReadObject( AstChannel *this, const char *name,
+*                               AstObject *def )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function searches the current values list of a Channel to
+*     identify an Object with a specified name. If such an Object is
+*     found, a pointer to it is returned, otherwise a default pointer
+*     is returned instead.
+*
+*     This function should only be invoked from within the loader
+*     function associated with a class, in order to return an Object
+*     pointer value to be assigned to an instance variable. It must be
+*     preceded by a call to the astReadClassData function, which loads
+*     the values associated with the class into the current values
+*     list from the input data source.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     name
+*        Pointer to a constant null-terminated character string
+*        containing the name of the required Object. This must be in
+*        lower case with no surrounding white space. Note that names
+*        longer than 6 characters will not match any Object.
+*     def
+*        If no suitable Object can be found (e.g. the Object is absent
+*        from the data stream being read), then a clone of this
+*        default Object pointer will be returned instead (or NULL if
+*        this default pointer is NULL).
+
+*  Returned Value:
+*     A pointer to the Object, or a clone of the default pointer if
+*     the Object was not found.
+
+*  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 *result;            /* Pointer value to return */
+   AstChannelValue *value;       /* Pointer to required Value structure */
+
+/* Initialise. */
+   result = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Search for a Value structure with the required name in the current
+   values list.*/
+   value = LookupValue( name, status );
+   if ( astOK ) {
+
+/* If a Value was found, check that it describes an Object (as opposed to
+   a string). */
+      if ( value ) {
+         if ( value->is_object ) {
+
+/* If so, then extract the Object pointer, replacing it with NULL. */
+            result = value->ptr.object;
+            value->ptr.object = NULL;
+
+/* If the Value does not describe an Object, then the wrong name has
+   probably been given, or the input data are corrupt, so report an
+   error. */
+         } else {
+            astError( AST__BADIN,
+                      "astRead(%s): The value \"%s = %s\" cannot be "
+                      "read as an Object.", status, astGetClass( this ),
+                      value->name, value->ptr.string );
+         }
+
+/* Free the Value structure and the resources it points at. */
+         value = FreeValue( value, status );
+
+/* If no suitable Value structure was found, clone the default
+   pointer, if given. */
+      } else if ( def ) {
+         result = astClone( def );
+      }
+   }
+
+/* Return the result. */
+   return result;
+}
+
+static char *ReadString( AstChannel *this, const char *name,
+                         const char *def, int *status ) {
+/*
+*+
+*  Name:
+*     astReadString
+
+*  Purpose:
+*     Read a string value as part of loading a class.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     char *astReadString( AstChannel *this, const char *name,
+*                          const char *def )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function searches the current values list of a Channel to
+*     identify a string value with a specified name. If such a value
+*     is found, a pointer to the string is returned, otherwise a
+*     pointer to a copy of a default string is returned instead.
+*
+*     This function should only be invoked from within the loader
+*     function associated with a class, in order to return a string
+*     pointer value to be assigned to an instance variable. It must be
+*     preceded by a call to the astReadClassData function, which loads
+*     the values associated with the class into the current values
+*     list from the input data source.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     name
+*        Pointer to a constant null-terminated character string
+*        containing the name of the required value. This must be in
+*        lower case with no surrounding white space. Note that names
+*        longer than 6 characters will not match any value.
+*     def
+*        If no suitable string can be found (e.g. the value is absent
+*        from the data stream being read), then a dynamically
+*        allocated copy of the null-terminated string pointed at by
+*        "def" will be made, and a pointer to this copy will be
+*        returned instead (or NULL if this default pointer is NULL).
+
+*  Returned Value:
+*     A pointer to a dynamically allocated null-terminated string
+*     containing the value required, or to a copy of the default
+*     string if the value was not found (or NULL if the "def" pointer
+*     was NULL).
+
+*  Notes:
+*     - It is the caller's responsibility to arrange for the memory
+*     holding the returned string to be freed (using astFree) when it
+*     is no longer required.
+*     - 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: */
+   AstChannelValue *value;       /* Pointer to required Value structure */
+   char *result;                 /* Pointer value to return */
+
+/* Initialise. */
+   result = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Search for a Value structure with the required name in the current
+   values list.*/
+   value = LookupValue( name, status );
+   if ( astOK ) {
+
+/* If a Value was found, check that it describes a string (as opposed
+   to an Object). */
+      if ( value ) {
+         if ( !value->is_object ) {
+
+/* If so, then extract the string pointer, replacing it with NULL. */
+            result = value->ptr.string;
+            value->ptr.string = NULL;
+
+/* If the Value does not describe a string, then the wrong name has
+   probably been given, or the input data are corrupt, so report an
+   error. */
+         } else {
+            astError( AST__BADIN,
+                      "astRead(%s): The Object \"%s = <%s>\" cannot "
+                      "be read as a string.", status, astGetClass( this ),
+                      value->name, astGetClass( value->ptr.object ) );
+         }
+
+/* Free the Value structure and the resources it points at. */
+         value = FreeValue( value, status );
+
+/* If no suitable Value structure was found, then make a dynamic copy
+   of the default string (if given) and return a pointer to this. */
+      } else if ( def ) {
+         result = astStore( NULL, def, strlen( def ) + (size_t) 1 );
+      }
+   }
+
+/* Return the result. */
+   return result;
+}
+
+static void RemoveValue( AstChannelValue *value, AstChannelValue **head, int *status ) {
+/*
+*  Name:
+*     RemoveValue
+
+*  Purpose:
+*     Remove a Value structure from a circular linked list.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void RemoveValue( AstChannelValue *value, AstChannelValue **head, int *status );
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function removes a Value structure from a doubly linked
+*     circular list of such structures. The "head of list" pointer is
+*     updated to point at the element following the one removed.
+
+*  Parameters:
+*     value
+*        Pointer to the structure to be removed (note that this must
+*        actually be in the list, although this function does not
+*        check).
+*     head
+*        Address of a pointer to the element at the head of the
+*        list. This pointer will be updated to point at the list
+*        element that follows the one removed. If the list becomes
+*        empty, the pointer will be set to NULL.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Notes:
+*     - This function does not perform error chacking and does not
+*     generate errors.
+*/
+
+/* Remove the Value structure from the list by re-establishing links
+   between the elements on either side of it. */
+   value->blink->flink = value->flink;
+   value->flink->blink = value->blink;
+
+/* Update the head of list pointer to identify the following
+   element. */
+   *head = value->flink;
+
+/* If the head of list identifies the removed element, then note that
+   the list is now empty. */
+   if ( *head == value ) *head = NULL;
+
+/* Make the removed element point at itself. */
+   value->flink = value;
+   value->blink = value;
+}
+
+static void SetAttrib( AstObject *this_object, const char *setting, int *status ) {
+/*
+*  Name:
+*     SetAttrib
+
+*  Purpose:
+*     Set an attribute value for a Channel.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void SetAttrib( AstObject *this, const char *setting )
+
+*  Class Membership:
+*     Channel member function (over-rides the astSetAttrib protected
+*     method inherited from the Object class).
+
+*  Description:
+*     This function assigns an attribute value for a Channel, 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 Channel.
+*     setting
+*        Pointer to a null terminated string specifying the new attribute
+*        value.
+*/
+
+/* Local Variables: */
+   AstChannel *this;             /* Pointer to the Channel structure */
+   int comment;                  /* Comment attribute value */
+   int full;                     /* Full attribute value */
+   int indent;                   /* Indent attribute value */
+   int len;                      /* Length of setting string */
+   int nc;                       /* Number of characters read by "astSscanf" */
+   int report_level;             /* Skip attribute value */
+   int skip;                     /* Skip attribute value */
+   int sourcefile;               /* Offset of SourceFile string */
+   int sinkfile;                 /* Offset of SinkFile string */
+   int strict;                   /* Report errors instead of warnings? */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Obtain a pointer to the Channel structure. */
+   this = (AstChannel *) this_object;
+
+/* 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. */
+
+/* Comment. */
+/* ---------*/
+   if ( nc = 0,
+        ( 1 == astSscanf( setting, "comment= %d %n", &comment, &nc ) )
+        && ( nc >= len ) ) {
+      astSetComment( this, comment );
+
+/* Full. */
+/* ----- */
+   } else if ( nc = 0,
+               ( 1 == astSscanf( setting, "full= %d %n", &full, &nc ) )
+               && ( nc >= len ) ) {
+      astSetFull( this, full );
+
+/* Indent. */
+/* ------- */
+   } else if ( nc = 0,
+               ( 1 == astSscanf( setting, "indent= %d %n", &indent, &nc ) )
+               && ( nc >= len ) ) {
+      astSetIndent( this, indent );
+
+/* ReportLavel. */
+/* ------------ */
+   } else if ( nc = 0,
+               ( 1 == astSscanf( setting, "reportlevel= %d %n", &report_level, &nc ) )
+               && ( nc >= len ) ) {
+      astSetReportLevel( this, report_level );
+
+/* Skip. */
+/* ----- */
+   } else if ( nc = 0,
+               ( 1 == astSscanf( setting, "skip= %d %n", &skip, &nc ) )
+               && ( nc >= len ) ) {
+      astSetSkip( this, skip );
+
+/* SinkFile. */
+/* --------- */
+   } else if ( nc = 0,
+               ( 0 == astSscanf( setting, "sinkfile=%n%*[^\n]%n", &sinkfile, &nc ) )
+               && ( nc >= len ) ) {
+      astSetSinkFile( this, setting + sinkfile );
+
+/* SourceFile. */
+/* ----------- */
+   } else if ( nc = 0,
+               ( 0 == astSscanf( setting, "sourcefile=%n%*[^\n]%n", &sourcefile, &nc ) )
+               && ( nc >= len ) ) {
+      astSetSourceFile( this, setting + sourcefile );
+
+/* Strict. */
+/* ------- */
+   } else if ( nc = 0,
+               ( 1 == astSscanf( setting, "strict= %d %n", &strict, &nc ) )
+               && ( nc >= len ) ) {
+      astSetStrict( this, strict );
+
+/* If the attribute is still not recognised, pass it on to the parent
+   method for further interpretation. */
+   } else {
+      (*parent_setattrib)( this_object, setting, status );
+   }
+}
+
+static void SinkWrap( void (* sink)( const char * ), const char *line, int *status ) {
+/*
+*  Name:
+*     SinkWrap
+
+*  Purpose:
+*     Wrapper function to invoke a C Channel sink function.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void SinkWrap( void (* sink)( const char * ), const char *line, int *status )
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function invokes the sink function whose pointer is
+*     supplied in order to write an output line to an external data
+*     store.
+
+*  Parameters:
+*     sink
+*        Pointer to a sink function, whose single parameter is a
+*        pointer to a const, null-terminated string containing the
+*        text to be written, and which returns void. This is the form
+*        of Channel sink function employed by the C language interface
+*        to the AST library.
+*     status
+*        Pointer to the inherited status variable.
+*/
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Invoke the sink function. */
+   ( *sink )( line );
+}
+
+static char *SourceWrap( const char *(* source)( void ), int *status ) {
+/*
+*  Name:
+*     SourceWrap
+
+*  Purpose:
+*     Wrapper function to invoke a C Channel source function.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     char *SourceWrap( const char *, int *status(* source)( void ) )
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function invokes the source function whose pointer is
+*     supplied in order to read the next input line from an external
+*     data store. It then returns a pointer to a dynamic string
+*     containing a copy of the text that was read.
+
+*  Parameters:
+*     source
+*        Pointer to a source function, with no parameters, that
+*        returns a pointer to a const, null-terminated string
+*        containing the text that it read. This is the form of Channel
+*        source function employed by the C language interface to the
+*        AST library.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Returned Value:
+*     A pointer to a dynamically allocated, null terminated string
+*     containing a copy of the text that was read. This string must be
+*     freed by the caller (using astFree) when no longer required.
+*
+*     A NULL pointer will be returned if there is no more input text
+*     to read.
+
+*  Notes:
+*     - A NULL pointer value 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 *result;                 /* Pointer value to return */
+   const char *line;             /* Pointer to input line */
+
+/* Initialise. */
+   result = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Invoke the source function to read the next input line and return a
+   pointer to the resulting string. */
+   line = ( *source )();
+
+/* If a string was obtained, make a dynamic copy of it and save the
+   resulting pointer. */
+   if ( line ) result = astString( line, (int) strlen( line ) );
+
+/* Return the result. */
+   return result;
+}
+
+void astStoreChannelData_( AstChannel *this, int *status ) {
+/*
+*+
+*  Name:
+*     astStoreChannelData
+
+*  Purpose:
+*     Store the Channel's channel-data pointer in a thread-specific
+*     global variable.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     astStoreChannelData( AstChannel *this )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function stores the Channel's channel-data pointer (if any)
+*     established by the previous call to astPutChannelData, in a
+*     thread-specific global variable from where the astChannelData macro
+*     can access it.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* Store the pointer int he global variable. */
+   channel_data = this->data;
+}
+
+static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) {
+/*
+*  Name:
+*     TestAttrib
+
+*  Purpose:
+*     Test if a specified attribute value is set for a Channel.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     int TestAttrib( AstObject *this, const char *attrib, int *status )
+
+*  Class Membership:
+*     Channel member function (over-rides the astTestAttrib protected
+*     method inherited from the Object class).
+
+*  Description:
+*     This function returns a boolean result (0 or 1) to indicate whether
+*     a value has been set for one of a Channel's attributes.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     attrib
+*        Pointer to a null terminated string specifying the attribute
+*        name.  This should be in lower case with no surrounding white
+*        space.
+*     status
+*        Pointer to the inherited status variable.
+
+*  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: */
+   AstChannel *this;             /* Pointer to the Channel structure */
+   int result;                   /* Result value to return */
+
+/* Initialise. */
+   result = 0;
+
+/* Check the global error status. */
+   if ( !astOK ) return result;
+
+/* Obtain a pointer to the Channel structure. */
+   this = (AstChannel *) this_object;
+
+/* Check the attribute name and test the appropriate attribute. */
+
+/* Comment. */
+/* -------- */
+   if ( !strcmp( attrib, "comment" ) ) {
+      result = astTestComment( this );
+
+/* Full. */
+/* ----- */
+   } else if ( !strcmp( attrib, "full" ) ) {
+      result = astTestFull( this );
+
+/* Indent. */
+/* ------- */
+   } else if ( !strcmp( attrib, "indent" ) ) {
+      result = astTestIndent( this );
+
+/* ReportLevel. */
+/* ------------ */
+   } else if ( !strcmp( attrib, "reportlevel" ) ) {
+      result = astTestReportLevel( this );
+
+/* Skip. */
+/* ----- */
+   } else if ( !strcmp( attrib, "skip" ) ) {
+      result = astTestSkip( this );
+
+/* SourceFile. */
+/* ----------- */
+   } else if ( !strcmp( attrib, "sourcefile" ) ) {
+      result = astTestSourceFile( this );
+
+/* SinkFile. */
+/* ----------- */
+   } else if ( !strcmp( attrib, "sinkfile" ) ) {
+      result = astTestSinkFile( this );
+
+/* Strict. */
+/* ------- */
+   } else if ( !strcmp( attrib, "strict" ) ) {
+      result = astTestStrict( this );
+
+/* If the attribute is still not recognised, pass it on to the parent
+   method for further interpretation. */
+   } else {
+      result = (*parent_testattrib)( this_object, attrib, status );
+   }
+
+/* Return the result, */
+   return result;
+}
+
+static void Unquote( AstChannel *this, char *str, int *status ) {
+/*
+*  Name:
+*     Unquote
+
+*  Purpose:
+*     Remove quotes from a (possibly) quoted string.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void Unquote( AstChannel *this, char *str, int *status )
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function removes one layer of quote characters (") from a
+*     string which is possibly quoted. Any quotes within quotes (which
+*     should have been doubled when the string was originally quoted)
+*     are also converted back to single quotes again.
+*
+*     The quotes need not start or end at the ends of the string, and
+*     there may be any number of quoted sections within the string. No
+*     error results if the string does not contain any quotes at all
+*     (it is simply returned unchanged), but an error results if any
+*     unmatched quotes are found.
+
+*  Parameters:
+*     this
+*        Pointer to a Channel. This is only used for constructing error
+*        messages and has no influence on the string processing.
+*     str
+*        Pointer to the null-terminated string to be processed. This
+*        is modified in place. The new string starts at the same
+*        location as the original but has a new null character
+*        appended if necessary (it will usually be shorter than the
+*        original).
+*     status
+*        Pointer to the inherited status variable.
+*/
+
+/* Local Variables: */
+   int i;                        /* Loop counter for "input" characters */
+   int j;                        /* Counter for "output" characters */
+   int quoted;                   /* Inside a quoted string? */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Loop to inspect each character in the string. */
+   quoted = 0;
+   for ( i = j = 0; str[ i ]; i++ ) {
+
+/* Non-quote characters are simply copied to their new location in the
+   string. */
+      if ( str[ i ] != '"' ) {
+         str[ j++ ] = str[ i ];
+
+/* If a quote character '"' is encountered and we are not already in a
+   quoted string, then note the start of a quoted string (and discard
+   the quote). */
+      } else if ( !quoted ) {
+         quoted = 1;
+
+/* If a quote character is encountered inside a quoted string, then
+   check if the next character is also a quote. If so, convert this
+   double quote to a single one. */
+      } else if ( str[ i + 1 ] == '"' ) {
+         str[ j++ ] = '"';
+         i++;
+
+/* If a single quote character is encountered inside a quoted string,
+   then note the end of the quoted string (and discard the quote). */
+      } else {
+         quoted = 0;
+      }
+   }
+
+/* Append a null to terminate the processed string. */
+   str[ j ] = '\0';
+
+/* If the "quoted" flag is still set, then there were unmatched
+   quotes, so report an error. */
+   if ( quoted ) {
+      astError( AST__UNMQT,
+                "astRead(%s): Unmatched quotes in input data: %s.", status,
+                astGetClass( this ), str );
+   }
+}
+
+static int Use( AstChannel *this, int set, int helpful, int *status ) {
+/*
+*  Name:
+*     Use
+
+*  Purpose:
+*     Decide whether to write a value to a data sink.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     int Use( AstChannel *this, int set, int helpful, int *status )
+
+*  Class Membership:
+*     Channel member function.
+
+*  Description:
+*     This function decides whether a value supplied by a class "Dump"
+*     function, via a call to one of the astWrite... protected
+*     methods, should actually be written to the data sink associated
+*     with a Channel.
+*
+*     This decision is based on the settings of the "set" and
+*     "helpful" flags supplied to the astWrite... method, plus the
+*     attribute settings of the Channel.
+
+*  Parameters:
+*     this
+*        A pointer to the Channel.
+*     set
+*        The "set" flag supplied.
+*     helpful
+*        The "helpful" value supplied.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Returned Value:
+*     One if the value should be written out, otherwise zero.
+
+*  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 full;                     /* Full attribute value */
+   int result;                   /* Result value to be returned */
+
+/* Check the global error status. */
+   if ( !astOK ) return 0;
+
+/* If "set" is non-zero, then so is the result ("set" values must
+   always be written out). */
+   result = ( set != 0 );
+
+/* Otherwise, obtain the value of the Channel's Full attribute. */
+   if ( !set ) {
+      full = astGetFull( this );
+
+/* If Full is positive, display all values, if zero, display only
+   "helpful" values, if negative, display no (un-"set") values. */
+      if ( astOK ) result = ( ( helpful && ( full > -1 ) ) || ( full > 0 ) );
+   }
+
+/* Return the result. */
+   return result;
+}
+
+static int Write( AstChannel *this, AstObject *object, int *status ) {
+/*
+*++
+*  Name:
+c     astWrite
+f     AST_WRITE
+
+*  Purpose:
+*     Write an Object to a Channel.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "channel.h"
+c     int astWrite( AstChannel *this, AstObject *object )
+f     RESULT = AST_WRITE( THIS, OBJECT, STATUS )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function writes an Object to a Channel, appending it to any
+*     previous Objects written to that Channel.
+
+*  Parameters:
+c     this
+f     THIS = INTEGER (Given)
+*        Pointer to the Channel.
+c     object
+f     OBJECT = INTEGER (Given)
+*        Pointer to the Object which is to be written.
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astWrite()
+f     AST_WRITE = INTEGER
+*        The number of Objects written to the Channel by this
+c        invocation of astWrite (normally, this will be one).
+f        invocation of AST_WRITE (normally, this will be one).
+
+*  Applicability:
+*     FitsChan
+*        If the FitsChan uses a foreign encoding (e.g. FITS-WCS) rather
+*        than the native AST encoding, then storing values in the
+*        FitsChan for keywords NAXIS1, NAXIS2, etc., before invoking
+c        astWrite
+f        AST_WRITE
+*        can help to produce a successful write.
+
+*  Notes:
+*     - 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
+f     with STATUS set to an error value, or if it should fail for any
+*     reason.
+*     - Invoking this function will usually cause the sink function
+*     associated with the channel to be called in order to transfer a
+*     textual description of the supplied object to some external data
+*     store. However, the FitsChan class behaves differently. Invoking
+*     this function on a FitsChan causes new FITS header cards to be
+*     added to an internal buffer (the sink function is not invoked).
+*     This buffer is written out through the sink function only when the
+*     FitsChan is deleted.
+*--
+*/
+
+/* Check the global error status. */
+   if ( !astOK ) return 0;
+
+/* The work of this function is actually performed by the protected
+   astDump method of the Object. The fact that this is further
+   encapsulated within the astWrite method (which belongs to the
+   Channel) is simply a trick to allow it to be over-ridden either by
+   a derived Channel, or a derived Object (or both), and hence to
+   adapt to the nature of either argument. */
+   astDump( object, this );
+
+/* Return the number of Objects written. */
+   return astOK ? 1 : 0;
+}
+
+static void WriteBegin( AstChannel *this, const char *class,
+                        const char *comment, int *status ) {
+/*
+*+
+*  Name:
+*     astWriteBegin
+
+*  Purpose:
+*     Write a "Begin" data item to a data sink.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astWriteBegin( AstChannel *this, const char *class,
+*                         const char *comment )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function writes a "Begin" data item to the data sink
+*     associated with a Channel, so as to begin the output of a new
+*     Object definition.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     class
+*        Pointer to a constant null-terminated string containing the
+*        name of the class to which the Object belongs.
+*     comment
+*        Pointer to a constant null-terminated string containing a
+*        textual comment to be associated with the "Begin"
+*        item. Normally, this will describe the purpose of the Object.
+
+*  Notes:
+*     - The comment supplied may not actually be used, depending on
+*     the nature of the Channel supplied.
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+   char *line;                   /* Pointer to dynamic output string */
+   int i;                        /* Loop counter for indentation characters */
+   int nc;                       /* Number of output characters */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* Start building a dynamic string with an initial space. Then add
+   further spaces to suit the current indentation level. */
+   line = astAppendString( NULL, &nc, " " );
+   for ( i = 0; i < current_indent; i++ ) {
+      line = astAppendString( line, &nc, " " );
+   }
+
+/* Append the "Begin" keyword followed by the class name. */
+   line = astAppendString( line, &nc, "Begin " );
+   line = astAppendString( line, &nc, class );
+
+/* If required, also append the comment. */
+   if ( astGetComment( this ) && *comment ) {
+      line = astAppendString( line, &nc, " \t# " );
+      line = astAppendString( line, &nc, comment );
+   }
+
+/* Write out the resulting line of text. */
+   OutputTextItem( this, line, status );
+
+/* Free the dynamic string. */
+   line = astFree( line );
+
+/* Increment the indentation level and clear the count of items written
+   for this Object. */
+   current_indent += astGetIndent( this );
+   items_written = 0;
+}
+
+static void WriteDouble( AstChannel *this, const char *name,
+                         int set, int helpful,
+                         double value, const char *comment, int *status ) {
+/*
+*+
+*  Name:
+*     astWriteDouble
+
+*  Purpose:
+*     Write a double value to a data sink.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astWriteDouble( AstChannel *this, const char *name,
+*                          int set, int helpful,
+*                          double value, const char *comment )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function writes a named double value, representing the
+*     value of a class instance variable, to the data sink associated
+*     with a Channel. It is intended for use by class "Dump" functions
+*     when writing out class information which will subsequently be
+*     re-read.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     name
+*        Pointer to a constant null-terminated string containing the
+*        name to be used to identify the value in the external
+*        representation. This will form the key for identifying it
+*        again when it is re-read. The name supplied should be unique
+*        within its class.
+*
+*        Mixed case may be used and will be preserved in the external
+*        representation (where possible) for cosmetic effect. However,
+*        case is not significant when re-reading values.
+*
+*        It is recommended that a maximum of 6 alphanumeric characters
+*        (starting with an alphabetic character) be used. This permits
+*        maximum flexibility in adapting to standard external data
+*        representations (e.g. FITS).
+*     set
+*        If this is zero, it indicates that the value being written is
+*        a default value (or can be re-generated from other values) so
+*        need not necessarily be written out. Such values will
+*        typically be included in the external representation with
+*        (e.g.) a comment character so that they are available to
+*        human readers but will be ignored when re-read. They may also
+*        be completely omitted in some circumstances.
+*
+*        If "set" is non-zero, the value will always be explicitly
+*        included in the external representation so that it can be
+*        re-read.
+*     helpful
+*        This flag provides a hint about whether a value whose "set"
+*        flag is zero (above) should actually appear at all in the
+*        external representaton.
+*
+*        If the external representation allows values to be "commented
+*        out" then, by default, values will be included in this form
+*        only if their "helpful" flag is non-zero. Otherwise, they
+*        will be omitted entirely. When possible, omitting the more
+*        obscure values associated with a class is recommended in
+*        order to improve readability.
+*
+*        This default behaviour may be further modified if the
+*        Channel's Full attribute is set - either to permit all values
+*        to be shown, or to suppress non-essential information
+*        entirely.
+*     value
+*        The value to be written.
+*     comment
+*        Pointer to a constant null-terminated string containing a
+*        textual comment to be associated with the value.
+*
+*        Note that this comment may not actually be used, depending on
+*        the nature of the Channel supplied and the setting of its
+*        Comment attribute.
+*-
+*/
+
+/* Local Constants: */
+#define BUFF_LEN 100             /* Size of local formatting buffer */
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+   char *line;                   /* Pointer to dynamic output string */
+   char buff[ BUFF_LEN + 1 ];    /* Local formatting buffer */
+   int i;                        /* Loop counter for indentation characters */
+   int nc;                       /* Number of output characters */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* Use the "set" and "helpful" flags, along with the Channel's
+   attributes to decide whether this value should actually be
+   written. */
+   if ( Use( this, set, helpful, status ) ) {
+
+/* Start building a dynamic string with an initial space, or a comment
+   character if "set" is zero. Then add further spaces to suit the
+   current indentation level. */
+      line = astAppendString( NULL, &nc, set ? " " : "#" );
+      for ( i = 0; i < current_indent; i++ ) {
+         line = astAppendString( line, &nc, " " );
+      }
+
+/* Append the name string followed by " = ". */
+      line = astAppendString( line, &nc, name );
+      line = astAppendString( line, &nc, " = " );
+
+/* Format the value as a string and append this. Make sure "-0" isn't
+   produced. Use a magic string to represent bad values. */
+      if( value != AST__BAD ) {
+         (void) sprintf( buff, "%.*g", AST__DBL_DIG, value );
+         if ( !strcmp( buff, "-0" ) ) {
+            buff[ 0 ] = '0';
+            buff[ 1 ] = '\0';
+         }
+      } else {
+         strcpy( buff, BAD_STRING );
+      }
+      line = astAppendString( line, &nc, buff );
+
+/* If required, also append the comment. */
+      if ( astGetComment( this ) && *comment ) {
+         line = astAppendString( line, &nc, " \t# " );
+         line = astAppendString( line, &nc, comment );
+      }
+
+/* Write out the resulting line of text. */
+      OutputTextItem( this, line, status );
+
+/* Free the dynamic string. */
+      line = astFree( line );
+   }
+
+/* Undefine macros local to this function. */
+#undef BUFF_LEN
+}
+
+static void WriteEnd( AstChannel *this, const char *class, int *status ) {
+/*
+*+
+*  Name:
+*     astWriteEnd
+
+*  Purpose:
+*     Write an "End" data item to a data sink.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astWriteEnd( AstChannel *this, const char *class )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function writes an "End" data item to the data sink
+*     associated with a Channel. This item delimits the end of an
+*     Object definition.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     class
+*        Pointer to a constant null-terminated string containing the
+*        class name of the Object whose definition is being terminated
+*        by the "End" item.
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+   char *line;                   /* Pointer to dynamic output string */
+   int i;                        /* Loop counter for indentation characters */
+   int nc;                       /* Number of output characters */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* Decrement the indentation level so that the "End" item matches the
+   corresponding "Begin" item. */
+   current_indent -= astGetIndent( this );
+
+/* Start building a dynamic string with an initial space. Then add
+   further spaces to suit the current indentation level. */
+   line = astAppendString( NULL, &nc, " " );
+   for ( i = 0; i < current_indent; i++ ) {
+      line = astAppendString( line, &nc, " " );
+   }
+
+/* Append the "End" keyword followed by the class name. */
+   line = astAppendString( line, &nc, "End " );
+   line = astAppendString( line, &nc, class );
+
+/* Write out the resulting line of text. */
+   OutputTextItem( this, line, status );
+
+/* Free the dynamic string. */
+   line = astFree( line );
+}
+
+static void WriteInt( AstChannel *this, const char *name, int set, int helpful,
+                      int value, const char *comment, int *status ) {
+/*
+*+
+*  Name:
+*     astWriteInt
+
+*  Purpose:
+*     Write an integer value to a data sink.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astWriteInt( AstChannel *this, const char *name,
+*                       int set, int helpful,
+*                       int value, const char *comment )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function writes a named integer value, representing the
+*     value of a class instance variable, to the data sink associated
+*     with a Channel. It is intended for use by class "Dump" functions
+*     when writing out class information which will subsequently be
+*     re-read.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     name
+*        Pointer to a constant null-terminated string containing the
+*        name to be used to identify the value in the external
+*        representation. This will form the key for identifying it
+*        again when it is re-read. The name supplied should be unique
+*        within its class.
+*
+*        Mixed case may be used and will be preserved in the external
+*        representation (where possible) for cosmetic effect. However,
+*        case is not significant when re-reading values.
+*
+*        It is recommended that a maximum of 6 alphanumeric characters
+*        (starting with an alphabetic character) be used. This permits
+*        maximum flexibility in adapting to standard external data
+*        representations (e.g. FITS).
+*     set
+*        If this is zero, it indicates that the value being written is
+*        a default value (or can be re-generated from other values) so
+*        need not necessarily be written out. Such values will
+*        typically be included in the external representation with
+*        (e.g.) a comment character so that they are available to
+*        human readers but will be ignored when re-read. They may also
+*        be completely omitted in some circumstances.
+*
+*        If "set" is non-zero, the value will always be explicitly
+*        included in the external representation so that it can be
+*        re-read.
+*     helpful
+*        This flag provides a hint about whether a value whose "set"
+*        flag is zero (above) should actually appear at all in the
+*        external representaton.
+*
+*        If the external representation allows values to be "commented
+*        out" then, by default, values will be included in this form
+*        only if their "helpful" flag is non-zero. Otherwise, they
+*        will be omitted entirely. When possible, omitting the more
+*        obscure values associated with a class is recommended in
+*        order to improve readability.
+*
+*        This default behaviour may be further modified if the
+*        Channel's Full attribute is set - either to permit all values
+*        to be shown, or to suppress non-essential information
+*        entirely.
+*     value
+*        The value to be written.
+*     comment
+*        Pointer to a constant null-terminated string containing a
+*        textual comment to be associated with the value.
+*
+*        Note that this comment may not actually be used, depending on
+*        the nature of the Channel supplied and the setting of its
+*        Comment attribute.
+*-
+*/
+
+/* Local Constants: */
+#define BUFF_LEN 50              /* Size of local formatting buffer */
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+   char *line;                   /* Pointer to dynamic output string */
+   char buff[ BUFF_LEN + 1 ];    /* Local formatting buffer */
+   int i;                        /* Loop counter for indentation characters */
+   int nc;                       /* Number of output characters */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* Use the "set" and "helpful" flags, along with the Channel's
+   attributes to decide whether this value should actually be
+   written. */
+   if ( Use( this, set, helpful, status ) ) {
+
+/* Start building a dynamic string with an initial space, or a comment
+   character if "set" is zero. Then add further spaces to suit the
+   current indentation level. */
+      line = astAppendString( NULL, &nc, set ? " " : "#" );
+      for ( i = 0; i < current_indent; i++ ) {
+         line = astAppendString( line, &nc, " " );
+      }
+
+/* Append the name string followed by " = ". */
+      line = astAppendString( line, &nc, name );
+      line = astAppendString( line, &nc, " = " );
+
+/* Format the value as a decimal string and append this. */
+      (void) sprintf( buff, "%d", value );
+      line = astAppendString( line, &nc, buff );
+
+/* If required, also append the comment. */
+      if ( astGetComment( this ) && *comment ) {
+         line = astAppendString( line, &nc, " \t# " );
+         line = astAppendString( line, &nc, comment );
+      }
+
+/* Write out the resulting line of text. */
+      OutputTextItem( this, line, status );
+
+/* Free the dynamic string. */
+      line = astFree( line );
+   }
+
+/* Undefine macros local to this function. */
+#undef BUFF_LEN
+}
+
+int astWriteInvocations_( int *status ){
+/*
+*+
+*  Name:
+*     astWriteInvocations
+
+*  Purpose:
+*     Returns the number of invocations of the astWrite method.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     int astWriteInvocations
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function returns the number of invocations of astWrite which
+*     have been made so far, excluding those made from within the
+*     astWriteObject method. An example of its use is to allow a Dump
+*     function to determine if a sub-object has already been dumped
+*     during the current invocation of astWrite. See the Dump method for
+*     the AstUnit class as an example.
+*-
+*/
+   astDECLARE_GLOBALS
+   astGET_GLOBALS(NULL);
+   return nwrite_invoc;
+}
+
+static void WriteIsA( AstChannel *this, const char *class,
+                      const char *comment, int *status ) {
+/*
+*+
+*  Name:
+*     astWriteIsA
+
+*  Purpose:
+*     Write an "IsA" data item to a data sink.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astWriteIsA( AstChannel *this, const char *class,
+*                       const char *comment )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function writes an "IsA" data item to the data sink
+*     associated with a Channel. This item delimits the end of the
+*     data associated with the instance variables of a class, as part
+*     of an overall Object definition.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     class
+*        Pointer to a constant null-terminated string containing the
+*        name of the class whose data are terminated by the "IsA"
+*        item.
+*     comment
+*        Pointer to a constant null-terminated string containing a
+*        textual comment to be associated with the "IsA"
+*        item. Normally, this will describe the purpose of the class
+*        whose data are being terminated.
+
+*  Notes:
+*     - The comment supplied may not actually be used, depending on
+*     the nature of the Channel supplied.
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+   char *line;                   /* Pointer to dynamic output string */
+   int i;                        /* Loop counter for indentation characters */
+   int indent_inc;               /* Indentation increment */
+   int nc;                       /* Number of output characters */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* Output an "IsA" item only if there has been at least one item
+   written since the last "Begin" or "IsA" item, or if the Full
+   attribute for the Channel is greater than zero (requesting maximum
+   information). */
+   if ( items_written || astGetFull( this ) > 0 ) {
+
+/* Start building a dynamic string with an initial space. Then add
+   further spaces to suit the current indentation level, but reduced
+   by one to allow the "IsA" item to match the "Begin" and "End" items
+   which enclose it. */
+      indent_inc = astGetIndent( this );
+      line = astAppendString( NULL, &nc, " " );
+      for ( i = 0; i < ( current_indent - indent_inc ); i++ ) {
+         line = astAppendString( line, &nc, " " );
+      }
+
+/* Append the "IsA" keyword followed by the class name. */
+      line = astAppendString( line, &nc, "IsA " );
+      line = astAppendString( line, &nc, class );
+
+/* If required, also append the comment. */
+      if ( astGetComment( this ) && *comment ) {
+         line = astAppendString( line, &nc, " \t# " );
+         line = astAppendString( line, &nc, comment );
+      }
+
+/* Write out the resulting line of text. */
+      OutputTextItem( this, line, status );
+
+/* Free the dynamic string. */
+      line = astFree( line );
+
+/* Clear the count of items written for this class. */
+      items_written = 0;
+   }
+}
+
+static void WriteObject( AstChannel *this, const char *name,
+                         int set, int helpful,
+                         AstObject *value, const char *comment, int *status ) {
+/*
+*+
+*  Name:
+*     astWriteObject
+
+*  Purpose:
+*     Write an Object as a value to a data sink.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astWriteObject( AstChannel *this, const char *name,
+*                          int set, int helpful,
+*                          AstObject *value, const char *comment )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function writes an Object as a named value, representing
+*     the value of a class instance variable, to the data sink
+*     associated with a Channel. It is intended for use by class
+*     "Dump" functions when writing out class information which will
+*     subsequently be re-read.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     name
+*        Pointer to a constant null-terminated string containing the
+*        name to be used to identify the value in the external
+*        representation. This will form the key for identifying it
+*        again when it is re-read. The name supplied should be unique
+*        within its class.
+*
+*        Mixed case may be used and will be preserved in the external
+*        representation (where possible) for cosmetic effect. However,
+*        case is not significant when re-reading values.
+*
+*        It is recommended that a maximum of 6 alphanumeric characters
+*        (starting with an alphabetic character) be used. This permits
+*        maximum flexibility in adapting to standard external data
+*        representations (e.g. FITS).
+*     set
+*        If this is zero, it indicates that the value being written is
+*        a default value (or can be re-generated from other values) so
+*        need not necessarily be written out. Such values will
+*        typically be included in the external representation with
+*        (e.g.) a comment character so that they are available to
+*        human readers but will be ignored when re-read. They may also
+*        be completely omitted in some circumstances.
+*
+*        If "set" is non-zero, the value will always be explicitly
+*        included in the external representation so that it can be
+*        re-read.
+*     helpful
+*        This flag provides a hint about whether a value whose "set"
+*        flag is zero (above) should actually appear at all in the
+*        external representaton.
+*
+*        If the external representation allows values to be "commented
+*        out" then, by default, values will be included in this form
+*        only if their "helpful" flag is non-zero. Otherwise, they
+*        will be omitted entirely. When possible, omitting the more
+*        obscure values associated with a class is recommended in
+*        order to improve readability.
+*
+*        This default behaviour may be further modified if the
+*        Channel's Full attribute is set - either to permit all values
+*        to be shown, or to suppress non-essential information
+*        entirely.
+*     value
+*        A Pointer to the Object to be written.
+*     comment
+*        Pointer to a constant null-terminated string containing a
+*        textual comment to be associated with the value.
+*
+*        Note that this comment may not actually be used, depending on
+*        the nature of the Channel supplied and the setting of its
+*        Comment attribute.
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+   char *line;                   /* Pointer to dynamic output string */
+   int i;                        /* Loop counter for indentation characters */
+   int indent_inc;               /* Indentation increment */
+   int nc;                       /* Number of output characters */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* Use the "set" and "helpful" flags, along with the Channel's
+   attributes to decide whether this value should actually be
+   written. */
+   if ( Use( this, set, helpful, status ) ) {
+
+/* Start building a dynamic string with an initial space, or a comment
+   character if "set" is zero. Then add further spaces to suit the
+   current indentation level. */
+      line = astAppendString( NULL, &nc, set ? " " : "#" );
+      for ( i = 0; i < current_indent; i++ ) {
+         line = astAppendString( line, &nc, " " );
+      }
+
+/* Append the name string followed by " =". The absence of a value on
+   the right hand side indicates an Object value, whose definition
+   follows. */
+      line = astAppendString( line, &nc, name );
+      line = astAppendString( line, &nc, " =" );
+
+/* If required, also append the comment. */
+      if ( astGetComment( this ) && *comment ) {
+         line = astAppendString( line, &nc, " \t# " );
+         line = astAppendString( line, &nc, comment );
+      }
+
+/* Write out the resulting line of text. */
+      OutputTextItem( this, line, status );
+
+/* Free the dynamic string. */
+      line = astFree( line );
+
+/* If the value is not a default, write the Object to the Channel as
+   well, suitably indented (this is omitted if the value is commented
+   out). */
+      if ( set ) {
+         indent_inc = astGetIndent( this );
+         current_indent += indent_inc;
+         (void) astWrite( this, value );
+         current_indent -= indent_inc;
+      }
+   }
+}
+
+static void WriteString( AstChannel *this, const char *name,
+                         int set, int helpful,
+                         const char *value, const char *comment, int *status ) {
+/*
+*+
+*  Name:
+*     astWriteString
+
+*  Purpose:
+*     Write a string value to a data sink.
+
+*  Type:
+*     Protected virtual function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     void astWriteString( AstChannel *this, const char *name,
+*                          int set, int helpful,
+*                          const char *value, const char *comment )
+
+*  Class Membership:
+*     Channel method.
+
+*  Description:
+*     This function writes a named string value, representing the
+*     value of a class instance variable, to the data sink associated
+*     with a Channel. It is intended for use by class "Dump" functions
+*     when writing out class information which will subsequently be
+*     re-read.
+
+*  Parameters:
+*     this
+*        Pointer to the Channel.
+*     name
+*        Pointer to a constant null-terminated string containing the
+*        name to be used to identify the value in the external
+*        representation. This will form the key for identifying it
+*        again when it is re-read. The name supplied should be unique
+*        within its class.
+*
+*        Mixed case may be used and will be preserved in the external
+*        representation (where possible) for cosmetic effect. However,
+*        case is not significant when re-reading values.
+*
+*        It is recommended that a maximum of 6 alphanumeric characters
+*        (starting with an alphabetic character) be used. This permits
+*        maximum flexibility in adapting to standard external data
+*        representations (e.g. FITS).
+*     set
+*        If this is zero, it indicates that the value being written is
+*        a default value (or can be re-generated from other values) so
+*        need not necessarily be written out. Such values will
+*        typically be included in the external representation with
+*        (e.g.) a comment character so that they are available to
+*        human readers but will be ignored when re-read. They may also
+*        be completely omitted in some circumstances.
+*
+*        If "set" is non-zero, the value will always be explicitly
+*        included in the external representation so that it can be
+*        re-read.
+*     helpful
+*        This flag provides a hint about whether a value whose "set"
+*        flag is zero (above) should actually appear at all in the
+*        external representaton.
+*
+*        If the external representation allows values to be "commented
+*        out" then, by default, values will be included in this form
+*        only if their "helpful" flag is non-zero. Otherwise, they
+*        will be omitted entirely. When possible, omitting the more
+*        obscure values associated with a class is recommended in
+*        order to improve readability.
+*
+*        This default behaviour may be further modified if the
+*        Channel's Full attribute is set - either to permit all values
+*        to be shown, or to suppress non-essential information
+*        entirely.
+*     value
+*        Pointer to a constant null-terminated string containing the
+*        value to be written.
+*     comment
+*        Pointer to a constant null-terminated string containing a
+*        textual comment to be associated with the value.
+*
+*        Note that this comment may not actually be used, depending on
+*        the nature of the Channel supplied and the setting of its
+*        Comment attribute.
+*-
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+   char *line;                   /* Pointer to dynamic output string */
+   int i;                        /* Loop counter for characters */
+   int nc;                       /* Number of output characters */
+   int quote;                    /* Quote character found? */
+   int size;                     /* Size of allocated memory */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Get a pointer to the structure holding thread-specific global data. */
+   astGET_GLOBALS(this);
+
+/* Use the "set" and "helpful" flags, along with the Channel's
+   attributes to decide whether this value should actually be
+   written. */
+   if ( Use( this, set, helpful, status ) ) {
+
+/* Start building a dynamic string with an initial space, or a comment
+   character if "set" is zero. Then add further spaces to suit the
+   current indentation level. */
+      line = astAppendString( NULL, &nc, set ? " " : "#" );
+      for ( i = 0; i < current_indent; i++ ) {
+         line = astAppendString( line, &nc, " " );
+      }
+
+/* Append the name string followed by " = " and an opening quote
+   character (the string will be quoted to protect leading and
+   trailing spaces). */
+      line = astAppendString( line, &nc, name );
+      line = astAppendString( line, &nc, " = \"" );
+
+/* We now append the value string, but must inspect each character so
+   that quotes (appearing inside quotes) can be doubled. Determine the
+   current size of memory allocated for the dynamic string. */
+      size = (int) astSizeOf( line );
+
+/* Loop to inspect each character and see if it is a quote. */
+      for ( i = 0; value[ i ]; i++ ) {
+         quote = ( value[ i ] == '"' );
+
+/* If more memory is required, extend the dynamic string (allowing for
+   doubling of quotes and the final null) and save its new size. */
+         if ( nc + 2 + quote > size ) {
+            line = astGrow( line, nc + 2 + quote, sizeof( char ) );
+            if ( astOK ) {
+               size = (int) astSizeOf( line );
+
+/* Quit if an error occurs. */
+            } else {
+               break;
+            }
+         }
+
+/* Append the value character to the dynamic string, duplicating each
+   quote character. */
+         line[ nc++ ] = value[ i ];
+         if ( quote ) line[ nc++ ] = '"';
+      }
+
+/* Append the closing quote. */
+      line = astAppendString( line, &nc, "\"" );
+
+/* If required, also append the comment. */
+      if ( astGetComment( this ) && *comment ) {
+         line = astAppendString( line, &nc, " \t# " );
+         line = astAppendString( line, &nc, comment );
+      }
+
+/* Write out the resulting line of text. */
+      OutputTextItem( this, line, status );
+
+/* Free the dynamic string. */
+      line = astFree( line );
+   }
+}
+
+/* Functions which access class attributes. */
+/* ---------------------------------------- */
+/* Implement member functions to access the attributes associated with
+   this class using the macros defined for this purpose in the
+   "object.h" file. */
+
+/*
+*att++
+*  Name:
+*     SourceFile
+
+*  Purpose:
+*     Input file from which to read data.
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     String.
+
+*  Description:
+*     This attribute specifies the name of a file from which the Channel
+*     should read data. If specified it is used in preference to any source
+*     function specified when the Channel was created.
+*
+*     Assigning a new value to this attribute will cause any previously
+*     opened SourceFile to be closed. The first subsequent call to
+c     astRead
+f     AST_READ
+*     will attempt to open the new file (an error will be reported if the
+*     file cannot be opened), and read data from it. All subsequent call to
+c     astRead
+f     AST_READ
+*     will read data from the new file, until the SourceFile attribute is
+*     cleared or changed.
+*
+*     Clearing the attribute causes any open SourceFile to be closed. All
+*     subsequent data reads will use the source function specified when the
+*     Channel was created, or will read from standard input if no source
+*     function was specified.
+*
+*     If no value has been assigned to SourceFile, a null string will be
+*     returned if an attempt is made to get the attribute value.
+
+*  Notes:
+*     - Any open SourceFile is closed when the Channel is deleted.
+*     - If the Channel is copied or dumped
+c     (using astCopy or astShow)
+f     (using AST_COPY or AST_SHOW)
+*     the SourceFile attribute is left in a cleared state in the output
+*     Channel (i.e. the value of the SourceFile attribute is not copied).
+
+*  Applicability:
+*     FitsChan
+*        In the case of a FitsChan, the specified SourceFile supplements
+*        the source function specified when the FitsChan was created,
+*        rather than replacing the source function. The source file
+*        should be a text file (not a FITS file) containing one header per
+*        line. When a value is assigned to SourceFile, the file is opened
+*        and read immediately, and all headers read from the file are
+*        appended to the end of any header already in the FitsChan. The file
+*        is then closed. Clearing the SourceFile attribute has no further
+*        effect, other than nullifying the string (i.e. the file name)
+*        associated with the attribute.
+
+*att--
+*/
+
+/* Clear the SourceFile value by closing any open file, freeing the
+   allocated memory and assigning a NULL pointer. */
+astMAKE_CLEAR(Channel,SourceFile,fn_in,((this->fd_in=(this->fd_in?(fclose(this->fd_in),NULL):NULL)),astFree(this->fn_in)))
+
+/* If the SourceFile value is not set, supply a default in the form of a
+   pointer to the constant string "". */
+astMAKE_GET(Channel,SourceFile,const char *,NULL,( this->fn_in ? this->fn_in : "" ))
+
+/* Set a SourceFile value by closing any open file, freeing any previously
+   allocated memory, allocating new memory, storing the string and saving
+   the pointer to the copy. */
+astMAKE_SET(Channel,SourceFile,const char *,fn_in,((this->fd_in=(this->fd_in?(fclose(this->fd_in),NULL):NULL)),astStore( this->fn_in, value, strlen( value ) + (size_t) 1 )))
+
+/* The SourceFile value is set if the pointer to it is not NULL. */
+astMAKE_TEST(Channel,SourceFile,( this->fn_in != NULL ))
+
+/*
+*att++
+*  Name:
+*     SinkFile
+
+*  Purpose:
+*     Output file to which to data should be written.
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     String.
+
+*  Description:
+*     This attribute specifies the name of a file to which the Channel
+*     should write data. If specified it is used in preference to any sink
+*     function specified when the Channel was created.
+*
+*     Assigning a new value to this attribute will cause any previously
+*     opened SinkFile to be closed. The first subsequent call to
+c     astWrite
+f     AST_WRITE
+*     will attempt to open the new file (an error will be reported if the
+*     file cannot be opened), and write data to it. All subsequent call to
+c     astWrite
+f     AST_WRITE
+*     will write data to the new file, until the SinkFile attribute is
+*     cleared or changed.
+*
+*     Clearing the attribute causes any open SinkFile to be closed. All
+*     subsequent data writes will use the sink function specified when the
+*     Channel was created, or will write to standard output if no sink
+*     function was specified.
+*
+*     If no value has been assigned to SinkFile, a null string will be
+*     returned if an attempt is made to get the attribute value.
+
+*  Notes:
+*     - A new SinkFile will over-write any existing file with the same
+*     name unless the existing file is write protected, in which case an
+*     error will be reported.
+*     - Any open SinkFile is closed when the Channel is deleted.
+*     - If the Channel is copied or dumped
+c     (using astCopy or astShow)
+f     (using AST_COPY or AST_SHOW)
+*     the SinkFile attribute is left in a cleared state in the output
+*     Channel (i.e. the value of the SinkFile attribute is not copied).
+
+*  Applicability:
+*     FitsChan
+*        When the FitsChan is destroyed, any headers in the FitsChan will be
+*        written out to the sink file, if one is specified (if not, the
+*        sink function used when the FitsChan was created is used). The
+*        sink file is a text file (not a FITS file) containing one header
+*        per line.
+
+*att--
+*/
+
+/* Clear the SinkFile value by closing any open file, freeing the allocated
+   memory and assigning a NULL pointer. */
+astMAKE_CLEAR(Channel,SinkFile,fn_out,((this->fd_out=(this->fd_out?(fclose(this->fd_out),NULL):NULL)),astFree(this->fn_out)))
+
+/* If the SinkFile value is not set, supply a default in the form of a
+   pointer to the constant string "". */
+astMAKE_GET(Channel,SinkFile,const char *,NULL,( this->fn_out ? this->fn_out : "" ))
+
+/* Set a SinkFile value by closing any open file, freeing any previously
+   allocated memory, allocating new memory, storing the string and saving
+   the pointer to the copy. */
+astMAKE_SET(Channel,SinkFile,const char *,fn_out,((this->fd_out=(this->fd_out?(fclose(this->fd_out),NULL):NULL)),astStore( this->fn_out, value, strlen( value ) + (size_t) 1 )))
+
+/* The SinkFile value is set if the pointer to it is not NULL. */
+astMAKE_TEST(Channel,SinkFile,( this->fn_out != NULL ))
+
+
+/*
+*att++
+*  Name:
+*     Comment
+
+*  Purpose:
+*     Include textual comments in output?
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     Integer (boolean).
+
+*  Description:
+*     This is a boolean attribute which controls whether textual
+*     comments are to be included in the output generated by a
+*     Channel. If included, they will describe what each item of
+*     output represents.
+*
+*     If Comment is non-zero, then comments will be included. If
+*     it is zero, comments will be omitted.
+
+*  Applicability:
+*     Channel
+*        The default value is non-zero for a normal Channel.
+*     FitsChan
+*        The default value is non-zero for a FitsChan.
+*     XmlChan
+*        The default value is zero for an XmlChan.
+
+*att--
+*/
+
+/* This is a boolean value (0 or 1) with a value of -INT_MAX when
+   undefined but yielding a default of one. */
+astMAKE_CLEAR(Channel,Comment,comment,-INT_MAX)
+astMAKE_GET(Channel,Comment,int,0,( this->comment != -INT_MAX ? this->comment : 1 ))
+astMAKE_SET(Channel,Comment,int,comment,( value != 0 ))
+astMAKE_TEST(Channel,Comment,( this->comment != -INT_MAX ))
+
+/*
+*att++
+*  Name:
+*     Full
+
+*  Purpose:
+*     Set level of output detail.
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     Integer.
+
+*  Description:
+*     This attribute is a three-state flag and takes values of -1, 0
+*     or +1.  It controls the amount of information included in the
+*     output generated by a Channel.
+*
+*     If Full is zero, then a modest amount of
+*     non-essential but useful information will be included in the
+*     output. If Full is negative, all non-essential information will
+*     be suppressed to minimise the amount of output, while if it is
+*     positive, the output will include the maximum amount of detailed
+*     information about the Object being written.
+
+*  Applicability:
+*     Channel
+*        The default value is zero for a normal Channel.
+*     FitsChan
+*        The default value is zero for a FitsChan.
+*     XmlChan
+*        The default value is -1 for an XmlChan.
+*     StcsChan
+*        The default value is zero for an StcsChan. Set a positive value
+*        to cause default values to be included in STC-S descriptions.
+
+*  Notes:
+*     - All positive values supplied for this attribute are converted
+*     to +1 and all negative values are converted to -1.
+*att--
+*/
+
+/* This ia a 3-state value (-1, 0 or +1) with a value of -INT_MAX when
+   undefined but yielding a default of zero. */
+astMAKE_CLEAR(Channel,Full,full,-INT_MAX)
+astMAKE_GET(Channel,Full,int,0,( this->full != -INT_MAX ? this->full : 0 ))
+astMAKE_SET(Channel,Full,int,full,( value > 0 ? 1 : ( value < 0 ? -1 : 0 ) ))
+astMAKE_TEST(Channel,Full,( this->full != -INT_MAX ))
+
+/*
+*att++
+*  Name:
+*     Indent
+
+*  Purpose:
+*     Specifies the indentation to use in text produced by a Channel.
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     Integer (boolean).
+
+*  Description:
+*     This attribute controls the indentation within the output text produced by
+f     the AST_WRITE function.
+c     the astWrite function.
+*     It gives the increase in the indentation for each level in the object
+*     heirarchy. If it is set to zero, no indentation will be used. [3]
+
+*  Applicability:
+*     Channel
+*        The default value is zero for a basic Channel.
+*     FitsChan
+*        The FitsChan class ignores this attribute.
+*     StcsChan
+*        The default value for an StcsChan is zero, which causes the entire
+*        STC-S description is written out by a single invocation of the sink
+*        function. The text supplied to the sink function will not contain
+*        any linefeed characters, and each pair of adjacent words will be
+*        separated by a single space. The text may thus be arbitrarily large
+*        and the StcsLength attribute is ignored.
+*
+*        If Indent is non-zero, then the text is written out via multiple
+*        calls to the sink function, each call corresponding to a single
+*        "line" of text (although no line feed characters will be inserted
+*        by AST). The complete STC-S description is broken into lines so that:
+*
+*        - the line length specified by attribute StcsLength is not exceeded
+*        - each sub-phrase (time, space, etc.) starts on a new line
+*        - each argument in a compound spatial region starts on a new line
+*
+*        If this causes a sub-phrase to extend to two or more lines, then the
+*        second and subsequent lines will be indented by three spaces compared
+*        to the first line. In addition, lines within a compound spatial region
+*        will have extra indentation to highlight the nesting produced by the
+*        parentheses. Each new level of nesting will be indented by a further
+*        three spaces.
+f
+f        Note, the default value of zero is unlikely to be appropriate when
+f        an StcsChan is used within Fortran code. In this case, Indent
+f        should usually be set non-zero, and the StcsLength attribute set to
+f        the size of the CHARACTER variable used to
+f        receive the text returned by AST_GETLINE within the sink function.
+f        This avoids the possibility of long lines being truncated invisibly
+f        within AST_GETLINE.
+*     XmlChan
+*        The default value for an XmlChan is zero, which results in no
+*        linefeeds or indentation strings being added to output text.
+*        If any non-zero value is assigned to Indent, then extra linefeed and
+*        space characters will be inserted as necessary to ensure that each
+*        XML tag starts on a new line, and each tag will be indented by
+*        a further 3 spaces to show its depth in the containment hierarchy.
+*att--
+*/
+
+/* This is an integer value with a value of -INT_MAX when undefined,
+   yielding a default of 3. Sub-classes may over-ride theis default. */
+astMAKE_CLEAR(Channel,Indent,indent,-INT_MAX)
+astMAKE_GET(Channel,Indent,int,3,( this->indent != -INT_MAX ? this->indent : 3 ))
+astMAKE_SET(Channel,Indent,int,indent,value)
+astMAKE_TEST(Channel,Indent,( this->indent != -INT_MAX ))
+
+/*
+*att++
+*  Name:
+*     ReportLevel
+
+*  Purpose:
+*     Determines which read/write conditions are reported.
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     Integer.
+
+*  Description:
+*     This attribute determines which, if any, of the conditions that occur
+*     whilst reading or writing an Object should be reported. These
+*     conditions will generate either a fatal error or a warning, as
+*     determined by attribute Strict. ReportLevel can take any of the
+*     following values:
+*
+*     0 - Do not report any conditions.
+*
+*     1 - Report only conditions where significant information content has been
+*     changed. For instance, an unsupported time-scale has been replaced by a
+*     supported near-equivalent time-scale. Another example is if a basic
+*     Channel unexpected encounters data items that may have been introduced
+*     by later versions of AST.
+*
+*     2 - Report the above, and in addition report significant default
+*     values. For instance, if no time-scale was specified when reading an
+*     Object from an external data source, report the default time-scale
+*     that is being used.
+*
+*     3 - Report the above, and in addition report any other potentially
+*     interesting conditions that have no significant effect on the
+*     conversion. For instance, report if a time-scale of "TT"
+*     (terrestrial time) is used in place of "ET" (ephemeris time). This
+*     change has no signficiant effect because ET is the predecessor of,
+*     and is continuous with, TT. Synonyms such as "IAT" and "TAI" are
+*     another example.
+*
+*     The default value is 1. Note, there are many other conditions that
+*     can occur whilst reading or writing an Object that completely
+*     prevent the conversion taking place. Such conditions will always
+*     generate errors, irrespective of the ReportLevel and Strict attributes.
+
+*  Applicability:
+*     Channel
+*        All Channels have this attribute.
+*     FitsChan
+*        All the conditions selected by the FitsChan Warnings attribute are
+*        reported at level 1.
+*att--
+*/
+
+/* This is an integer value with a value of -INT_MAX when undefined,
+   yielding a default of one. */
+astMAKE_CLEAR(Channel,ReportLevel,report_level,-INT_MAX)
+astMAKE_GET(Channel,ReportLevel,int,1,( this->report_level != -INT_MAX ? this->report_level : 1 ))
+astMAKE_SET(Channel,ReportLevel,int,report_level,value)
+astMAKE_TEST(Channel,ReportLevel,( this->report_level != -INT_MAX ))
+
+/*
+*att++
+*  Name:
+*     Skip
+
+*  Purpose:
+*     Skip irrelevant data?
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     Integer (boolean).
+
+*  Description:
+*     This is a boolean attribute which indicates whether the Object
+*     data being read through a Channel are inter-mixed with other,
+*     irrelevant, external data.
+*
+*     If Skip is zero (the default), then the source of input data is
+*     expected to contain descriptions of AST Objects and comments and
+*     nothing else (if anything else is read, an error will
+*     result). If Skip is non-zero, then any non-Object data
+*     encountered between Objects will be ignored and simply skipped
+*     over in order to reach the next Object.
+
+*  Applicability:
+*     Channel
+*        All Channels have this attribute.
+*     FitsChan
+*        The FitsChan class sets the default value of this attribute
+*        to 1, so that all irrelevant FITS headers will normally be
+*        ignored.
+*att--
+*/
+
+/* This ia a boolean value (0 or 1) with a value of -INT_MAX when
+   undefined but yielding a default of zero. */
+astMAKE_CLEAR(Channel,Skip,skip,-INT_MAX)
+astMAKE_GET(Channel,Skip,int,0,( this->skip != -INT_MAX ? this->skip : 0 ))
+astMAKE_SET(Channel,Skip,int,skip,( value != 0 ))
+astMAKE_TEST(Channel,Skip,( this->skip != -INT_MAX ))
+
+/*
+*att++
+*  Name:
+*     Strict
+
+*  Purpose:
+*     Report an error if any unexpeted data items are found?
+
+*  Type:
+*     Public attribute.
+
+*  Synopsis:
+*     Integer (boolean).
+
+*  Description:
+*     This is a boolean attribute which indicates whether a warning
+*     rather than an error should be issed for insignificant conversion
+*     problems. If it is set non-zero, then fatal errors are issued
+*     instead of warnings, resulting in the
+c     AST error status being set.
+f     inherited STATUS variable being set to an error value.
+*     If Strict is zero (the default), then execution continues after minor
+*     conversion problems, and a warning message is added to the Channel
+*     structure. Such messages can be retrieved using the
+c     astWarnings
+f     AST_WARNINGS
+*     function.
+
+*  Notes:
+*     - This attribute was introduced in AST version 5.0. Prior to this
+*     version of AST unexpected data items read by a basic Channel always
+*     caused an error to be reported. So applications linked against
+*     versions of AST prior to version 5.0 may not be able to read Object
+*     descriptions created by later versions of AST, if the Object's class
+*     description has changed.
+
+*  Applicability:
+*     Channel
+*        All Channels have this attribute.
+*att--
+*/
+
+/* This ia a boolean value (0 or 1) with a value of -INT_MAX when
+   undefined but yielding a default of zero. */
+astMAKE_CLEAR(Channel,Strict,strict,-INT_MAX)
+astMAKE_GET(Channel,Strict,int,0,( this->strict != -INT_MAX ? this->strict : 0 ))
+astMAKE_SET(Channel,Strict,int,strict,( value != 0 ))
+astMAKE_TEST(Channel,Strict,( this->strict != -INT_MAX ))
+
+/* Destructor. */
+/* ----------- */
+static void Delete( AstObject *obj, int *status ) {
+/*
+*  Name:
+*     Delete
+
+*  Purpose:
+*     Destructor for Channel objects.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     void Delete( AstObject *obj, int *status )
+
+*  Description:
+*     This function implements the destructor for Channel objects.
+
+*  Parameters:
+*     obj
+*        Pointer to the object to be deleted.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Notes:
+*     This function attempts to execute even if the global error status is
+*     set.
+*/
+
+/* Local Variables: */
+   AstChannel *this;               /* Pointer to Channel */
+
+/* Obtain a pointer to the Channel structure. */
+   this = (AstChannel *) obj;
+
+/* Free memory used to store warnings. */
+   astAddWarning( this, 0, NULL, NULL, status );
+
+/* Close any open input or output files. */
+   if( this->fd_in ) fclose( this->fd_in );
+   if( this->fd_out ) fclose( this->fd_out );
+
+/* Free file name memory. */
+   this->fn_in = astFree( this->fn_in );
+   this->fn_out = astFree( this->fn_out );
+}
+
+/* Copy constructor. */
+/* ----------------- */
+static void Copy( const AstObject *objin, AstObject *objout, int *status ) {
+/*
+*  Name:
+*     Copy
+
+*  Purpose:
+*     Copy constructor for Channel objects.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     void Copy( const AstObject *objin, AstObject *objout, int *status )
+
+*  Description:
+*     This function implements the copy constructor for Channel objects.
+
+*  Parameters:
+*     objin
+*        Pointer to the object to be copied.
+*     objout
+*        Pointer to the object being constructed.
+*     status
+*        Pointer to the inherited status variable.
+
+*  Notes:
+*     -  This constructor makes a deep copy.
+*/
+
+/* Local Variables: */
+   AstChannel *out;                /* Pointer to output Channel */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Obtain pointers to the input and output Channels. */
+   out = (AstChannel *) objout;
+
+/* Just clear any references to the input memory from the output Channel. */
+   out->warnings = NULL;
+   out->nwarn = 0;
+   out->fd_in = NULL;
+   out->fn_in = NULL;
+   out->fd_out = NULL;
+   out->fn_out = NULL;
+}
+
+/* Dump function. */
+/* -------------- */
+static void Dump( AstObject *this_object, AstChannel *channel, int *status ) {
+/*
+*  Name:
+*     Dump
+
+*  Purpose:
+*     Dump function for Channel objects.
+
+*  Type:
+*     Private function.
+
+*  Synopsis:
+*     void Dump( AstObject *this, AstChannel *channel, int *status )
+
+*  Description:
+*     This function implements the Dump function which writes out data
+*     for the Channel class to an output Channel.
+
+*  Parameters:
+*     this
+*        Pointer to the Object whose data are being written.
+*     channel
+*        Pointer to the Channel to which the data are being written.
+*     status
+*        Pointer to the inherited status variable.
+*/
+
+/* Local Variables: */
+   AstChannel *this;             /* Pointer to the Channel structure */
+   const char *comment;          /* Pointer to comment string */
+   int ival;                     /* Integer value */
+   int set;                      /* Attribute value set? */
+
+/* Check the global error status. */
+   if ( !astOK ) return;
+
+/* Obtain a pointer to the Channel structure. */
+   this = (AstChannel *) this_object;
+
+/* Write out values representing the instance variables for the
+   Channel 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. */
+
+/* Indent */
+/* ------------ */
+   set = TestIndent( this, status );
+   ival = set ? GetIndent( this, status ) : astGetIndent( this );
+   astWriteInt( channel, "Indnt", set, 0, ival, "Indentation increment" );
+
+/* ReportLevel. */
+/* ------------ */
+   set = TestReportLevel( this, status );
+   ival = set ? GetReportLevel( this, status ) : astGetReportLevel( this );
+   astWriteInt( channel, "RpLev", set, 0, ival, "Error reporting level" );
+
+/* Skip. */
+/* ----- */
+   set = TestSkip( this, status );
+   ival = set ? GetSkip( this, status ) : astGetSkip( this );
+   astWriteInt( channel, "Skip", set, 0, ival,
+                ival ? "Ignore data between Objects" :
+                       "No data allowed between Objects" );
+
+/* Strict. */
+/* ------- */
+   set = TestStrict( this, status );
+   ival = set ? GetStrict( this, status ) : astGetStrict( this );
+   astWriteInt( channel, "Strict", set, 0, ival,
+                ival ? "Report errors insead of warnings" :
+                       "Report warnings instead of errors" );
+
+/* Full. */
+/* ----- */
+   set = TestFull( this, status );
+   ival = set ? GetFull( this, status ) : astGetFull( this );
+   if ( ival < 0 ) {
+      comment = "Suppress non-essential output";
+   }else if ( ival == 0 ) {
+      comment = "Output standard information";
+   } else {
+      comment = "Output maximum information";
+   }
+   astWriteInt( channel, "Full", set, 0, ival, comment );
+
+/* Comment. */
+/* -------- */
+   set = TestComment( this, status );
+   ival = set ? GetComment( this, status ) : astGetComment( this );
+   astWriteInt( channel, "Comm", set, 0, ival,
+                ival ? "Display comments" :
+                       "Omit comments" );
+}
+
+/* Standard class functions. */
+/* ========================= */
+/* Implement the astIsAChannel and astCheckChannel functions using the
+   macros defined for this purpose in the "object.h" header file. */
+astMAKE_ISA(Channel,Object)
+astMAKE_CHECK(Channel)
+
+AstChannel *astChannel_( const char *(* source)( void ),
+                         void (* sink)( const char * ),
+                         const char *options, int *status, ...) {
+/*
+*+
+*  Name:
+*     astChannel
+
+*  Purpose:
+*     Create a Channel.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     AstChannel *astChannel( const char *(* source)( void ),
+*                             void (* sink)( const char * ),
+*                             const char *options, ..., int *status )
+
+*  Class Membership:
+*     Channel constructor.
+
+*  Description:
+*     This function creates a new Channel and optionally initialises
+*     its attributes.
+*
+*     A Channel implements low-level input/output for the AST library.
+*     Writing an Object to a Channel (using astWrite) will generate a
+*     textual representation of that Object, and reading from a
+*     Channel (using astRead) will create a new Object from its
+*     textual representation.
+*
+*     Normally, when you use a Channel, you should provide "source"
+*     and "sink" functions which connect it to an external data store
+*     by reading and writing the resulting text. By default, however,
+*     a Channel will read from standard input and write to standard
+*     output.
+
+*  Parameters:
+*     source
+*        Pointer to a "source" function that takes no arguments and
+*        returns a pointer to a null-terminated string.
+*
+*        This function will be used by the Channel to obtain lines of
+*        input text. On each invocation, it should return a pointer to
+*        the next input line read from some external data store, and a
+*        NULL pointer when there are no more lines to read.
+*
+*        If "source" is NULL, the Channel will read from standard
+*        input instead.
+*     sink
+*        Pointer to a "sink" function that takes a pointer to a
+*        null-terminated string as an argument and returns void.
+*
+*        This function will be used by the Channel to deliver lines of
+*        output text. On each invocation, it should deliver the
+*        contents of the string supplied to some external data store.
+*
+*        If "sink" is NULL, the Channel will write to standard output
+*        instead.
+*     options
+*        Pointer to a null-terminated string containing an optional
+*        comma-separated list of attribute assignments to be used for
+*        initialising the new Channel. The syntax used is identical to
+*        that for the astSet function and may include "printf" format
+*        specifiers identified by "%" symbols in the normal way.
+*     status
+*        Pointer to the inherited status variable.
+*     ...
+*        If the "options" string contains "%" format specifiers, then
+*        an optional list of additional arguments may follow it in
+*        order to supply values to be substituted for these
+*        specifiers. The rules for supplying these are identical to
+*        those for the astSet function (and for the C "printf"
+*        function).
+
+*  Returned Value:
+*     astChannel()
+*        A pointer to the new Channel.
+
+*  Notes:
+*     - A NULL pointer value will be returned if this function is
+*     invoked with the global error status set, or if it should fail
+*     for any reason.
+*-
+
+*  Implementation Notes:
+*     - This function implements the basic Channel constructor which
+*     is available via the protected interface to the Channel class.
+*     A public interface is provided by the astChannelId_ function.
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Pointer to thread-specific global data */
+   AstChannel *new;              /* Pointer to new Channel */
+   va_list args;                 /* Variable argument list */
+
+/* Get a pointer to the thread specific global data structure. */
+   astGET_GLOBALS(NULL);
+
+/* Check the global status. */
+   if ( !astOK ) return NULL;
+
+/* Initialise the Channel, allocating memory and initialising the
+   virtual function table as well if necessary. Supply pointers to
+   (local) wrapper functions that can invoke the source and sink
+   functions with appropriate arguments for the C language. */
+   new = astInitChannel( NULL, sizeof( AstChannel ), !class_init, &class_vtab,
+                         "Channel", source, SourceWrap, sink, SinkWrap );
+
+/* If successful, note that the virtual function table has been
+   initialised. */
+   if ( astOK ) {
+      class_init = 1;
+
+/* Obtain the variable argument list and pass it along with the
+   options string to the astVSet method to initialise the new
+   Channel's attributes. */
+      va_start( args, status );
+      astVSet( new, options, NULL, args );
+      va_end( args );
+
+/* If an error occurred, clean up by deleting the new object. */
+      if ( !astOK ) new = astDelete( new );
+   }
+
+/* Return a pointer to the new Channel. */
+   return new;
+}
+
+AstChannel *astChannelId_( const char *(* source)( void ),
+                           void (* sink)( const char * ),
+                           const char *options, ... ) {
+/*
+*++
+*  Name:
+c     astChannel
+f     AST_CHANNEL
+
+*  Purpose:
+*     Create a Channel.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+c     #include "channel.h"
+c     AstChannel *astChannel( const char *(* source)( void ),
+c                             void (* sink)( const char * ),
+c                             const char *options, ... )
+f     RESULT = AST_CHANNEL( SOURCE, SINK, OPTIONS, STATUS )
+
+*  Class Membership:
+*     Channel constructor.
+
+*  Description:
+*     This function creates a new Channel and optionally initialises
+*     its attributes.
+*
+*     A Channel implements low-level input/output for the AST library.
+c     Writing an Object to a Channel (using astWrite) will generate a
+f     Writing an Object to a Channel (using AST_WRITE) will generate a
+*     textual representation of that Object, and reading from a
+c     Channel (using astRead) will create a new Object from its
+f     Channel (using AST_READ) will create a new Object from its
+*     textual representation.
+*
+*     Normally, when you use a Channel, you should provide "source"
+c     and "sink" functions which connect it to an external data store
+f     and "sink" routines which connect it to an external data store
+*     by reading and writing the resulting text. By default, however,
+*     a Channel will read from standard input and write to standard
+*     output. Alternatively, a Channel can be told to read or write from
+*     specific text files using the SinkFile and SourceFile attributes,
+*     in which case no sink or source function need be supplied.
+
+*  Parameters:
+c     source
+f     SOURCE = SUBROUTINE (Given)
+c        Pointer to a source function that takes no arguments and
+c        returns a pointer to a null-terminated string.  If no value
+c        has been set for the SourceFile attribute, this function
+c        will be used by the Channel to obtain lines of input text. On
+c        each invocation, it should return a pointer to the next input
+c        line read from some external data store, and a NULL pointer
+c        when there are no more lines to read.
+c
+c        If "source" is NULL and no value has been set for the SourceFile
+c        attribute, the Channel will read from standard input instead.
+f        A source routine, which is a subroutine which takes a single
+f        integer error status argument.   If no value has been set
+f        for the SourceFile attribute, this routine will be used by
+f        the Channel to obtain lines of input text. On each
+f        invocation, it should read the next input line from some
+f        external data store, and then return the resulting text to
+f        the AST library by calling AST_PUTLINE. It should supply a
+f        negative line length when there are no more lines to read.
+f        If an error occurs, it should set its own error status
+f        argument to an error value before returning.
+f
+f        If the null routine AST_NULL is suppied as the SOURCE value,
+f        and no value has been set for the SourceFile attribute,
+f        the Channel will read from standard input instead.
+c     sink
+f     SINK = SUBROUTINE (Given)
+c        Pointer to a sink function that takes a pointer to a
+c        null-terminated string as an argument and returns void.
+c        If no value has been set for the SinkFile attribute, this
+c        function will be used by the Channel to deliver lines of
+c        output text. On each invocation, it should deliver the
+c        contents of the string supplied to some external data store.
+c
+c        If "sink" is NULL, and no value has been set for the SinkFile
+c        attribute, the Channel will write to standard output instead.
+f        A sink routine, which is a subroutine which takes a single
+f        integer error status argument.  If no value has been set
+f        for the SinkFile attribute, this routine will be used by
+f        the Channel to deliver lines of output text. On each
+f        invocation, it should obtain the next output line from the
+f        AST library by calling AST_GETLINE, and then deliver the
+f        resulting text to some external data store.  If an error
+f        occurs, it should set its own error status argument to an
+f        error value before returning.
+f
+f        If the null routine AST_NULL is suppied as the SINK value,
+f        and no value has been set for the SinkFile attribute,
+f        the Channel will write to standard output instead.
+c     options
+f     OPTIONS = CHARACTER * ( * ) (Given)
+c        Pointer to a null-terminated string containing an optional
+c        comma-separated list of attribute assignments to be used for
+c        initialising the new Channel. The syntax used is identical to
+c        that for the astSet function and may include "printf" format
+c        specifiers identified by "%" symbols in the normal way.
+f        A character string containing an optional comma-separated
+f        list of attribute assignments to be used for initialising the
+f        new Channel. The syntax used is identical to that for the
+f        AST_SET routine.
+c     ...
+c        If the "options" string contains "%" format specifiers, then
+c        an optional list of additional arguments may follow it in
+c        order to supply values to be substituted for these
+c        specifiers. The rules for supplying these are identical to
+c        those for the astSet function (and for the C "printf"
+c        function).
+f     STATUS = INTEGER (Given and Returned)
+f        The global status.
+
+*  Returned Value:
+c     astChannel()
+f     AST_CHANNEL = INTEGER
+*        A pointer to the new Channel.
+
+*  Notes:
+c     - Application code can pass arbitrary data (such as file
+c     descriptors, etc) to source and sink functions using the
+c     astPutChannelData function. The source or sink function should use
+c     the astChannelData macro to retrieve this data.
+f     - The names of the routines supplied for the SOURCE and SINK
+f     arguments should appear in EXTERNAL statements in the Fortran
+f     routine which invokes AST_CHANNEL. However, this is not generally
+f     necessary for the null routine AST_NULL (so long as the AST_PAR
+f     include file has been used).
+*     - 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.
+f     - Note that the null routine AST_NULL (one underscore) is
+f     different to AST__NULL (two underscores), which is the null Object
+f     pointer.
+*--
+
+*  Implementation Notes:
+*     - This function implements the external (public) interface to
+*     the astChannel constructor function. It returns an ID value
+*     (instead of a true C pointer) to external users, and must be
+*     provided because astChannel_ has a variable argument list which
+*     cannot be encapsulated in a macro (where this conversion would
+*     otherwise occur).
+*     - The variable argument list also prevents this function from
+*     invoking astChanel_ directly, so it must be a re-implementation
+*     of it in all respects, except for the final conversion of the
+*     result to an ID value.
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Pointer to thread-specific global data */
+   AstChannel *new;              /* Pointer to new Channel */
+   va_list args;                 /* Variable argument list */
+
+   int *status;                  /* Pointer to inherited status value */
+
+/* Get a pointer to the inherited status value. */
+   status = astGetStatusPtr;
+
+/* Get a pointer to the thread specific global data structure. */
+   astGET_GLOBALS(NULL);
+
+/* Check the global status. */
+   if ( !astOK ) return NULL;
+
+/* Initialise the Channel, allocating memory and initialising the
+   virtual function table as well if necessary. Supply pointers to
+   (local) wrapper functions that can invoke the source and sink
+   functions with appropriate arguments for the C language. */
+   new = astInitChannel( NULL, sizeof( AstChannel ), !class_init, &class_vtab,
+                         "Channel", source, SourceWrap, sink, SinkWrap );
+
+/* If successful, note that the virtual function table has been
+   initialised. */
+   if ( astOK ) {
+      class_init = 1;
+
+/* Obtain the variable argument list and pass it along with the
+   options string to the astVSet method to initialise the new
+   Channel's attributes. */
+      va_start( args, options );
+      astVSet( new, options, NULL, args );
+      va_end( args );
+
+/* If an error occurred, clean up by deleting the new object. */
+      if ( !astOK ) new = astDelete( new );
+   }
+
+/* Return an ID value for the new Channel. */
+   return astMakeId( new );
+}
+
+AstChannel *astChannelForId_( const char *(* source)( void ),
+                              char *(* source_wrap)( const char *(*)( void ), int * ),
+                              void (* sink)( const char * ),
+                              void (* sink_wrap)( void (*)( const char * ),
+                                                  const char *, int * ),
+                              const char *options, ... ) {
+/*
+*+
+*  Name:
+*     astChannelFor
+
+*  Purpose:
+*     Initialise a Channel from a foreign language interface.
+
+*  Type:
+*     Public function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     AstChannel *astChannelFor( const char *(* source)( void ),
+*                                char *(* source_wrap)( const char *(*)
+*                                                       ( void ), int * ),
+*                                void (* sink)( const char * ),
+*                                void (* sink_wrap)( void (*)( const char * ),
+*                                                    const char *, int * ),
+*                                const char *options, ... )
+
+*  Class Membership:
+*     Channel constructor.
+
+*  Description:
+*     This function creates a new Channel from a foreign language
+*     interface and optionally initialises its attributes.
+*
+*     A Channel implements low-level input/output for the AST library.
+*     Writing an Object to a Channel (using astWrite) will generate a
+*     textual representation of that Object, and reading from a
+*     Channel (using astRead) will create a new Object from its
+*     textual representation.
+*
+*     Normally, when you use a Channel, you should provide "source"
+*     and "sink" functions which connect it to an external data store
+*     by reading and writing the resulting text. This function also
+*     requires you to provide "wrapper" functions which will invoke
+*     the source and sink functions. By default, however, a Channel
+*     will read from standard input and write to standard output.
+
+*  Parameters:
+*     source
+*        Pointer to a "source" function which will be used to obtain
+*        lines of input text. Generally, this will be obtained by
+*        casting a pointer to a source function which is compatible
+*        with the "source_wrap" wrapper function (below). The pointer
+*        should later be cast back to its original type by the
+*        "source_wrap" function before the function is invoked.
+*
+*        If "source" is NULL, the Channel will read from standard
+*        input instead.
+*     source_wrap
+*        Pointer to a function which can be used to invoke the
+*        "source" function supplied (above). This wrapper function is
+*        necessary in order to hide variations in the nature of the
+*        source function, such as may arise when it is supplied by a
+*        foreign (non-C) language interface.
+*
+*        The single parameter of the "source_wrap" function is a
+*        pointer to the "source" function, and it should cast this
+*        function pointer (as necessary) and invoke the function with
+*        appropriate arguments to obtain the next line of input
+*        text. The "source_wrap" function should then return a pointer
+*        to a dynamically allocated, null terminated string containing
+*        the text that was read. The string will be freed (using
+*        astFree) when no longer required and the "source_wrap"
+*        function need not concern itself with this. A NULL pointer
+*        should be returned if there is no more input to read.
+*
+*        If "source_wrap" is NULL, the Channel will read from standard
+*        input instead.
+*     sink
+*        Pointer to a "sink" function which will be used to deliver
+*        lines of output text. Generally, this will be obtained by
+*        casting a pointer to a sink function which is compatible with
+*        the "sink_wrap" wrapper function (below). The pointer should
+*        later be cast back to its original type by the "sink_wrap"
+*        function before the function is invoked.
+*
+*        If "sink" is NULL, the Channel will write to standard output
+*        instead.
+*     sink_wrap
+*        Pointer to a function which can be used to invoke the "sink"
+*        function supplied (above). This wrapper function is necessary
+*        in order to hide variations in the nature of the sink
+*        function, such as may arise when it is supplied by a foreign
+*        (non-C) language interface.
+*
+*        The first parameter of the "sink_wrap" function is a pointer
+*        to the "sink" function, and the second parameter is a pointer
+*        to a const, null-terminated character string containing the
+*        text to be written.  The "sink_wrap" function should cast the
+*        "sink" function pointer (as necessary) and invoke the
+*        function with appropriate arguments to deliver the line of
+*        output text. The "sink_wrap" function then returns void.
+*
+*        If "sink_wrap" is NULL, the Channel will write to standard
+*        output instead.
+*     options
+*        Pointer to a null-terminated string containing an optional
+*        comma-separated list of attribute assignments to be used for
+*        initialising the new Channel. The syntax used is identical to
+*        that for the astSet function and may include "printf" format
+*        specifiers identified by "%" symbols in the normal way.
+*     ...
+*        If the "options" string contains "%" format specifiers, then
+*        an optional list of additional arguments may follow it in
+*        order to supply values to be substituted for these
+*        specifiers. The rules for supplying these are identical to
+*        those for the astSet function (and for the C "printf"
+*        function).
+
+*  Returned Value:
+*     astChannelFor()
+*        A pointer to the new Channel.
+
+*  Notes:
+*     - A null Object pointer (AST__NULL) will be returned if this
+*     function is invoked with the global error status set, or if it
+*     should fail for any reason.
+*     - This function is only available through the public interface
+*     to the Channel class (not the protected interface) and is
+*     intended solely for use in implementing foreign language
+*     interfaces to this class.
+*-
+
+*  Implememtation Notes:
+*     - This function behaves exactly like astChannelId_, in that it
+*     returns ID values and not true C pointers, but it has two
+*     additional arguments. These are pointers to the "wrapper
+*     functions" which are needed to accommodate foreign language
+*     interfaces.
+*/
+
+/* Local Variables: */
+   astDECLARE_GLOBALS            /* Declare the thread specific global data */
+   AstChannel *new;              /* Pointer to new Channel */
+   va_list args;                 /* Variable argument list */
+   int *status;                  /* Pointer to inherited status value */
+
+/* Get a pointer to the inherited status value. */
+   status = astGetStatusPtr;
+
+/* Check the global status. */
+   if ( !astOK ) return NULL;
+
+/* Get a pointer to the thread specific global data structure. */
+   astGET_GLOBALS(NULL);
+
+/* Initialise the Channel, allocating memory and initialising the
+   virtual function table as well if necessary. */
+   new = astInitChannel( NULL, sizeof( AstChannel ), !class_init, &class_vtab,
+                         "Channel", source, source_wrap, sink, sink_wrap );
+
+/* If successful, note that the virtual function table has been
+   initialised. */
+   if ( astOK ) {
+      class_init = 1;
+
+/* Obtain the variable argument list and pass it along with the
+   options string to the astVSet method to initialise the new
+   Channel's attributes. */
+      va_start( args, options );
+      astVSet( new, options, NULL, args );
+      va_end( args );
+
+/* If an error occurred, clean up by deleting the new object. */
+      if ( !astOK ) new = astDelete( new );
+   }
+
+/* Return an ID value for the new Channel. */
+   return astMakeId( new );
+}
+
+AstChannel *astLoadChannel_( void *mem, size_t size,
+                             AstChannelVtab *vtab, const char *name,
+                             AstChannel *channel, int *status ) {
+/*
+*+
+*  Name:
+*     astLoadChannel
+
+*  Purpose:
+*     Load a Channel.
+
+*  Type:
+*     Protected function.
+
+*  Synopsis:
+*     #include "channel.h"
+*     AstChannel *astLoadChannel( void *mem, size_t size,
+*                                 AstChannelVtab *vtab, const char *name,
+*                                 AstChannel *channel )
+
+*  Class Membership:
+*     Channel loader.
+
+*  Description:
+*     This function is provided to load a new Channel using data read
+*     from a Channel. It first loads the data used by the parent class
+*     (which allocates memory if necessary) and then initialises a
+*     Channel structure in this memory, using data read from the input
+*     Channel.
+*
+*     If the "init" flag is set, it also initialises the contents of a
+*     virtual function table for a Channel at the start of the memory
+*     passed via the "vtab" parameter.
+
+
+*  Parameters:
+*     mem
+*        A pointer to the memory into which the Channel is to be
+*        loaded.  This must be of sufficient size to accommodate the
+*        Channel data (sizeof(Channel)) 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 Channel (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 Channel 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(AstChannel) is used instead.
+*     vtab
+*        Pointer to the start of the virtual function table to be
+*        associated with the new Channel. If this is NULL, a pointer
+*        to the (static) virtual function table for the Channel 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 "Channel" is used instead.
+
+*  Returned Value:
+*     A pointer to the new Channel.
+
+*  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            /* Pointer to thread-specific global data */
+   AstChannel *new;              /* Pointer to the new Channel */
+
+/* Initialise. */
+   new = NULL;
+
+/* Check the global error status. */
+   if ( !astOK ) return new;
+
+/* Get a pointer to the thread specific global data structure. */
+   astGET_GLOBALS(channel);
+
+/* If a NULL virtual function table has been supplied, then this is
+   the first loader to be invoked for this Channel. In this case the
+   Channel belongs to this class, so supply appropriate values to be
+   passed to the parent class loader (and its parent, etc.). */
+   if ( !vtab ) {
+      size = sizeof( AstChannel );
+      vtab = &class_vtab;
+      name = "Channel";
+
+/* If required, initialise the virtual function table for this class. */
+      if ( !class_init ) {
+         astInitChannelVtab( vtab, name );
+         class_init = 1;
+      }
+   }
+
+/* Invoke the parent class loader to load data for all the ancestral
+   classes of the current one, returning a pointer to the resulting
+   partly-built Channel. */
+   new = astLoadObject( mem, size, (AstObjectVtab *) vtab, name,
+                        channel );
+
+   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, "Channel" );
+
+/* Set the pointers to the source and sink functions, and their
+   wrapper functions, to NULL (we cannot restore these since they
+   refer to process-specific addresses). */
+      new->source = NULL;
+      new->source_wrap = NULL;
+      new->sink = NULL;
+      new->sink_wrap = NULL;
+
+/* We do not have any data to pass to the source and sink functions. */
+      new->data = NULL;
+
+/* No warnings yet. */
+      new->warnings = NULL;
+      new->nwarn = 0;
+
+/* Indicate no input or output files have been associated with the
+   Channel. */
+      new->fd_in = NULL;
+      new->fn_in = NULL;
+      new->fd_out = NULL;
+      new->fn_out = NULL;
+
+/* Now read each individual data item from this list and use it to
+   initialise the appropriate instance variable(s) for this class. */
+
+/* In the case of attributes, we first read the "raw" input value,
+   supplying the "unset" value as the default. If a "set" value is
+   obtained, we then use the appropriate (private) Set... member
+   function to validate and set the value properly. */
+
+/* Indent. */
+/* ------- */
+      new->indent = astReadInt( channel, "indnt", -INT_MAX );
+      if ( TestIndent( new, status ) ) SetIndent( new, new->indent, status );
+
+/* ReportLevel. */
+/* ------------ */
+      new->report_level = astReadInt( channel, "rplev", -INT_MAX );
+      if ( TestReportLevel( new, status ) ) SetReportLevel( new,
+                                                            new->report_level,
+                                                            status );
+
+/* Skip. */
+/* ----- */
+      new->skip = astReadInt( channel, "skip", -INT_MAX );
+      if ( TestSkip( new, status ) ) SetSkip( new, new->skip, status );
+
+/* Strict. */
+/* ------- */
+      new->strict = astReadInt( channel, "strict", -INT_MAX );
+      if ( TestStrict( new, status ) ) SetStrict( new, new->strict, status );
+
+/* Full. */
+/* ----- */
+      new->full = astReadInt( channel, "full", -INT_MAX );
+      if ( TestFull( new, status ) ) SetFull( new, new->full, status );
+
+/* Comment. */
+/* -------- */
+      new->comment = astReadInt( channel, "comm", -INT_MAX );
+      if ( TestComment( new, status ) ) SetComment( new, new->comment, status );
+
+/* If an error occurred, clean up by deleting the new Channel. */
+      if ( !astOK ) new = astDelete( new );
+   }
+
+/* Return the new Channel 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 astGetNextData_( AstChannel *this, int begin, char **name, char **val, int *status ) {
+   *name = NULL;
+   *val = NULL;
+   if ( !astOK ) return;
+   (**astMEMBER(this,Channel,GetNextData))( this, begin, name, val, status );
+}
+char *astGetNextText_( AstChannel *this, int *status ) {
+   if ( !astOK ) return NULL;
+   return (**astMEMBER(this,Channel,GetNextText))( this, status );
+}
+void astPutNextText_( AstChannel *this, const char *line, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Channel,PutNextText))( this, line, status );
+}
+AstObject *astRead_( AstChannel *this, int *status ) {
+   if ( !astOK ) return NULL;
+   astAddWarning( this, 0, NULL, NULL, status );
+   return (**astMEMBER(this,Channel,Read))( this, status );
+}
+void astReadClassData_( AstChannel *this, const char *class, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Channel,ReadClassData))( this, class, status );
+}
+double astReadDouble_( AstChannel *this, const char *name, double def, int *status ) {
+   if ( !astOK ) return 0.0;
+   return (**astMEMBER(this,Channel,ReadDouble))( this, name, def, status );
+}
+int astReadInt_( AstChannel *this, const char *name, int def, int *status ) {
+   if ( !astOK ) return 0;
+   return (**astMEMBER(this,Channel,ReadInt))( this, name, def, status );
+}
+AstObject *astReadObject_( AstChannel *this, const char *name,
+                           AstObject *def, int *status ) {
+   if ( !astOK ) return NULL;
+   return (**astMEMBER(this,Channel,ReadObject))( this, name, def, status );
+}
+char *astReadString_( AstChannel *this, const char *name, const char *def, int *status ) {
+   if ( !astOK ) return NULL;
+   return (**astMEMBER(this,Channel,ReadString))( this, name, def, status );
+}
+void astWriteBegin_( AstChannel *this, const char *class,
+                     const char *comment, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Channel,WriteBegin))( this, class, comment, status );
+}
+void astWriteDouble_( AstChannel *this, const char *name, int set, int helpful,
+                      double value, const char *comment, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Channel,WriteDouble))( this, name, set, helpful, value,
+                                            comment, status );
+}
+void astWriteEnd_( AstChannel *this, const char *class, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Channel,WriteEnd))( this, class, status );
+}
+void astWriteInt_( AstChannel *this, const char *name, int set, int helpful,
+                   int value, const char *comment, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Channel,WriteInt))( this, name, set, helpful, value,
+                                         comment, status );
+}
+void astWriteIsA_( AstChannel *this, const char *class, const char *comment, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Channel,WriteIsA))( this, class, comment, status );
+}
+void astWriteString_( AstChannel *this, const char *name, int set, int helpful,
+                      const char *value, const char *comment, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Channel,WriteString))( this, name, set, helpful, value,
+                                            comment, status );
+}
+void astPutChannelData_( AstChannel *this, void *data, int *status ) {
+   if ( !astOK ) return;
+   (**astMEMBER(this,Channel,PutChannelData))( this, data, status );
+}
+
+AstKeyMap *astWarnings_( AstChannel *this, int *status ){
+   if( !astOK ) return NULL;
+   return (**astMEMBER(this,Channel,Warnings))( this, status );
+}
+
+/* Because of the variable argument list, we need to work a bit harder on
+   astAddWarning. Functions that provide implementations of the
+   astAddWarning method recieve the fully expanded message and so do not
+   need a variable argument list. */
+
+void astAddWarning_( void *this_void, int level, const char *fmt,
+                     const char *method, int *status, ... ) {
+   AstChannel *this;
+   char buff[ 201 ];
+   va_list args;
+   int nc;
+
+   this = astCheckChannel( this_void );
+
+   if( fmt ) {
+      if( astOK ) {
+         va_start( args, status );
+         nc = vsprintf( buff, fmt, args );
+         va_end( args );
+         if( nc > 200 ) {
+            astError( AST__INTER, "astAddWarning(%s): Message buffer size "
+                      "exceeded (internal AST programming error).",
+                      status, astGetClass( this ) );
+         } else {
+            (**astMEMBER(this,Channel,AddWarning))( this, level, buff, method, status );
+         }
+      }
+   } else {
+      (**astMEMBER(this,Channel,AddWarning))( this, level, NULL, method, status );
+   }
+}
+
+/* Count the number of times astWrite is invoked (excluding invocations
+   made from within the astWriteObject method - see below). The count is
+   done here so that invocations of astWrite within a sub-class will be
+   included. */
+int astWrite_( AstChannel *this, AstObject *object, int *status ) {
+   astDECLARE_GLOBALS
+   if ( !astOK ) return 0;
+   astGET_GLOBALS(this);
+   nwrite_invoc++;
+   astAddWarning( this, 0, NULL, NULL, status );
+   return (**astMEMBER(this,Channel,Write))( this, object, status );
+}
+
+/* We do not want to count invocations of astWrite made from within the
+   astWriteObject method. So decrement the number of invocations first
+   (this assumes that each invocation of astWriteObject will only invoke
+   astWrite once). */
+void astWriteObject_( AstChannel *this, const char *name, int set,
+                      int helpful, AstObject *value, const char *comment, int *status ) {
+   astDECLARE_GLOBALS
+   if ( !astOK ) return;
+   astGET_GLOBALS(this);
+   nwrite_invoc--;
+   (**astMEMBER(this,Channel,WriteObject))( this, name, set, helpful, value,
+                                            comment, status );
+}
+
+
+
+
+