arg.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$"
 *
 * History:
 *     10-Nov-2004 - TJF - Original Version.
 */
 
 
 
#ifndef ARGINC
#define ARGINC
/*
 *  @(#) $Id$
 */
/*
 * 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 documentation (see DramaHtml/Makefile,
 * DramaHtml/doxygen.config and DramaHtml/filter.m4 for details)
 */
 
#ifdef __cplusplus
 
/*
 * If under C++ and this is allowed, then we can add functions which
 * require the C++ Standard Library (say under GCC 2.95.2 or later).
 */
#ifdef DRAMA_ALLOW_CPP_STDLIB
#include <string>
#endif
 
extern "C" {
 
#endif
#include "sds.h"
#include "arg_err.h"
#include "status.h"
 
/*
 *   Is const acceptable on this machine.
 */
#if defined(__cplusplus) || defined(__STDC__) || defined (VAXC)
#     define ARGCONST const
#else
#     define ARGCONST  /* */
#endif
 
 
/*
 * Under Windows, we may need to export or import the functions, depending
 * on if we are building the DLL or linking against it.
 */
#ifdef WIN32
#ifdef DRAMA_DLL  /* Am building DRAMA DLL */
#define ARGEXTERN __declspec(dllexport)
#elif defined(DRAMA_STATIC) /* Building a static library */
#define ARGEXTERN extern
#else           /* Am building application with DLL */
#define ARGEXTERN __declspec(dllimport)
#endif
 
#else
#define ARGEXTERN extern
#endif
 
/*
 * If defined, we are using the newer C++ overloads.
 */
#define ARG_NEWCPP_OVERLOADS 1
 
 
ARGEXTERN void ArgNew(SdsIdType *id, StatusType * ARGCONST status);
ARGEXTERN void ArgPutc(SdsIdType id, ARGCONST char *name, char value, 
                           StatusType * ARGCONST status);
ARGEXTERN void ArgPuts(SdsIdType id, ARGCONST char *name, short value,
                           StatusType * ARGCONST status);
ARGEXTERN void ArgPutus(SdsIdType id, ARGCONST char *name, unsigned short value,
                           StatusType * ARGCONST status);
ARGEXTERN void ArgPuti(SdsIdType id, ARGCONST char *name, long value, 
                           StatusType * ARGCONST status);
ARGEXTERN void ArgPuti64(SdsIdType id, ARGCONST char *name, INT64 value, 
                           StatusType * ARGCONST status);
 
ARGEXTERN void ArgPutu(SdsIdType id, ARGCONST char *name, unsigned long value, 
                           StatusType * ARGCONST status);
 
ARGEXTERN void ArgPutu64(SdsIdType id, ARGCONST char *name, UINT64 value,
                           StatusType * ARGCONST status);
 
ARGEXTERN void ArgPutf(SdsIdType id, ARGCONST char *name, float value,
                           StatusType * ARGCONST status);
ARGEXTERN void ArgPutd(SdsIdType id, ARGCONST char *name, double value,
                           StatusType * ARGCONST status);
ARGEXTERN void ArgPutString(SdsIdType id, ARGCONST char *name, ARGCONST char *value,
                           StatusType * ARGCONST status);
ARGEXTERN void ArgGetc(SdsIdType id, ARGCONST char *name, char *value,
                           StatusType * ARGCONST status);
ARGEXTERN void ArgGets(SdsIdType id, ARGCONST char *name, short *value,
                           StatusType * ARGCONST status);
ARGEXTERN void ArgGetus(SdsIdType id, ARGCONST char *name, unsigned short *value,
                           StatusType * ARGCONST status);
ARGEXTERN void ArgGeti(SdsIdType id, ARGCONST char *name, long *value,
                           StatusType * ARGCONST status);
ARGEXTERN void ArgGeti64(SdsIdType id, ARGCONST char *name, INT64 *value,
                           StatusType * ARGCONST status);
 
ARGEXTERN void ArgGetu(SdsIdType id, ARGCONST char *name, unsigned long *value,
                           StatusType * ARGCONST status);
ARGEXTERN void ArgGetu64(SdsIdType id, ARGCONST char *name, UINT64 *value,
                            StatusType * ARGCONST status);
 
ARGEXTERN void ArgGetf(SdsIdType id, ARGCONST char *name, float *value, 
                           StatusType * ARGCONST status);
ARGEXTERN void ArgGetd(SdsIdType id, ARGCONST char *name, double *value, 
                          StatusType * ARGCONST status);
ARGEXTERN void ArgGetString(SdsIdType id, ARGCONST char *name, long len, char *value, 
                          StatusType * ARGCONST status);
ARGEXTERN void ArgDelete(SdsIdType id, StatusType * ARGCONST status);
 
 
ARGEXTERN void ArgCvt (ARGCONST void * SrcAddr, SdsCodeType SrcType,  SdsCodeType DstType,
             void * DstAddr, unsigned long int DstLen , 
                          StatusType  * ARGCONST status);
ARGEXTERN void ArgLook (char *SrcAddr, int USFlag, int MinFlag, SdsCodeType *DstType, 
                          StatusType * ARGCONST status);
 
 
ARGEXTERN void ArgToString (SdsIdType id,int maxlen,int *length,char *string,
                          StatusType * ARGCONST status);
 
typedef void (*ArgListFuncType)(
                        void *client_data,
                        ARGCONST char *line,                    
                        StatusType * status);
ARGEXTERN void ArgSdsList(SdsIdType id, unsigned buflen, char *buffer, 
                 ArgListFuncType func, void * client_data,
                 StatusType * ARGCONST status);
 
 
ARGEXTERN void ArgFind(SdsIdType parent_id, ARGCONST char *name, 
                       SdsIdType *id, 
                       StatusType * ARGCONST status);
 
ARGEXTERN void ArgCheckItem(SdsIdType id, 
                            SdsCodeType code, long ndims, 
                            long * ARGCONST dims, 
                            StatusType * ARGCONST status);
 
 
/*
 * Methods for creating/setting array items.  We don't have the complete
 * set as yet.
 */
ARGEXTERN void ArgPut1DArrayD(SdsIdType id,
                              const char *name,
                              unsigned long dim,
                              const double data[],
                              StatusType * status);
 
 
ARGEXTERN void ArgPut1DArrayDElem(SdsIdType id,
                                  const char *name,
                                  unsigned long dim,
                                  unsigned int index,
                                  double data,
                                  StatusType * const status);
                              
 
ARGEXTERN void ArgPut1DArrayI(SdsIdType id,
                              const char *name,
                              unsigned long dim,
                              const INT32 data[],
                              StatusType * status);
 
 
ARGEXTERN void ArgPut1DArrayIElem(SdsIdType id,
                                  const char *name,
                                  unsigned long dim,
                                  unsigned int index,
                                  INT32 data,
                                  StatusType * const status);
                              
ARGEXTERN void ArgPut1DArrayB(SdsIdType id,
                              const char *name,
                              unsigned long dim,
                              const unsigned char data[],
                              StatusType * status);
 
 
ARGEXTERN void ArgPut1DArrayBElem(SdsIdType id,
                                  const char *name,
                                  unsigned long dim,
                                  unsigned int index,
                                  unsigned char data,
                                  StatusType * const status);
 
 
 
ARGEXTERN void ArgPut1DArrayS(SdsIdType id,
                              const char *name,
                              unsigned long slen,
                              unsigned long dim,
                              const char *data[],
                              StatusType * status);
 
 
ARGEXTERN void ArgPut1DArraySElem(SdsIdType id,
                                  const char *name,
                                  unsigned long slen,
                                  unsigned long dim,
                                  unsigned int index,
                                  const char *data,
                                  StatusType * const status);
 
 
#ifdef __cplusplus
} /* extern "C" */
 
 
/*
 * C++ only section.
 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *
 *  Here is the a C++ interface to ARG.  No object modifications required since
 *  all code is inline.
 */
