---

sds.h

/*
 * Name: filter.m4
 *
 * Description:
 *     DOXYGEN Input file filter for DRAMA source files.
 *
 *     This file must be complatible with both Solaris and GNU m4.  All
 *     unused macros are deleted and this comment must end up as a C/C++
 *     compatible comment which is not picked up by DOXYGEN.
 * 
 * Synopsis:
 *    DCF(func)  => Produces a link to a DRAMA C source file func.html 
 *                   in ../routines.
 *     DDL(link,text) => Produce a link to ../link.html, specified link text.
 *
 * Language: m4 macro. 
 *
 * Author: Tony Farrell, AAO.
 *
 * "@(#) $Id: ACMM:DramaHtml/filter.m4,v 3.24 03-Nov-2009 09:07:29+11 tjf $"
 *
 * History:
 *     10-Nov-2004 - TJF - Original Version.
 */



/*  SDS Include file                                         */
/*                                                           */
/*  Jeremy Bailey      1998  Jul 13                          */
/*                                                           */
/*     @(#) $Id: ACMM:sds/sds.h,v 3.48 02-Nov-2009 14:50:59+11 tjf $                        */
/*                                                           */
/*                                                           */
/*                                                           */

/*
 * This file now uses DOXYGEN comments to generate the C++ web pages.
 * m4 macros of the form @htmlonly <a href="../routines/function.html">function()</a>@endhtmlonly are used in the comments
 * to refer to DRAMA C function documention (see DramaHtml/Makefile,
 * DramaHtml/doxygen.config and DramaHtml/filter.m4 for detials)
 */
#ifndef _SDS_INCLUDE_
#define _SDS_INCLUDE_ 1

#include "sdsport.h"
#include "status.h"