class Arg : public SdsId {
    private:
        /* Assignment and Copy operators, made private to avoid misuse, but
           this is done in SdsId so would have been prohibited anyway
         */
        Arg& operator=(const Arg&); /* Assignment */
        Arg(const Arg&); /* Copy */
     public:
 
        Arg (const SdsIdType item=0, const bool free=false, 
             const bool del = false, const bool readfree = false) : 
                        SdsId(item,free,del,readfree) {
        };
        Arg (bool /*flag*/, StatusType * const status, 
                        const char * const name = "ArgStructure") : 
            SdsId(name, SDS_STRUCT,status) {
        }
        
        void New (StatusType * const status,
                        const char * const name = "ArgStructure") {
            /*
             * We create the new item and then us SdsId::ShallowCopy to
             * copy it into this object.
             */
            Arg tid(true,status, name);
            ShallowCopy(tid,true);
        };
 
        Arg(const SdsId& source, const char * const name,
                StatusType * const status) :
                SdsId(0,false,false,false) {
            /*
             * This is confusing since what we really want is to do is SdsFind 
             * but we want the ErsRep reporting facilities of ArgFind, so we   
             * must create this item as a null item, call ArgFind using the    
             * arguments and then use ShallowCopy to copy the SdsIdType to this 
             * item 
             */
            SdsIdType tid=0;
            ArgFind(source,name,&tid,status);
            ShallowCopy(tid,true,false,false);
        }
 
 
        void ToString(int maxlen, int *length, char *string, 
                                StatusType * const status)
        {
            ArgToString(*this,maxlen,length,string,status);
        }
        /* More modern  naming of this */
        void toString(int maxlen, int *length, char *string, 
                      StatusType * const status) {
            ToString(maxlen, length, string, status);
        }
        void CheckItem(SdsCodeType code,
                       StatusType *status,
                       long ndims=-1, 
                       long * dims=0) 
        {
            ArgCheckItem(*this, code, ndims, dims, status);
        }
        
 
#       ifndef CPP_NOBOOL
        void Put (const char *name, bool value, StatusType * const status) {
            unsigned short v = (int)value;
            ArgPutus(*this,name,v,status);
        };
#       endif
        void Put (const char *name, char value, StatusType * const status) {
            ArgPutc(*this,name,value,status);
        };
        void Put (const char *name, short value, StatusType * const status) {
            ArgPuts(*this,name,value,status);
        };
        void Put (const char *name, unsigned short value, 
                                           StatusType * const status) {
            ArgPutus(*this,name,value,status);
        };
 
        void Put (const char *name, INT32 value, StatusType * const status) {
            ArgPuti(*this,name,value,status);
        };
 
        void Put (const char *name, UINT32 value, StatusType * const status) {
            ArgPutu(*this,name,value,status);
        };
        void Put (const char *name, INT64 value, StatusType * const status) {
            ArgPuti64(*this,name,value,status);
        };
        void Put (const char *name, UINT64 value, StatusType * const status) {
            ArgPutu64(*this,name,value,status);
        };
        void Put (const char *name, float value, StatusType * const status) {
            ArgPutf(*this,name,value,status);
        };
        void Put (const char *name, double value, StatusType * const status) {
            ArgPutd(*this,name,value,status);
        };
#ifndef DRAMA_ALLOW_CPP_STDLIB
        // There is a version below which works when CPP_STDLIB is allowed.
        void Put (const char *name, const char *value, StatusType * const status) {
            ArgPutString(*this,name,value,status);
        };
#endif
 
#       ifndef CPP_NOBOOL
        void Get (const char *name, bool * value, 
                                              StatusType * const status)const {
            unsigned short v;
            ArgGetus(*this,name,&v,status);
            *value =  v ? true : false;
        }
#       endif
 
 
        void Put (const char *name, const long dim, const double data[],
                  StatusType * const status) {
            ArgPut1DArrayD(*this, name, dim, data, status);
        };
 
 
 