#ifdef __cplusplus
extern "C" {
#endif

#define SDS_VERSION 100

/*    Status codes  */

#include "sds_err.h"

/*    Type codes   */

#define SDS_STRUCT   0              /*  Structure   */
#define SDS_CHAR     1              /*  Character   */
#define SDS_UBYTE    2              /*  Unsigned byte */
#define SDS_BYTE     3              /*  byte          */
#define SDS_USHORT   4              /*  Unsigned short */
#define SDS_SHORT    5              /*  short  */
#define SDS_UINT     6              /*  Unsigned int  */
#define SDS_INT      7              /*  int  */
#define SDS_FLOAT    8              /*  float  */
#define SDS_DOUBLE   9              /*  double  */
#define SDS_I64      11             /*  Int 64  */
#define SDS_UI64     12             /*  Unsigned Int 64  */
#define SDS_C_MAXCODE SDS_UI64      /* The maximum code value */

/*  Name length  */

#define SDS_C_NAMELEN 16

#define SDS_C_MAXARRAYDIMS 7

#define SDS_WATCH_EVENT_FREE        0
#define SDS_WATCH_EVENT_DELETE      1
#define SDS_WATCH_EVENT_READFREE    2
#define SDS_WATCH_EVENT_NEW         3
#define SDS_WATCH_EVENT_COPY        4
#define SDS_WATCH_EVENT_INSERT      5
#define SDS_WATCH_EVENT_INSERT_CELL 6
#define SDS_WATCH_EVENT_EXTRACT     7
#define SDS_WATCH_EVENT_RESIZE      8
#define SDS_WATCH_EVENT_NEWID       9

typedef long  SdsIdType;

typedef long  SdsCodeType;

typedef void (*SdsWatchRoutineType)(SdsIdType, void *, int reserved);

SDSEXTERN void SdsSetWatch(SdsIdType id,
                           SdsWatchRoutineType watchRoutine,
                           void * clientData,
                           SdsIdType *oldId,
                           SdsWatchRoutineType *oldWatchRoutine,
                           void ** oldClientData,
                           StatusType * SDSCONST status);

SDSEXTERN void SdsCreate(SDSCONST char *name, long nextra, SDSCONST char *extra, 
                SdsIdType *id, StatusType * SDSCONST status);

SDSEXTERN void SdsInfo(SdsIdType id,char *name, SdsCodeType *code, long *ndims, 
               unsigned long* dims, StatusType * SDSCONST status);

SDSEXTERN void SdsNew(SdsIdType parent_id, SDSCONST char *name, long nextra, 
               SDSCONST char *extra, SdsCodeType code, long ndims,  
               SDSCONST unsigned long *dims, 
               SdsIdType *id, StatusType * SDSCONST status);

SDSEXTERN int SdsIsDefined(SdsIdType parent_id, StatusType * SDSCONST status);

SDSEXTERN void SdsIndex(SdsIdType parent_id, long index, SdsIdType *id, StatusType * SDSCONST status);

SDSEXTERN void SdsFind(SdsIdType parent_id, SDSCONST char *name, SdsIdType *id, StatusType * SDSCONST status);

SDSEXTERN void SdsFindByPath(SdsIdType parent_id, SDSCONST char *name, SdsIdType *id, StatusType * SDSCONST status);

SDSEXTERN void SdsPointer(SdsIdType id, void **data, unsigned long *length, StatusType * SDSCONST status);

SDSEXTERN void SdsGet(SdsIdType id, unsigned long length, unsigned long offset, 
        void *data, unsigned long *actlen, StatusType * SDSCONST status);

SDSEXTERN void SdsPut(SdsIdType id, unsigned long length, unsigned long offset, 
                SDSCONST void *data,  StatusType * SDSCONST status);


SDSEXTERN void SdsCell(SdsIdType array_id, long nindices, 
                SDSCONST unsigned long *indices, 
                SdsIdType *id, StatusType * SDSCONST status);


SDSEXTERN void SdsInsertCell(SdsIdType array_id, long nindices, 
                SDSCONST unsigned long *indices, 
                SdsIdType id, StatusType * SDSCONST status);

SDSEXTERN void SdsDelete(SdsIdType id, StatusType * SDSCONST status);

SDSEXTERN void SdsSize(SdsIdType id, unsigned long *bytes, StatusType * SDSCONST status);
SDSEXTERN void SdsExport(SdsIdType id, unsigned long length, void *data, StatusType * SDSCONST status);

SDSEXTERN void SdsImport(SDSCONST void *data, SdsIdType *id, 
                        StatusType * SDSCONST status);

SDSEXTERN void SdsAccess(void *data, SdsIdType *id, StatusType * SDSCONST status);

SDSEXTERN void SdsExtract(SdsIdType id, StatusType * SDSCONST status);

SDSEXTERN void SdsInsert(SdsIdType parent_id, SdsIdType id, StatusType * SDSCONST status);

SDSEXTERN void SdsCopy(SdsIdType id, SdsIdType *copy_id, StatusType * SDSCONST status);

SDSEXTERN void SdsResize(SdsIdType id, long ndims, SDSCONST unsigned long *dims,
                 StatusType * SDSCONST status);

SDSEXTERN void SdsRename(SdsIdType id, SDSCONST char* name, StatusType * SDSCONST status);

SDSEXTERN void SdsGetExtra(SdsIdType id, long length, char* extra, unsigned long *actlen, 
StatusType * SDSCONST status);

SDSEXTERN void SdsPutExtra(SdsIdType id, long length, SDSCONST char *extra, 
                                        StatusType * SDSCONST status);
    
SDSEXTERN void SdsExportDefined(SdsIdType id, unsigned long length, void *data, StatusType * SDSCONST status);    
      
SDSEXTERN void SdsSizeDefined(SdsIdType id, unsigned long *bytes, StatusType * SDSCONST status);

SDSEXTERN void SdsIsExternal(SdsIdType id, int *external, StatusType * SDSCONST status);

SDSEXTERN void SdsGetExternInfo(SdsIdType id, void **data, StatusType * SDSCONST status);
           
SDSEXTERN void SdsList(SdsIdType id, StatusType * SDSCONST status);

SDSEXTERN void SdsWrite(SdsIdType id, SDSCONST char *filename, StatusType * SDSCONST status);

SDSEXTERN void SdsFreeId(SdsIdType id, StatusType * SDSCONST status);

SDSEXTERN void SdsFlush(SdsIdType id, StatusType * SDSCONST status);

SDSEXTERN void SdsRead(SDSCONST char *filename, SdsIdType *id, StatusType * SDSCONST status);

SDSEXTERN void SdsFillArray(SdsIdType array_id, SdsIdType elem_id,
                StatusType * SDSCONST status);


SDSEXTERN void SdsReadFree(SdsIdType id, StatusType * SDSCONST status);
SDSEXTERN SDSCONST char *SdsTypeToStr(SdsCodeType code, int mode);
SDSEXTERN void SdsFindByName( SdsIdType parent_id,  
                    SDSCONST char * name, 
                    unsigned int * skip, 
                    SdsIdType * id, 
                    StatusType * SDSCONST status );



SDSEXTERN void Sds__MarkFree(SdsIdType id);

SDSEXTERN void Sds__Free(SdsIdType id, StatusType * SDSCONST status);

SDSEXTERN void Sds___WatchEvent(SdsIdType id, int eventFlag, const char * sourceFunc);


#define SDS_COMP_MESS_ERROR 1
#define SDS_COMP_MESS_WARN  2

SDSEXTERN void SdsCompiler(SDSCONST char *string, int messages, int intaslong, SdsIdType *id, StatusType *status);


/*
 * Note - if you get a syntax error at this point, it is likely
 * that INT64 has not been defined.  See the relevant part of
 * sdsport.h. 
 */
SDSEXTERN INT64 SdsSetI64(long high, unsigned long low);

SDSEXTERN UINT64 SdsSetUI64(unsigned long high, unsigned long low);

SDSEXTERN void SdsGetI64(INT64 i64, long *high, unsigned long *low);

SDSEXTERN void SdsGetUI64(UINT64 i64, unsigned long *high, unsigned long *low);


SDSEXTERN void SdsGetIdInfo( INT32 * pnum, INT32 * pasize, INT32 * puids );

struct SdsCheckStruct {
    INT32 _init_last_id;
    INT32 _init_current_array_size;
    INT32 _init_unused_ids;
    INT32 leakCount;
    INT32 _spare2;
    INT32 _spare3;
    INT32 _spare4;
};
typedef struct SdsCheckStruct SdsCheckType;

SDSEXTERN void SdsCheckInit(SdsCheckType *chkData, StatusType *status);
SDSEXTERN void SdsCheck(const char *mes, SdsCheckType *chkData, 
                        StatusType *status); 

SDSEXTERN void SdsFreeIdAndCheck(const char *mes, SdsIdType id, StatusType *status);
SDSEXTERN SDSCONST char * SdsErrorCodeString(StatusType error);
SDSEXTERN void SdsListInUse();

#if defined(SDS_CHECK_FREE)||defined(SDS_CHECK_FREE_W)
#include <stdio.h>
#ifndef SdsFreeId
#ifdef SDS_CHECK_FREE_W
#warning "Checking SdsFree operations"
#endif
/*
 * Note - the C++ version does its own thing below - see cleanup().
 */
#define SdsFreeId(_id_, _status) \
    { \
        if (*(_status) == STATUS__OK)                   \
        {                                               \
            SdsFreeIdAndCheck("", (_id_), (_status));    \
            if (*(_status) == SDS__CHK_FREE)             \
            {                                           \
                fprintf(stderr, "    At file %s, line %d\n", __FILE__, __LINE__); \
                fprintf(stderr, "    This warning was enabled by SDS_CHECK_FREE or SDS_CHECK_FREE_W macro\n"); \
                *(_status) = STATUS__OK;                \
            }                                           \
        }                                               \
    }
#endif
#endif

#ifdef __cplusplus

} /* extern "C" */

/*
 * C++ only section.
 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *  Here is the a C++ interface to SDS. No object code is required since
 *  all code is inline.
 *
 */
#ifdef DRAMA_ALLOW_CPP_STDLIB
#include <string>
template <typename T> class SdsArrayAccessHelper {
public:
    friend class SdsId;
    /* Some exceptions thrown from the subscript operator */
    class NoDataException {
        std::string detail;
    public:
        NoDataException(const char *why) :detail(why) { }
        std::string const & GetDetails() const { return detail; };

    };
    class InvalidIndexException {
        std::string detail;
    public:
        InvalidIndexException(const char *why) :detail(why) { }
        std::string const & GetDetails() const { return detail; };
    };

private:
    SdsCodeType code;         /* The SDS code of the item */
    unsigned long elements;   /* Number of element in the array */
    T* data;                  /* The array pointer is written here */

    /*
     * Help function used to check an index is valid.  Also checks
     * that we have some data. Throws expections on problems.
     */
    void CheckIndexAndData(unsigned long index) const {
        if (!data)
        {
            throw new NoDataException("Index %d, Code %d, elements %d - data is invalid");
        }
        if (index >= elements)
        {
            throw new InvalidIndexException("Index %d, Code %d, elements %d - index is invalid");
        }
    }


    /*
     * The remaining private items are accessed by SdsId as a friend class.
     */
    /*
     * Return the address of the address of the data being accessed  
     *
     * This is used by SdsId.AccessArray() to put the address of the
     * data item.
     */
    void ** Data() { return (void **)&data; }

    /*
     * Set the number of elements in the array.
     *
     * This is used by SdsId.AccessArray() set the number of elements in
     * the array.
     */
    void SetElements(unsigned long nelem) {
        elements = nelem;
    }


protected:
    SdsArrayAccessHelper(SdsCodeType c) : code(c), elements(0), data(0) {
    }
public:
 
    SdsCodeType Code() const { return code; }
    unsigned long Size() const { return elements; }
    T const & operator[](const unsigned long index) const {
        CheckIndexAndData(index);
        return data[index];
    }
    T  & operator[](const unsigned long index) {
        CheckIndexAndData(index);
        return data[index];
    }
    T * DataAddressRW() {
        return data;
    }
    const T * DataAddressRO() const {
        return data;
    }
};  /* SdsArrayAccessHelper */