        void Put (const char *name, const long dim, const unsigned index,
                  const double data, StatusType * const status) {
            ArgPut1DArrayDElem(*this, name, dim, index, data, status);
        };
 
 
 
 
        void Put (const char *name, const long dim, const INT32 data[],
                  StatusType * const status) {
            ArgPut1DArrayI(*this, name, dim, data, status);
        };
 
        void Put (const char *name, const long dim, const unsigned index,
                  const INT32 data, StatusType * const status) {
            ArgPut1DArrayIElem(*this, name, dim, index, data, status);
        };
 
 
 
 
        void Put (const char *name, const long dim, const unsigned char data[],
                  StatusType * const status) {
            ArgPut1DArrayB(*this, name, dim, data, status);
        };
 
 
        void Put (const char *name, const long dim, const unsigned index,
                  const unsigned char data, StatusType * const status) {
            ArgPut1DArrayBElem(*this, name, dim, index, data, status);
        };
 
 
        void Put (const char *name,  const long slen, const long dim, const char *data[],
                  StatusType * const status) {
            ArgPut1DArrayS(*this, name, slen, dim, data, status);
        };
 
 
        void Put (const char *name, const long slen, const long dim, const unsigned index,
                  const char *data, StatusType * const status) {
            ArgPut1DArraySElem(*this, name, slen, dim, index, data, status);
        };
 
 
        void Get (const char *name, char * value, StatusType * const status)const {
            ArgGetc(*this,name,value,status);
        }
        void Get (const char *name, short * value, StatusType * const status)const {
            ArgGets(*this,name,value,status);
        }
        void Get (const char *name, unsigned short * value, 
                                              StatusType * const status) const {
            ArgGetus(*this,name,value,status);
        }
        void Get (const char *name, INT32 * value, StatusType * const status ) const{
            long v; /* Since ArgGeti uses long */
            ArgGeti(*this,name,&v,status);
            *value = v;
        }
        void Get (const char *name, UINT32 * value, 
                  StatusType * const status)const {
            unsigned long v; /* Since ArgGetu always uses long */
            ArgGetu(*this,name,&v,status);
            *value = v;
        }
        void Get (const char *name, INT64 * value, StatusType * const status) const{
            ArgGeti64(*this,name,value,status);
        }
        void Get (const char *name, UINT64 * value, StatusType * const status)const{
            ArgGetu64(*this,name,value,status);
        }
 
        void Get (const char *name, float * value, StatusType * const status) const{
            ArgGetf(*this,name,value,status);
        }
        void Get (const char *name, double * value, StatusType * const status)const {
            ArgGetd(*this,name,value,status);
        }
        void Get (const char *name, long len, char * value,  
                                               StatusType * const status) const{
            ArgGetString(*this,name,len,value,status);
        }       
        static void List(const SdsId & id, unsigned buflen, char *buffer, 
                 ArgListFuncType func, void * client_data,
                 StatusType * ARGCONST status) {
            ArgSdsList(id,buflen,buffer,func,client_data,status);
        }
 
/*
 *  
 *      Arg hids some Sds functions, so we redeclare them here.
 */
         void List(StatusType * const status) const {
            SdsList(*this,status);
        }
 
         void List(FILE *to, StatusType * const status) const {
             SdsListTo(to, *this,status);
        }
 
        void Get(const unsigned long length,
                 void * const data,
                 StatusType * const status,
                 unsigned long *actlen = 0,
                 const unsigned long offset=0) const {
            SdsId::Get(length,data,status,actlen,offset);
        }
        void Put(const unsigned long length,
                 void * const data,
                 StatusType * const status,
                 const unsigned long offset=0)
        {
            SdsId::Put(length,data,status,offset);
        }
 