/*
 * Classes for each SDS data type.
 */
class SdsArrayChar : public SdsArrayAccessHelper<char> {
public:
    SdsArrayChar() : SdsArrayAccessHelper<char>(SDS_CHAR) {
    }

};
class SdsArrayUbyte : public SdsArrayAccessHelper<unsigned char> {
public:
    SdsArrayUbyte() : SdsArrayAccessHelper<unsigned char>(SDS_UBYTE) {
    }

};
class SdsArrayByte : public SdsArrayAccessHelper<signed char> {
public:
    SdsArrayByte() : SdsArrayAccessHelper<signed char>(SDS_BYTE) {
    }

};


class SdsArrayUshort : public SdsArrayAccessHelper<unsigned short> {
public:
    SdsArrayUshort() : SdsArrayAccessHelper<unsigned short>(SDS_USHORT) {
    }

};
class SdsArrayShort : public SdsArrayAccessHelper<short> {
public:
    SdsArrayShort() : SdsArrayAccessHelper<short>(SDS_SHORT) {
    }

};



class SdsArrayINT32 : public SdsArrayAccessHelper<INT32> {
public:
    SdsArrayINT32() : SdsArrayAccessHelper<INT32>(SDS_INT) {
    }

};
class SdsArrayUINT32 : public SdsArrayAccessHelper<UINT32> {
public:
    SdsArrayUINT32() : SdsArrayAccessHelper<UINT32>(SDS_UINT) {
    }
};


class SdsArrayINT64 : public SdsArrayAccessHelper<INT64> {
public:
    SdsArrayINT64() : SdsArrayAccessHelper<INT64>(SDS_I64) {
    }

};
class SdsArrayUINT64 : public SdsArrayAccessHelper<UINT64> {
public:
    SdsArrayUINT64() : SdsArrayAccessHelper<UINT64>(SDS_UI64) {
    }
};

class SdsArrayDouble : public SdsArrayAccessHelper<double> {
public:
    SdsArrayDouble() : SdsArrayAccessHelper<double>(SDS_DOUBLE) {
    }
};
class SdsArrayFloat : public SdsArrayAccessHelper<float> {
 public:
    SdsArrayFloat() : SdsArrayAccessHelper<float>(SDS_FLOAT) {
    }
};

#endif /* defined DRAMA_ALLOW_CPP_STDLIB */

SDSCLASS SdsId {
    private:
        SdsIdType id;   /* Actual Sds id.  If 0, then no id is allocated */
        struct {
                bool free : 1;/* Set true to cause destructor to free the id*/
                bool del  : 1;/* If free is true, destructor will do SdsDelete*/
                bool readfree : 1;/* if free and del, to SdsReadFree */
                } flags;

        /* Private routine to clean up, will be called by destructor and 
           Shallow and Deep copy operations */

        /* If this check free code is not to be run, we don't want the from_where argument, it
           causes warnings in all using code.  This macro setup allows that
        */
#if defined(SDS_CHECK_FREE)||defined(SDS_CHECK_FREE_W)            
#define SDS__CHECK_ARG(_arg_) _arg_
#else
#define SDS__CHECK_ARG(_arg_) 
#endif


        void CleanUp(const char * SDS__CHECK_ARG(from_where)) {
            /* If we have an id and the free flag is set */
            /* In the future, we should consider do a throw if status goes */
            /* bad, instead of just ignoring it                 */
            
            if ((id)&&(flags.free))
            {
                /* If del and readfree, we need to do SdsReadFree */
                if ((flags.del)&&(flags.readfree))
                {
                    StatusType ignore = STATUS__OK;
                    SdsReadFree(id,&ignore);
                }
                /* If del and not readfree, we need to to SdsDelete */
                else if (flags.del)
                {
                    StatusType ignore = STATUS__OK;
                    SdsDelete(id,&ignore);
                }
                /* Free the id */
                StatusType ignore = STATUS__OK;
#if defined(SDS_CHECK_FREE)||defined(SDS_CHECK_FREE_W)            
                SdsFreeIdAndCheck("", id, &ignore);
                if (ignore != STATUS__OK)
                {
                    fprintf(stderr, "SDS FreeId failure in C++ cleanup(), called from \"%s\" for id %d\n", from_where,(int)id);
                    fprintf(stderr, "    Status Code:%s\n", SdsErrorCodeString(ignore));
                    fprintf(stderr, "    SdsId object address is %p\n", (void *)(this));
                    fprintf(stderr, "    Sorry - don't have more exact location information\n");
                    fprintf(stderr, "    This warning was enabled by SDS_CHECK_FREE or SDS_CHECK_FREE_W macro\n");
                }
#else
                SdsFreeId(id,&ignore);
#endif

            }
        }
        /* Assignment and Copy operators, made private to avoid misuse */       
        SdsId& operator=(const SdsId& a); /* Assignment */
        SdsId(const SdsId&); /* Copy */


#ifdef DRAMA_ALLOW_CPP_STDLIB
        /* This is used by the ArrayAccess methods to check the item
           is appropiate for the SdsArrayAccessHelper being used
        */
        void CheckArrayType(
            const SdsCodeType code,     /* Expected code */
            const int ndims,            /* Expected number of dims */
            unsigned long * const dims, /* Actual dims written here */
            StatusType * const status) {
            
            if (*status != STATUS__OK) return;
            char name[SDS_C_NAMELEN];
            SdsCodeType tcode;
            long tndims;
            /*
             * Get details on the object.
             */
            Info(name, &tcode, &tndims, dims, status);
            /*
             * Check the code and number of dimensions are correct.
             */
            if (tcode != code)
            {
                *status = SDS__TYPE;
                return;
            }
            if (tndims == 0)
            {
                *status = SDS__NOTARR;
                return;
            }
            if (tndims != ndims)
            {
                *status = SDS__INVDIMS;
                return;
            }
            
        }
        /*
         * A simplified access to  CheckArrayType, for a single dimensional
         * array.
         */
        void CheckArrayTypeSingleDim(
            const SdsCodeType code, 
            unsigned long * const nitems,  /* Actual number of items written here*/
            StatusType * const status) {
            
            unsigned long dims[SDS_C_MAXARRAYDIMS];
            CheckArrayType(code, 1, dims, status);
            if (*status != STATUS__OK) return;
            *nitems = dims[0];
            
        }
#endif /* defined DRAMA_ALLOW_CPP_STDLIB */

    public:
        SdsId(const SdsIdType item = 0, const bool free=false, 
                        const bool del = false, const bool readfree = false) :
                id(item) {
                 flags.free = free;
                 flags.del = del; 
                 flags.readfree = readfree;
        }
        SdsId(void * const data, StatusType * const status, 
                   const bool import = false) :
                id(0) {
            flags.free = true;
            flags.readfree = false;
            if (import)
            {
                SdsImport(data,&id,status);
                flags.del = true;
            }
            else
            {
                SdsAccess(data,&id,status);
                flags.del = false; 
            }
        }
        SdsId(const void * const data, StatusType * const status) : id(0) {
            flags.free = true;
            flags.readfree = false;
            flags.del = true;
            SdsImport(data,&id,status);
        }
        SdsId(const char * const filename, StatusType * const status) :
                id(0) {
            flags.free = true;
            flags.del = true;
            flags.readfree = true;
            SdsRead(filename,&id,status);
        }
        SdsId(const SdsId &parent_id, const char * const name, 
            const SdsCodeType code,
            StatusType * const status, const long nextra = 0, 
            const char * const extra = 0) :
                id(0) {
            flags.free = true;
            flags.del = false;
            flags.readfree = false;
            SdsNew(parent_id.id,name,nextra,extra,code,0,0,&id,status);
        }    
        SdsId(const char * const name, const SdsCodeType code,
            StatusType * const status, const long nextra = 0, 
            const char * const extra = 0) :
                id(0) {
            flags.free = true;
            flags.del = true;
            flags.readfree = false;
            SdsNew(0,name,nextra,extra,code,0,0,&id,status);
        }    
        SdsId(const SdsId &parent_id, const char * const name, 
            const SdsCodeType code,
            const long ndims, const unsigned long *dims,
            StatusType * const status, const long nextra = 0, 
            const char * const extra = 0) :
                id(0) {
            flags.free = true;
            flags.del = false;
            flags.readfree = false;
            SdsNew(parent_id.id,name,nextra,extra,code,ndims,dims,&id,status);
        }    
        /* Constructor which creates a new array top-level item */
        SdsId(const char * const name, const SdsCodeType code,
            const long ndims, const unsigned long *dims,
            StatusType * const status, const long nextra = 0, 
            const char * const extra = 0) :
                id(0) {
            flags.free = true;
            flags.del = true;
            flags.readfree = false;
            SdsNew(0,name,nextra,extra,code,ndims,dims,&id,status);
        }    
        
        SdsId(const SdsId &array_id, const long nindicies, 
            const unsigned long * const indicies, StatusType * const status) :
                id(0) {
            flags.free = true;
            flags.del = false;
            flags.readfree = false;
            SdsCell(array_id.id, nindicies, indicies, &id,status);      
        }
        SdsId(const SdsId& source, StatusType * const status):
                id(0) {
            flags.free = true;
            flags.del = true;
            flags.readfree = false;
            SdsCopy(source.id, &id, status);
        }
        SdsId(const SdsId& source, const char * const name, 
                StatusType * const status) :
                id(0) {
            flags.free = true;
            flags.del = false;
            flags.readfree = false;
            SdsFind(source.id,name,&id,status);
        }
        
        SdsId(const SdsId& source, const long index, StatusType * const status):
                id(0) {
            flags.free = true;
            flags.del = false;
            flags.readfree = false;
            SdsIndex(source.id,index,&id,status);
        }
        
        /*Just invoke the private cleanup routine */
        virtual ~SdsId() {
            CleanUp("SdsId destructor");
        }
        /* Modify flags */

        void SetFree() { flags.free = true; }
        void SetDelete() { flags.del = true; }

        void ClearDelete() { flags.del = false; }

        void Outlive() { flags.free = false; flags.del = false; 
                           flags.readfree = false; }
        
/*
 *      General operations, as per similar Sds operation.
 *      Currently only Delete, Get and Put are virtual.
 */
        
        virtual void Delete(StatusType * const status) {
            SdsDelete(id,status);
            if (*status == STATUS__OK)
            {
                flags.del = false;
                if (flags.free)
                {
                    SdsFreeId(id, status);
                    if (*status == STATUS__OK)
                    {
                        id = 0;
                        flags.free = false;
                    }
                }
            }
        }
        void Export(const unsigned long length, 
                    void * const data,
                    StatusType * const status) {
            SdsExport(id,length,data,status);
        }
        void ExportDefined(const unsigned long length, 
                    void * const data,
                    StatusType * const status) {
            SdsExportDefined(id,length,data,status);
        }
        void Extract(StatusType * const status) {
            SdsExtract(id,status);
            /* If we succeed, we need to modify the flags to appropiate for
               and indepent toplevel item */
            if (*status == STATUS__OK)
            {
                flags.free = true;
                flags.del = true;
                flags.readfree = false;
            }
        }
        void Flush(StatusType * const status) {
            SdsFlush(id,status);
        }
        virtual void Get(const unsigned long length,
                 void * const data,
                 StatusType * const status,
                 unsigned long *actlen = 0,
                 const unsigned long offset=0) const
        {
            unsigned long myactlen;
            if (!actlen) actlen = &myactlen;
            SdsGet(id,length,offset,data,actlen,status);
        }
        void GetExtra(const unsigned long length,
                 char * const extra,
                 StatusType * const status,
                 unsigned long *actlen = 0) const
        {
            unsigned long myactlen;
            if (!actlen) actlen = &myactlen;
            SdsGetExtra(id,length,extra,actlen,status);
        }
        void Info(char * const name,
                  SdsCodeType * const code,
                  long * const ndims,
                  unsigned long * const dims,
                  StatusType * const status) const {
            SdsInfo(id,name,code,ndims,dims,status);
        }
        /* Give access to individual things normally returned by SdsInfo*/
        void GetName(char * const name,
                     StatusType * const status) const {
            SdsCodeType code;
            long ndims;
            unsigned long dims[SDS_C_MAXARRAYDIMS];
            SdsInfo(id,name,&code,&ndims,dims,status);
        }
        void Code(SdsCodeType * const code,
                        StatusType * const status) const {
            char name[16];
            long ndims;
            unsigned long dims[SDS_C_MAXARRAYDIMS];
            SdsInfo(id,name,code,&ndims,dims,status);
        }
         void Dims(long * const ndims, unsigned long * const dims,
                        StatusType * const status) const {
            char name[16];
            SdsCodeType code;
            SdsInfo(id,name,&code,ndims,dims,status);
        }
        void Insert(SdsId & to_insert, StatusType * const status) {
            SdsInsert(id,to_insert.id,status);
            /* If we succeed, the new child should not be deleted when
                it's id is destroyed, so clear the flag */
            if (*status == STATUS__OK)
                to_insert.flags.del = false;
        }
        void Insert(SdsId & to_insert, const long ndims,
                        const unsigned long * const dims, 
                        StatusType * const status) {
            SdsInsertCell(id,ndims,dims,to_insert.id,status);
            /* If we succeed, the new child should not be deleted when
                it's id is destroyed, so clear the flag */
            if (*status == STATUS__OK)
                to_insert.flags.del = false;
        }

        void FillArray(const SdsId &elem, StatusType * const status) {
            SdsFillArray(id,elem.id,status);
        }

        void Pointer(void **data, StatusType * const status, 
                     unsigned long * length = 0) {
            unsigned long mylength;
            if (!length) length = &mylength;
            SdsPointer(id,data,length,status);
        }

        virtual void Put(const unsigned long length,
                 void * const data,
                 StatusType * const status,
                 const unsigned long offset=0)
        {
            SdsPut(id,length,offset,data,status);
        }
        void PutExtra(const long nextra,
                 const char * const extra,
                 StatusType * const status)
        {
            SdsPutExtra(id,nextra,extra,status);
        }
        void Rename(const char * const name, 
                        StatusType * const status) {
            SdsRename(id,name,status);
        }
        void Resize(const long ndims, const unsigned long *dims, 
                        StatusType * const status) {
             SdsResize(id,ndims,dims,status);
        }
        void Size(unsigned long * const bytes, 
                  StatusType * const status) const {
            SdsSize(id,bytes,status);
        }
        void SizeDefined(unsigned long * const bytes, 
                  StatusType * const status) const {
            SdsSizeDefined(id,bytes,status);
        }
        void List(StatusType * const status) const {
            SdsList(id,status);
        }
        void Write(const char * const filename,
                   StatusType * const status) const {
            SdsWrite(id,filename,status);
        }        

        void IsExternal(int * const external, 
                   StatusType * const status) const {
            SdsIsExternal(id, external, status);
        }
        void GetExternInfo(void **data, 
                   StatusType * const status) const {
            SdsGetExternInfo(id, data, status);
        }
        
        operator SdsIdType(void) const { return id; }
        
        /* Note, if there is no bool type, we can just use the above operator which 
           returns the Sds id. Similary for Borland Cpp which does not like
           this operator (ambigious with the above operator 
         */
#       if (!defined(CPP_NOBOOL))  && (!defined(BORLAND))
        operator bool(void) const { return (id != 0); }
#       endif
        
        SdsIdType COut(const bool outlives, bool * const free = 0,
                bool * const del= 0, bool * const readfree = 0) {
            if (free)
                *free = flags.free;
            if (del)
                *del  = flags.del;
            if (readfree)
                *readfree = flags.readfree;
            if (outlives)
                flags.free = flags.del = flags.readfree = false;
            return (SdsId::id);
        }
        /* Obsolete version     */
        void COut(const bool outlives, SdsIdType *item, bool * const free = 0,
                bool * const del= 0, bool * const readfree = 0) {
            *item = COut(outlives,free,del,readfree);
        }

        void ShallowCopy (SdsId & source, const bool outlives=true) {
            if (this != &source)
            {
                CleanUp("SdsId::ShallowCopy 1");        /* Run destructor on old id */
                id = source.id;
                if (outlives)
                {
                    /* If we will outlive the source, then we copy the source's 
                     * flags and set  the sources flags to false.       
                     */

                    flags.free = source.flags.free;
                    flags.del  = source.flags.del;
                    flags.readfree  = source.flags.readfree;

                    source.flags.free = source.flags.del = 
                                        source.flags.readfree = false;
                }
                else
                {
                    flags.free = flags.del = flags.readfree = false;
                }
            }
        }
        void DeepCopy (const SdsId &source, StatusType * const status)
        {
            if (this != &source)
            {
                CleanUp("SdsId::DeepCopy 1");   /* Run destructor code on old id */
                id = 0;
                SdsCopy(source.id,&id,status);
                flags.free = true;
                flags.del = true;
                flags.readfree = false;
            }
            else
            {
                /*
                 * this = &source;
                 *
                 * Deep copy of self.  If this item is external, then
                 * we actual do a copy - but we have to get the ordering
                 * right.  This ensures that DeepCopy() always gives us
                 * something we can modify the structure of.
                 */
                int external;
                SdsIsExternal(id, &external, status);
                if (external)
                {
                    /*
                     * copy this to a new SDS id..
                     */
                    SdsIdType newId;
                    SdsCopy(id,&newId,status);
                    
                    if (*status == STATUS__OK)
                    {
                        /*
                         * Run the contructor on "this" and then set up 
                         * this again.
                         */
                        CleanUp("SdsId::DeepCopy 2");
                        id = newId;
                        flags.free = true;
                        flags.del = true;
                        flags.readfree = false;
                        
                    }
                    
                }
            }
        }
        void ShallowCopy (const SdsIdType source, const bool free=false, 
                        const bool del = false, const bool readfree = false)
        {
            CleanUp("SdsId::ShallowCopy 2");    /* Run destructor on old id */
            flags.free = free;
            flags.del = del; 
            flags.readfree = readfree;
            id = source;
        }
        void DeepCopy (const SdsIdType source, StatusType *status)
        {
            CleanUp("SdsId::DeepCopy 3");       /* Run destructor code on old id */
            id = 0;
            SdsCopy(source,&id,status);
            flags.free = true;
            flags.del = true;
            flags.readfree = false;
        }
#ifdef DRAMA_ALLOW_CPP_STDLIB

        template <typename T> void ArrayAccess(
            SdsArrayAccessHelper<T> * const data,
            StatusType *const status) {
            
            unsigned long dims[SDS_C_MAXARRAYDIMS];
            CheckArrayTypeSingleDim(data->Code(), dims, status);
            if (*status != STATUS__OK) return;
            data->SetElements(dims[0]);
            
            Pointer(data->Data(), status); 
        }
        template <typename T> void ArrayAccess(
            const unsigned long expitems, /* Expected number of elements in array*/
            SdsArrayAccessHelper<T> * const data,
            StatusType *const status) {
            
            unsigned long dims[SDS_C_MAXARRAYDIMS];
            CheckArrayTypeSingleDim(data->Code(), dims, status);
            if (*status != STATUS__OK) return;
            if (dims[0] != expitems)
            {
                *status = SDS__INVDIMS;
                return;
            }
            data->SetElements(dims[0]);
            Pointer(data->Data(), status); 
        }
        template <typename T> void ArrayAccess(
            SdsArrayAccessHelper<T> * const data,
            long ndims,
            unsigned long dims[],
            StatusType *const status) {
            
            if ((ndims < 1)||(ndims > 7))
            {
                *status = SDS__INVDIMS;
                return;
            }
            CheckArrayType(data->Code(), ndims, dims, status);
            if (*status != STATUS__OK) return;

            /*
             * work out the number of elements
             */
            unsigned long elements = dims[0];
            for (long i = 1; i < ndims ; ++i)
            {
                elements *= dims[i];
            }
            data->SetElements(elements);
            /*
             * Access the data.
             */
            Pointer(data->Data(), status); 
        }


        template <typename T> void ArrayAccess(
            SdsArrayAccessHelper<T> * const data,
            long *ndims,
            unsigned long dims[],
            StatusType *const status) {
            
            /*
             * A bit of a pain, we need to call Dims to get the number
             * of dimensions.
             */
            Dims(ndims, dims, status);
            /*
             * The use the above version where we know the number of dimenions
             */
            ArrayAccess(data, *ndims, dims, status);
        }



#endif /* defined DRAMA_ALLOW_CPP_STDLIB */


}; /* class SdsId */