        void Convert(SdsCodeType DstType,
                     void * DstAddr, 
                     unsigned long int DstLen , 
                     StatusType *status)
        {
            SdsIdType id = SdsIdType(*this); // Grab as an SDS id.
            ArgCvt(&id, ARG_SDS, DstType, DstAddr, DstLen, status);
        }
        Arg(const SdsId &source, 
            const long index, 
            StatusType *status) :
                SdsId(0, false, false, false)
        {
            SdsIdType tid = 0;
            SdsIndex(source,index,&tid,status);
            ShallowCopy(tid,true,false,false);
        }
 
#ifdef DRAMA_ALLOW_CPP_STDLIB
        /*
         * If DRAMA is allowed to use the C++ Standard Template library, then
         * we add these functions to arg.   All of these are about using
         * std::string instead of char[], and the only complicate one
         * is the Get function which gets the value as a string.
         *
         */
 
        Arg(const SdsId &source, 
            const std::string &name,
            StatusType *const status) :
                SdsId(0,false,false,false) {
            SdsIdType tid=0;
            ArgFind(source,name.c_str(),&tid,status);
            ShallowCopy(tid,true,false,false);
        }
 
        void PutExtra(const std::string &name,
                      const std::string &extraData,
                      StatusType *const status) {
 
            if (*status != STATUS__OK) return;
            SdsId item(*this, name.c_str(), status);
            item.PutExtra(extraData.length(),
                          extraData.c_str(),
                          status);
        }
 
        void Put (const std::string &name, bool value, 
                  StatusType * const status,
                  const std::string &extraData="") {
            unsigned short v = (int)value;
            ArgPutus(*this,name.c_str(),v,status);
 
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
        };
        void Put (const std::string &name, 
                  char value, 
                  StatusType * const status,
                  const std::string &extraData="") {
            ArgPutc(*this,name.c_str(),value,status);
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
        };
        void Put (const std::string &name,
                  short value, 
                  StatusType * const status,
                  const std::string &extraData="") {
            ArgPuts(*this,name.c_str(),value,status);
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
        };
        void Put (const std::string &name, unsigned short value, 
                                           StatusType * const status) {
            ArgPutus(*this,name.c_str(),value,status);
        };
        void Put (const std::string &name, 
                  INT32 value, 
                  StatusType * const status,
                  const std::string &extraData="") {
            ArgPuti(*this,name.c_str(),value,status);
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
        };
        void Put (const std::string &name, 
                  UINT32 value, 
                  StatusType * const status,
                  const std::string &extraData="") {
            ArgPutu(*this,name.c_str(),value,status);
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
        };
 
        void Put (const std::string &name, 
                  INT64 value, 
                  StatusType * const status,
                  const std::string &extraData="") {
            ArgPuti64(*this,name.c_str(),value,status);
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
        };
        void Put (const std::string &name, 
                  UINT64 value, 
                  StatusType * const status,
                  const std::string &extraData="") {
            ArgPutu64(*this,name.c_str(),value,status);
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
        };
        void Put (const std::string &name, 
                  float value, 
                  StatusType * const status,
                  const std::string &extraData="") {
            ArgPutf(*this,name.c_str(),value,status);
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
 
        };
        void Put (const std::string &name, 
                  double value, 
                  StatusType * const status,
                  const std::string &extraData="") {
            ArgPutd(*this,name.c_str(),value,status);
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
        };
        void Put(const char *name,
                 const std::string &value,
                 StatusType *status,
                  const std::string &extraData="") {
            ArgPutString(*this, name, value.c_str(), status);
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
 
        }
        /*
         * This actually replaced a version in the non STL section
         * above. It is needed to avoid ambiguous overloading cases
         */
        void Put (const char *name, 
                  const char *value, 
                  StatusType * const status, 
                  const std::string &extraData="") {
            ArgPutString(*this,name,value,status);
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
 
        };
 
        void Put(const std::string &name,
                 const std::string &value,
                 StatusType *status,
                  const std::string &extraData="") {
            ArgPutString(*this, name.c_str(), value.c_str(), status);
            if (extraData != "")
            {
                PutExtra(name, extraData, status);
            }
        }
        void Get (const std::string &name, bool * value, 
                                              StatusType * const status) const{
            unsigned short v;
            ArgGetus(*this,name.c_str(),&v,status);
            *value =  v ? true : false;
        }
        void Get (const std::string &name, char * value, StatusType * const status) const {
            ArgGetc(*this,name.c_str(),value,status);
        }
        void Get (const std::string &name, short * value, StatusType * const status) const {
            ArgGets(*this,name.c_str(),value,status);
        }
        void Get (const std::string &name, unsigned short * value, 
                                              StatusType * const status) const{
            ArgGetus(*this,name.c_str(),value,status);
        }
        void Get (const std::string &name, INT32 * value, 
                  StatusType * const status) const {
            Get(name.c_str(), value, status);
        }
        void Get (const std::string &name, UINT32 * value, 
                  StatusType * const status) const{
            Get(name.c_str(), value, status);
        }
        void Get (const std::string &name, INT64 * value, StatusType * const status) const {
            ArgGeti64(*this,name.c_str(),value,status);
        }
        void Get (const std::string &name, UINT64 * value, StatusType * const status) const {
            ArgGetu64(*this,name.c_str(),value,status);
        }
        void Get (const std::string &name, float * value, StatusType * const status) const {
            ArgGetf(*this,name.c_str(),value,status);
        }
        void Get (const std::string &name, double * value, StatusType * const status) const {
            ArgGetd(*this,name.c_str(),value,status);
        }
        void Get(const char *name,
                       std::string *value,
                 StatusType *status,
                 int buflen = 100) const {
            
            /* Find the item we are interested in */
            Arg ItemId(*this, name, status);
            if (*status != STATUS__OK) return;
 
            char tname[SDS_C_NAMELEN];
            SdsCodeType code;
            long ndims;
            unsigned long dims[SDS_C_MAXARRAYDIMS];
 
            /* Get details on this item */
            ItemId.Info(tname, &code, &ndims, dims, status);
            if (*status != STATUS__OK) return;
 
            if ((code == SDS_CHAR)&&(ndims == 1))
            {
                /* Character array.  Ensure we have sufficent space */
                buflen = dims[0] + 1;
            }
            char *buffer;
            buffer = new char[buflen];
            if (buffer == 0)
            {
                *status = ARG__MALLOCERR;
                return;
            }
            ArgGetString(*this, name, buflen, buffer, status);
            if (*status == STATUS__OK)
                *value = buffer;
            delete[] buffer;
 
        }
 
        /*
         * Interface to the above were the name string is a std::string.
         */
        void Get(const std::string &name,
                       std::string *value,
                 StatusType *status,
                 int buflen = 100) const {
            Get(name.c_str(), value, status, buflen);
        }
 
 
        void ToString(std::string *s, StatusType * const status, int maxlen=200)
        {
            /*
             * Allocate some space to store the string in.
             */
            char *string = new char[maxlen];
            int length=0;
            /*
             * ArgToString() does the job for us.
             */
            ArgToString(*this,maxlen,&length,&string[0],status);
            if (*status != STATUS__OK)
            {
                delete[] string;
                *s = "";
                return;
            }
            *s = string;
            delete[] string;
        }
        /* More modern naming of this */
        void toString(std::string *s, StatusType * const status, int maxlen=200) {
            ToString(s, status, maxlen);
        }
 
#endif
 
}; /* class */
 
 
#endif
 
#endif