SDSEXTERN const SdsId SdsNull;

#ifdef DRAMA_ALLOW_CPP_STDLIB
#include <stdio.h>
class  SdsIDChecker {
private:
    SdsCheckType _chkData;
    int _line;
    std::string _file;
    std::string _function;
public:
    SdsIDChecker(int line, const char *file, const char *function) 
        : _line(line), _file(file), _function(function) {
        StatusType ignore = STATUS__OK;
        SdsCheckInit(&_chkData, &ignore);
    }
    virtual ~SdsIDChecker() {
        StatusType status = STATUS__OK;
        SdsCheck(0, &_chkData, &status);
        if (status == SDS__CHK_LEAK)
            fprintf(stderr,"Warning:SdsIDChecker:Function leaked SDS id's - function %s, file %s, check object at line %d\n", _function.c_str(), _file.c_str(), _line);
        else if (status == SDS__CHK_RELEASED)
            fprintf(stderr,"Warning:SdsIDChecker:Function released SDS id's - function %s, file %s, check object at line %d\n", _function.c_str(), _file.c_str(), _line);
    }
};
#define SDS_CHECK_IDS(_function_) SdsIDChecker _sds_id_checker(__LINE__, __FILE__, (_function_))
#endif /* defined DRAMA_ALLOW_CPP_STDLIB */

 
#endif

/* Define SdsMalloc and SdsFree.  These are normally just defined
   to malloc and free but sometimes when debugging we want different
   versions
 */
 
#define SdsMalloc(_size) (void *)malloc(_size)
#define SdsFree(_where)   (void)free((void *)(_where))

#endif

---