DRAMA C++ Intro   Class Hierarchy   Alphabetical List of types   List of Classes   File List   Class Member Index   File Members Index   Related Pages  

SdsId Class Reference

#include <sds.h>

Inheritance diagram for SdsId:

Arg List of all members.

Detailed Description

A C++ Interface to the handling SDS structures.

The class SdsId provides a C++ interface to the AAO DRAMA SDS Library. See The SDS Specification for more details on SDS itself.

An assortment of constructors are provided. Some of these access components of structures, some access external items and some create new SDS structures. Each SdsId class object contains an SDS id which refers to an SDS structure, rather then a complete SDS structure and more then on SdsId can refer to the one underlying SDS structure. Additionally, details about what to do when the object goes out of scope are maintained, ensuring the the destructor cleans up correctly.

If any of the contructors fail, then the current implementation will set the inherited status argument bad rather then throwing an exception. The object is still constructed in this case but will refer to an invalid SDS id, causing any other methods to fail (by setting status bad). If the inherited status is not equal to STATUS__OK on entry to any method with an inherited status argument, then the method returns immediately.

The various methods of the class implement those SDS functions which do not return new SDS id's (SDS functions which return new SDS id's are implemented as constructors).

The destructor will normally delete the underlying SDS item and and free the SDS id, when appropiate. These operations are normally dependent on how the item was constructed, but can be changed if required (which might be required if the underlying SDS id is to be passed to a C function).

Assignment and copying of these items is prohibited by making the operators private. This is done since it is not clear what the user will expect from some operations. (for example, in a copy constructor, should the item be copied with the C routine SdsCopy() or just a new id to the same item generated. SDS does not even support the later. Also, management of the inherited status is a problem).

You can pass items to subroutines by reference or pointer to get around the copy problem. A constructor which creates a copy of an existing object can be used in the place of assignment in many cases. You can use the member functions ShallowCopy() (which just copies the Sds id itself) and DeepCopy(), to get a copy in an explicit maner in other cases.

See also:
Arg , SDS Specification , DRAMA C++ interface , DRAMA DITS Specification


Public Methods

 SdsId (const SdsIdType item=0, const bool free=false, const bool del=false, const bool readfree=false)
 Construct an SdsId item from an existing C language SDS id.

 SdsId (void *const data, StatusType *const status, const bool import=false)
 Constructor that accesses an exported SDS structure in a byte stream.

 SdsId (const void *const data, StatusType *const status)
 Constructor that imports a previously exported SDS structure from a const byte stream.

 SdsId (const char *const filename, StatusType *const status)
 Constructor which creates an SDS Id after reading a structure from a file.

 SdsId (const SdsId &parent_id, const char *const name, const SdsCodeType code, StatusType *const status, const long nextra=0, const char *const extra=0)
 Constructor which creates a new (non-array) child item.

 SdsId (const char *const name, const SdsCodeType code, StatusType *const status, const long nextra=0, const char *const extra=0)
 Constructor which creates a new (non-array) top-level item.

 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)
 Constructor which creates a new array child 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)
 Constructor which creates a new array top-level item.

 SdsId (const SdsId &array_id, const long nindicies, const unsigned long *const indicies, StatusType *const status)
 Constructor that returns a cell of an existing array id.

 SdsId (const SdsId &source, StatusType *const status)
 SdsId Copy constructor.

 SdsId (const SdsId &source, const char *const name, StatusType *const status)
 Constructor which returns a reference to a named item.

 SdsId (const SdsId &source, const long index, StatusType *const status)
 Constructor which returns an id to a structured item indexed by position.

virtual ~SdsId ()
 SdsId Destructor.

void SetFree ()
 Indicate the underlying SDS item should be free-ed when the SdsId object is destroyed.

void SetDelete ()
 Indicate the underlying SDS structure should be deleted when the SdsId object is destroyed.

void ClearDelete ()
 Indicate the underlying SDS structure should NOT be deleted when the SdsId object is desroyed.

void Outlive ()
 Force the actual SDS ID to outlive the SdsId variable.

virtual void Delete (StatusType *const status)
 Delete the SDS item.

void Export (const unsigned long length, void *const data, StatusType *const status)
 Export the SDS structure into a buffer.

void ExportDefined (const unsigned long length, void *const data, StatusType *const status)
 Export the SDS structure into a buffer, defining any undefined data.

void Extract (StatusType *const status)
 Extract the SDS structure from its parent.

void Flush (StatusType *const status)
 Flush data modified by pointer.

virtual void Get (const unsigned long length, void *const data, StatusType *const status, unsigned long *actlen=0, const unsigned long offset=0) const
 Get data from an SDS item.

void GetExtra (const unsigned long length, char *const extra, StatusType *const status, unsigned long *actlen=0) const
 Get extra data from an SDS item.

void Info (char *const name, SdsCodeType *const code, long *const ndims, unsigned long *const dims, StatusType *const status) const
 Return information about an SDS item.

void GetName (char *const name, StatusType *const status) const
 Return the name of the SDS item.

void Code (SdsCodeType *const code, StatusType *const status) const
 Return the code of the SDS item.

void Dims (long *const ndims, unsigned long *const dims, StatusType *const status) const
 Return the dimensions of the SDS item.

void Insert (SdsId &to_insert, StatusType *const status)
 Insert an SDS object into this object.

void Insert (SdsId &to_insert, const long ndims, const unsigned long *const dims, StatusType *const status)
 Insert an SDS object into this object, which is a structured array.

void FillArray (const SdsId &elem, StatusType *const status)
 Fill out the contents of this object, which is a structured array.

void Pointer (void **data, StatusType *const status, unsigned long *length=0)
 Object a pointer to the data area of a primitive SDS item.

virtual void Put (const unsigned long length, void *const data, StatusType *const status, const unsigned long offset=0)
 Put data into an SDS item.

void PutExtra (const long nextra, const char *const extra, StatusType *const status)
 Put extra data into an SDS item.

void Rename (const char *const name, StatusType *const status)
 Rename the SDS item.

void Resize (const long ndims, const unsigned long *dims, StatusType *const status)
 Change the dimensions of an SDS array.

void Size (unsigned long *const bytes, StatusType *const status) const
 Return the size of an SDS structure, as required for exporting.

void SizeDefined (unsigned long *const bytes, StatusType *const status) const
 Return the size of an SDS structure, as required for exporting defined.

void List (StatusType *const status) const
 List the contents of the structure to standard output.

void Write (const char *const filename, StatusType *const status) const
 Write the contents of the structure to a file.

void IsExternal (int *const external, StatusType *const status) const
 Determine if the SDS structure is external.

void GetExternInfo (void **data, StatusType *const status) const
 Return the address of an external item.

 operator SdsIdType (void) const
 Operator which returns the underlying SDS id.

 operator bool (void) const
 Operator which tests if an item is valid.

SdsIdType COut (const bool outlives, bool *const free=0, bool *const del=0, bool *const readfree=0)
 Return this item as an SdsIdType for return to C code.

void COut (const bool outlives, SdsIdType *item, bool *const free=0, bool *const del=0, bool *const readfree=0)
 Return this item as an SdsIdType for return to C code.

void ShallowCopy (SdsId &source, const bool outlives=true)
 Shallow copy from SdsId.

void DeepCopy (const SdsId &source, StatusType *const status)
 Replace the item refered to by this object by a deep copy of source.

void ShallowCopy (const SdsIdType source, const bool free=false, const bool del=false, const bool readfree=false)
 Shallow copy from SdsIdType.

void DeepCopy (const SdsIdType source, StatusType *status)
 Replace the item refered to by this object by a deep copy of source.

template<typename T> void ArrayAccess (SdsArrayAccessHelper< T > *const data, StatusType *const status)
 Access the data of a single dimensional SDS array item.

template<typename T> void ArrayAccess (const unsigned long expitems, SdsArrayAccessHelper< T > *const data, StatusType *const status)
 Access the data of a single dimensional SDS array.

template<typename T> void ArrayAccess (SdsArrayAccessHelper< T > *const data, long ndims, unsigned long dims[], StatusType *const status)
 Access the data of an SDS array.

template<typename T> void ArrayAccess (SdsArrayAccessHelper< T > *const data, long *ndims, unsigned long dims[], StatusType *const status)
 Access the data of an SDS array.

Constructor & Destructor Documentation

SdsId::SdsId (  const SdsIdType    item = 0,
const bool    free = false,
const bool    del = false,
const bool    readfree = false
)  [inline]
 

Construct an SdsId item from an existing C language SDS id.

This SdsId constructor that takes an existing SDS id (C style) and creates an SdsId class object which refers to that SDS id. You must explictly specify if the item is to be free-ed and/or deleted when the object's destructor is invoked, and what you do depends on when what other code may do with item. The del and readfree are mutually exclusive, through this is currently not checked in this implementation.

Parameters:
item  The SdsIdType of the item. If 0 (the default), the SdsId object constructed does not refer to any SDS item. This is normally only used when we want an argument to pass (by pointer) to a function which will use SdsId::ShallowCopy or SdsId::DeepCopy to set the ID.
free  Set true to invoke SdsFreeId() on the ID when the object is destroyed. The default is false.
del  Set true to invoke SdsDelete() on the ID when the object is destroyed. The default is false.
readfree  Set true to invoke SdsReadFree() on the ID when the object is destroyed. The default is false.

SdsId::SdsId (  void *const    data,
StatusType *const    status,
const bool    import = false
)  [inline]
 

Constructor that accesses an exported SDS structure in a byte stream.

This constructor uses SdsImport() or SdsAccess() to get access an SDS structure stored in an external byte stream

See also:
SdsImport(). , SdsAccess().
Parameters:
data  A pointer to a byte stream created with SdsExport() or SdsId::Export .
status  Inherited status.
import  If true, then import the structure such that is an internal SDS structure. This allows the structure to be modified in any fashion, but is slower and requires more memory.

SdsId::SdsId (  const void *const    data,
StatusType *const    status
)  [inline]
 

Constructor that imports a previously exported SDS structure from a const byte stream.

This constructor uses SdsImport() to get access an SDS structure stored in an const external byte stream. Note that since the data is const, only a SdsImport() is possible.

See also:
SdsImport().
Parameters:
data  A pointer to a byte stream created with SdsExport() or SdsId::Export .
status  Inherited status.

SdsId::SdsId (  const char *const    filename,
StatusType *const    status
)  [inline]
 

Constructor which creates an SDS Id after reading a structure from a file.

The specified file should contain an SDS structure created using SdsWrite() or SdsId::Write .

See also:
SdsId::Write , SdsRead()
Parameters:
filename  Name of the file.
status  Inherited status.

SdsId::SdsId (  const SdsId &    parent_id,
const char *const    name,
const SdsCodeType    code,
StatusType *const    status,
const long    nextra = 0,
const char *const    extra = 0
)  [inline]
 

Constructor which creates a new (non-array) child item.

This contructor creates a new SDS item which is a child of the specified SDS item in the specified SdsId object.

See also:
SdsNew()
Parameters:
parent_id  The parent SDS item.
name  The name for the new SDS item.
code  The SDS code for the new item.
status  Inherited status.
nextra  The about of extra data, default to 0 (no extra data).
extra  The extra data.

SdsId::SdsId (  const char *const    name,
const SdsCodeType    code,
StatusType *const    status,
const long    nextra = 0,
const char *const    extra = 0
)  [inline]
 

Constructor which creates a new (non-array) top-level item.

This constructor creates a new SDS top-level SDS item.

Parameters:
name  The name for the new SDS item.
code  The SDS code for the new item.
status  Inherited status.
nextra  The about of extra data, default to 0 (no extra data).
extra  The extra data.

SdsId::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
)  [inline]
 

Constructor which creates a new array child item.

This contructor creates a new SDS structure array which is a child of the specified SDS item in the specified SdsId object.

See also:
SdsNew()
Parameters:
parent_id  The parent SDS item.
name  The name for the new SDS item.
code  The SDS code for the new item.
ndims  The number of dimensions, 1 through 7.
dims  An array giving each dimension.
status  Inherited status.
nextra  The about of extra data, default to 0 (no extra data).
extra  The extra data.

SdsId::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
)  [inline]
 

Constructor which creates a new array top-level item.

This constructor creates a new SDS top-level SDS structure array.

See also:
SdsNew()
Parameters:
name  The name for the new SDS item.
code  The SDS code for the new item.
ndims  The number of dimensions, 1 through 7.
dims  An array giving each dimension.
status  Inherited status.
nextra  The about of extra data, default to 0 (no extra data).
extra  The extra data.

SdsId::SdsId (  const SdsId &    array_id,
const long    nindicies,
const unsigned long *const    indicies,
StatusType *const    status
)  [inline]
 

Constructor that returns a cell of an existing array id.

This constructor is used to access a specified cell of an existing SDS structure array.

See also:
SdsCell().
Parameters:
array_id  An ID which refers to a structure array.
nindicies  The number of indicies in the array
indicies  An array giving the indicies of the cell in question.
status  Inherited status.

SdsId::SdsId (  const SdsId &    source,
StatusType *const    status
)  [inline]
 

SdsId Copy constructor.

This constructor is used to generate a copy of an existing SDS structure. This is a deep copy - a new internal SDS item is created.

See also:
SdsCopy().
Parameters:
source  The SDS item to be copied.
status  Inherited status.

SdsId::SdsId (  const SdsId &    source,
const char *const    name,
StatusType *const    status
)  [inline]
 

Constructor which returns a reference to a named item.

This constructor searches an existing SDS item for a item with a specified name and creates a reference to it.

See also:
SdsFind()
Parameters:
source  The SDS item to find name within.
name  The name of the SDS item to find.
status  Inherited status.

SdsId::SdsId (  const SdsId &    source,
const long    index,
StatusType *const    status
)  [inline]
 

Constructor which returns an id to a structured item indexed by position.

This constructor uses the specified index to find an item within an SDS structure.

See also:
SdsIndex()
Parameters:
source  The SDS item to index within.
index  The index of the item fo find. Items in a structure are numbered in order of creation starting with one.
status  Inherited status.

virtual SdsId::~SdsId (    )  [inline, virtual]
 

SdsId Destructor.

The SdsDelete()/ SdsReadFree() may be invoked on the underlying SDS id as may SdsFreeId(). What is to happen depends on how the item was constructed or how the flags were changed. In general, the required result is achived.

See also:
SdsId::SetFree() , SdsId::SetDelete() , SdsId::ClearDelete() , SdsId::Outlive() , SdsFreeId() , SdsDelete() , SdsReadFree()

Member Function Documentation

template<typename T>
void SdsId::ArrayAccess (  SdsArrayAccessHelper< T > *const    data,
long *    ndims,
unsigned long    dims[],
StatusType *const    status
)  [inline]
 

Access the data of an SDS array.

Accesses an array using an SdsArrayAccessHelper of the appropiate type. This version allows access to an array of any dimensions and number of dimensions. Various other versions also exist.

On return, "data[index]" can be used to access the array element at the specified index. See the SdsArrayAccessHelper class for more information. Note that mult-idimensional arrays must be indexed by calculating the single dimensional index (otherwise the type definitions are too hard).

In this example, SdsArrayShort is a sub-class of SdsArrayAccessHelper. 

    SdsId structure;
    ...
    long ndims;
    unsigned long dims[SDS_C_MAXARRAYDIMS];
    SdsArrayShort value;
    structure.ArrayAccess(&value, &ndims, dims, status);
    unsigned long count = value.Size();
    if (*status == STATUS__OK)
    {
       for (unsigned long i = 0; i < count ; ++i)
         printf("Element ld = d\n", i, (int)value[i]);
    }

Remarks:
Only available if the marcro DRAMA_ALLOW_CPP_STDLIB is defined.
See also:
SdsArrayAccessHelper
Parameters:
data  A pointer to an object which allows you to access the underlying SDS data. It must be a sub-class of SdsArrayAccessHelper appropiate for type T.
ndims  The number of dimensions is written here.
dims  The dimensions are written to this array. Must have space for 7 dimensions.
status  Inherited status. In addition to the values returned by SdsInfo() and SdsPointer(), the values SDS__TYPE, SDS__NOTARR and SDS__INVDIMS may be returned.

template<typename T>
void SdsId::ArrayAccess (  SdsArrayAccessHelper< T > *const    data,
long    ndims,
unsigned long    dims[],
StatusType *const    status
)  [inline]
 

Access the data of an SDS array.

Accesses an array using an SdsArrayAccessHelper of the appropiate type. This version allows access to an array of a specified number of dimensions. Various other versions also exist.

On return, "data[index]" can be used to access the array element at the specified index. See the SdsArrayAccessHelper:: class for more information. Note that Multidimensional arrays must be indexed by calculating the equivalent single dimensional index (otherwise the type definitions are too hard).

In this example, SdsArrayShort is a sub-class of SdsArrayAccessHelper. 

    SdsId structure;
    ...
    unsigned long dims[SDS_C_MAXARRAYDIMS];
    SdsArrayShort value;
    structure.ArrayAccess(&value, 1, dims, status);
    if (*status == STATUS__OK)
    {
       for (unsigned long i = 0; i < dims[0] ; ++i)
         printf("Element ld = d\n", i, (int)value[i]);
    }

Remarks:
Only available if the marcro DRAMA_ALLOW_CPP_STDLIB is defined.
See also:
SdsArrayAccessHelper
Parameters:
data  A pointer to an object which allows you to access the underlying SDS data. It must be a sub-class of SdsArrayAccessHelper appropiate for type T.
ndims  The number of dimensions there should be in the structure.
dims  The dimensions are written to this array. Must have space for 7 dimensions.
status  Inherited status. In addition to the values returned by SdsInfo() and SdsPointer(), the values SDS__TYPE, SDS__NOTARR and SDS__INVDIMS may be returned.

template<typename T>
void SdsId::ArrayAccess (  const unsigned long    expitems,
SdsArrayAccessHelper< T > *const    data,
StatusType *const    status
)  [inline]
 

Access the data of a single dimensional SDS array.

Accesses an array using an SdsArrayAccessHelper of the appropiate type. This version allows access to a one dimensional array of any size. Various other versions also exist.

On return, "data[index]" can be used to access the array element at the specified index.

In this version uses the number of elements in the SDS array must match the specified number of elements, otherwise status is set to SDS__INVDIMS.

Remarks:
Only available if the marcro DRAMA_ALLOW_CPP_STDLIB is defined.
In this example, SdsArrayShort is a sub-class of SdsArrayAccessHelper. 
    SdsId structure;
    ...
    SdsArrayShort value;
    structure.ArrayAccess(10, &value, status);
    if (*status == STATUS__OK)
    {
       for (unsigned long i = 0; i < 10 ; ++i)
         printf("Element ld = d\n", i, (int)value[i]);
    }
*
See also:
SdsArrayAccessHelper
Parameters:
expitems  The number of items expected in the array.
data  A pointer to an object which allows you to access the underlying SDS data. It must be a sub-class of SdsArrayAccessHelper appropiate for type T.
status  Inherited status. In addition to the values returned by SdsInfo() and SdsPointer(), the values SDS__TYPE, SDS__NOTARR and SDS__INVDIMS may be returned.

template<typename T>
void SdsId::ArrayAccess (  SdsArrayAccessHelper< T > *const    data,
StatusType *const    status
)  [inline]
 

Access the data of a single dimensional SDS array item.

Accesses an array using an SdsArrayAccessHelper of the appropiate type. This version allows access to a one dimensional array of any size. Various other versions also exist.

On return, "data[index]" can be used to access the array element at the specified index. See the SdsAccess ArrayHelper:: class for more information.

This version uses the number of elements in the SDS array.

In this example, SdsArrayShort is a sub-class of SdsArrayAccessHelper. 

    SdsId structure;
    ...
    SdsArrayShort value;
    structure.ArrayAccess(&value, status);
    unsigned long count = value.Size();
    if (*status == STATUS__OK)
    {
       for (unsigned long i = 0; i < count ; ++i)
         printf("Element ld = d\n", i, (int)value[i]);
    }

Remarks:
Only available if the marcro DRAMA_ALLOW_CPP_STDLIB is defined.
See also:
SdsArrayAccessHelper
Parameters:
data  A pointer to an object which allows you to access the underlying SDS data. It must be a sub-class of SdsArrayAccessHelper appropiate for type T.
status  Inherited status. In addition to the values returned by SdsInfo() and SdsPointer(), the values SDS__TYPE, SDS__NOTARR and SDS__INVDIMS may be returned.

void SdsId::ClearDelete (    )  [inline]
 

Indicate the underlying SDS structure should NOT be deleted when the SdsId object is desroyed.

This should be considered if the SDS object refered to was created when the SdsId object is created and must outlive the object.

See also:
SdsId::OutLive()

void SdsId::Code (  SdsCodeType *const    code,
StatusType *const    status
)  const [inline]
 

Return the code of the SDS item.

Just return the code of the underlying SDS item.

Note that if you want more then one of the items returned by SdsId::GetName, SdsId::Code and SdsId::Dims, then use SdsId::Info, it is more efficent.

See also:
SdsId::Info , SdsInfo()
Parameters:
code  The SDS item code is returned here..
status  Inherited status.

void SdsId::COut (  const bool    outlives,
SdsIdType *    item,
bool *const    free = 0,
bool *const    del = 0,
bool *const    readfree = 0
)  [inline]
 

Return this item as an SdsIdType for return to C code.

Deprecated:
Please use the version which returns the value.

This method will setup for and obtain details of this item for return of this item using an SdsIdType. Of particular note - if outlives is true, the SdsIdType item returned by this is considered to outlive this object and we leave the freeing of the id etc up to the caller, who can use the other variables to work out what to do.

Parameters:
outlives  If true, then the returned value will outlive this object and this object is modified to reflect this.
item  the SDS item is returned here.
free  If specified, set true to indicate that the destructor for this object would have invoked SdsFreeId() on the underlying SDS ID. If outlives is true, this won't now happen.
del  If specified, set true to indicate that the destructor for this object would have invoked SdsDelete() on the underlying SDS ID. If outlives is true, this won't now happen.
readfree  If specified, set true to indicate that the destructor for this object would have invoked SdsReadFree() on the underlying SDS ID. If outlives is true, this won't now happen.
Returns:
The underlying SDS ID value.

SdsIdType SdsId::COut (  const bool    outlives,
bool *const    free = 0,
bool *const    del = 0,
bool *const    readfree = 0
)  [inline]
 

Return this item as an SdsIdType for return to C code.

This method will setup for and obtain details of this item for return of this item using an SdsIdType. Of particular note - if outlives is true, the SdsIdType item returned by this is considered to outlive this object and we leave the freeing of the id etc up to the caller, who can use the other variables to work out what to do. If outlives is false, can method be used as an enquiry for what is to happen when the destructor is invoked.

Parameters:
outlives  If true, then the returned value will outlive this object and this object is modified to reflect this.
free  If specified, set true to indicate that the destructor for this object would have invoked SdsFreeId() on the underlying SDS ID. If outlives is true, this won't now happen.
del  If specified, set true to indicate that the destructor for this object would have invoked SdsDelete() on the underlying SDS ID. If outlives is true, this won't now happen.
readfree  If specified, set true to indicate that the destructor for this object would have invoked SdsReadFree() on the underlying SDS ID. If outlives is true, this won't now happen.
Returns:
The underlying SDS ID value.

void SdsId::DeepCopy (  const SdsIdType    source,
StatusType *    status
)  [inline]
 

Replace the item refered to by this object by a deep copy of source.

The SdsCopy() function is used to create a copy.

Parameters:
source  The item to create a copy of.
status  Inherited status.

void SdsId::DeepCopy (  const SdsId &    source,
StatusType *const    status
)  [inline]
 

Replace the item refered to by this object by a deep copy of source.

The SdsCopy() function is used to create a copy.

Remarks:
If source is this item, then SdsCopy() is only invoked if this is an external SDS item. The result of such an operation is that "this" will always refer to something you can modify the structure of, after a call to DeepCopy().
Parameters:
source  The item to create a copy of.
status  Inherited status.

virtual void SdsId::Delete (  StatusType *const    status )  [inline, virtual]
 

Delete the SDS item.

SdsDelete() is invoked on the SDS ID refered to by the Object. This is generally used to delete items which are a component of other objects. The ID is also free-ed if the approiate flag is set

After this method is invoked, this object is invalid and many methods will now fail. But you can use the copy methods to insert a new item.

See also:
SdsDelete() , SdsFreeId()
Parameters:
status  Inherited status.

void SdsId::Dims (  long *const    ndims,
unsigned long *const    dims,
StatusType *const    status
)  const [inline]
 

Return the dimensions of the SDS item.

Just return the dimensions of the underlying SDS item.

Note that if you want more then one of the items returned by SdsId::GetName, SdsId::Code and SdsId::Dims, then use SdsId::Info, it is more efficent.

See also:
SdsId::Info , SdsInfo()
Parameters:
ndims  The number of dimensions is returned here, 0 if the item is not an array, otherwise, 1 through 7.
dims  The dimensions are retuned here. This should be an array of 7 items.
status  Inherited status.

void SdsId::Export (  const unsigned long    length,
void *const    data,
StatusType *const    status
)  [inline]
 

Export the SDS structure into a buffer.

The SDS structure refered to by this SdsId object is exported into the specified buffer.

Note that if any of the underlying data is not defined (say because you created a new item but have not yet put any data into it) then the size will not include space for the data itself. This is acceptable to SDS but may not be what you expect. To create the required space in the exported object, use the SdsId::ExportDefined method.

See also:
SdsExport() , SdsId::ExportDefined
Parameters:
length  The length of the buffer. Should be the value returned by SdsSize() or SdsId::Size
data  The buffer to write the data into. Should be of at least the size specified by length.
status  Inherited status.

void SdsId::ExportDefined (  const unsigned long    length,
void *const    data,
StatusType *const    status
)  [inline]
 

Export the SDS structure into a buffer, defining any undefined data.

The SDS structure refered to by this SdsId object is exported into the specified buffer, with any undefined data defined.

Data may be undefined if you created a new item but have not yet put any data into it. The standard Export() method does not allow space for this data, but this method does.

See also:
SdsExportDefined() , SdsId::Export
Parameters:
length  The length of the buffer. Should be the value returned by SdsSizeDefined() or SdsId::SizeDefined
data  The buffer to write the data into. Should be of at least the size specified by length.
status  Inherited status.

void SdsId::Extract (  StatusType *const    status )  [inline]
 

Extract the SDS structure from its parent.

This method is normally applied to an SdsId object which refers to a child of another SDS structure. This method extracts the child to create a new top-level SDS structure

See also:
SdsExtract() , SdsId::Pointer , SdsPointer()
Parameters:
status  Inherited status.

void SdsId::FillArray (  const SdsId &    elem,
StatusType *const    status
)  [inline]
 

Fill out the contents of this object, which is a structured array.

This routine will fill out an array of structures item with the copies of a specified struture.

See also:
SdsFillArray() , SdsId::Insert(SdsId &to_insert, const long ndims, const unsigned long *const dims, StatusType *const status)
Parameters:
elem  The item to copy into the structure.
status  Inherited status.

void SdsId::Flush (  StatusType *const    status )  [inline]
 

Flush data modified by pointer.

When the data of an SDS is modified via a pointer obtained by SdsPointer() or SdsId::Pointer, then this method should be used to ensure the data is updated correctly.

This is currently a null method for all machines on which SDS is currently implemented, but may be required in the future.

See also:
SdsFlush()
Parameters:
status  Inherited status.

virtual void SdsId::Get (  const unsigned long    length,
void *const    data,
StatusType *const    status,
unsigned long *    actlen = 0,
const unsigned long    offset = 0
)  const [inline, virtual]
 

Get data from an SDS item.

This method accesses the data from an SDS item. The data is copied into the specified buffer.

Note that data from nested structures is also copied. Please see the SDS manual for more details on Get operations.

See also:
SdsGet() , SdsId::Pointer , SdsId::Put , SdsPut()
Parameters:
length  The amount of data to fetch.
data  The buffer to put the data info, must of of size length or greater.
status  Inherited status.
actlen  The actual amount of data retrived is written here. If not supplied, this information is not returned.
offset  An offset into the SDS structure to start fetch from, in bytes

Reimplemented in Arg.

void SdsId::GetExternInfo (  void **    data,
StatusType *const    status
)  const [inline]
 

Return the address of an external item.

This method is used to determine the address of the buffer containing an external item, if this item refers to an external item. This is the value given the contructor which accessed this item.

See also:
SdsId::SdsId(void *const data, StatusType *const status, const bool import)
Parameters:
data  The address is written here.
status  Inherited status.

void SdsId::GetExtra (  const unsigned long    length,
char *const    extra,
StatusType *const    status,
unsigned long *    actlen = 0
)  const [inline]
 

Get extra data from an SDS item.

This method accesses the extra data from an SDS item. The data is copied into the specified buffer.

See also:
SdsGetExtra() , SdsId::PutExtra , SdsPutExtra()
Parameters:
length  The amount of data to fetch.
extra  The buffer to fetch the data into, must of of size length or greater.
status  Inherited status.
actlen  The actual amount of data retrived is written here. If not supplied, this information is not returned.

void SdsId::GetName (  char *const    name,
StatusType *const    status
)  const [inline]
 

Return the name of the SDS item.

Just return the name of the underlying SDS item.

Note that if you want more then one of the items returned by SdsId::GetName, SdsId::Code and SdsId::Dims, then use SdsId::Info, it is more efficent.

See also:
SdsId::Info , SdsInfo()
Parameters:
name  The name of the SDS item is returned here. There should be space for SDS_C_NAMELEN (16) 16 bytes.
status  Inherited status.

void SdsId::Info (  char *const    name,
SdsCodeType *const    code,
long *const    ndims,
unsigned long *const    dims,
StatusType *const    status
)  const [inline]
 

Return information about an SDS item.

This method returns all the standard information about an SDS item.

See also:
SdsInfo() , SdsId::Code , SdsId::Dims , SdsId::Dims
Parameters:
name  The name of the SDS item is returned here. There should be space for SDS_C_NAMELEN (16) 16 bytes.
code  The SDS item code is returned here..
ndims  The number of dimensions is returned here, 0 if the item is not an array, otherwise, 1 through 7.
dims  The dimensions are retuned here. This should be an array of 7 items.
status  Inherited status.

void SdsId::Insert (  SdsId &    to_insert,
const long    ndims,
const unsigned long *const    dims,
StatusType *const    status
)  [inline]
 

Insert an SDS object into this object, which is a structured array.

This object inserts a top level object into a structure array at a position specified by its indices. It deletes any object that is currently at that position.

See also:
SdsInsertCell() , SdsId::FillArray
Parameters:
to_insert  The object to insert.
ndims  The number of dimensions to the array. 1 through 7.
dims  The cell indicies.
status  Inherited status.

void SdsId::Insert (  SdsId &    to_insert,
StatusType *const    status
)  [inline]
 

Insert an SDS object into this object.

This method inserts an existing SDS structure into the SDS structure refered to by this object.

See also:
SdsInsert()
Parameters:
to_insert  The object to insert.
status  Inherited status.

void SdsId::IsExternal (  int *const    external,
StatusType *const    status
)  const [inline]
 

Determine if the SDS structure is external.

This method is used to determine if the SDS object refered to by this object is an external object. Note that external objects cannot have their structure modified.

See also:
SdsIsExternal()
Parameters:
external  A non-zero value is written here if the object is external
status  Inherited status.

void SdsId::List (  StatusType *const    status )  const [inline]
 

List the contents of the structure to standard output.

See also:
SdsList()
Parameters:
status  Inherited status.

Reimplemented in Arg.

SdsId::operator bool (  void    )  const [inline]
 

Operator which tests if an item is valid.

Returns:
True if an item appears to be valid (the underlying SDS ID is non-zero).

SdsId::operator SdsIdType (  void    )  const [inline]
 

Operator which returns the underlying SDS id.

This operator allows the SdsId object to be used in calls to functions which expect an SdsIdType argument. Note that you must ensure that object is nether deleted or free-ed by whatever uses it. See SdsId::COut if that might happen.

See also:
SdsId::COut
Returns:
The underlying SDS ID value.

void SdsId::Outlive (    )  [inline]
 

Force the actual SDS ID to outlive the SdsId variable.

This method should be invoked if it is determined that the underlying SDS ID/Structure should outlive the SdsId object. Typically, this might be done if the underlying ID is passed to some other function

void SdsId::Pointer (  void **    data,
StatusType *const    status,
unsigned long *    length = 0
)  [inline]
 

Object a pointer to the data area of a primitive SDS item.

Return a pointer to the data of a primitive item. If the data item is undefined and the object is internal, storage for the data will be created. This can only be used with primitive items, not with structures.

If necessary (e.g. if the data originated on a machine with different architecture) the data for the object is converted (in place) from the format stored in the data item to that required for the local machine

If the data pointed to by the pointer is updated by a calling program, the program should then call the function SdsFlush()/ SdsId::Flush to ensure that the data is updated in the original structure. This is necessary because implementations on some machine architectures may have to use a copy of the data rather than the actual data when returning a pointer.

See also:
SdsPointer()
Parameters:
data  The address of a item to return the pointer to.
status  Inherited status.
length  If specified, the length of the data is returned here.

virtual void SdsId::Put (  const unsigned long    length,
void *const    data,
StatusType *const    status,
const unsigned long    offset = 0
)  [inline, virtual]
 

Put data into an SDS item.

This method put the data into an SDS item. The data is copied into the specified buffer.

Note that data from nested structures is also copied. Please see the SDS manual for more details on Put operations.

See also:
SdsPut() , SdsId::Get , SdsId::Pointer , SdsGet()
Parameters:
length  The amount of data to put.
data  The buffer of the data, must of of size length or greater.
status  Inherited status.
offset  An offset into the SDS structure to start fetch from, in bytes

Reimplemented in Arg.

void SdsId::PutExtra (  const long    nextra,
const char *const    extra,
StatusType *const    status
)  [inline]
 

Put extra data into an SDS item.

This method puts the extra data from an SDS item. The data is copied into the specified buffer.

See also:
SdsPutExtra() , SdsId::GetExtra , SdsGetExtra()
Parameters:
nextra  The amount of data to put
extra  The buffer of the data, must of of size length or greater.
status  Inherited status.

void SdsId::Rename (  const char *const    name,
StatusType *const    status
)  [inline]
 

Rename the SDS item.

See also:
SdsRename()
Parameters:
name  The new name, must be less then SDS_C_NAMELEN (16) bytes including the null terminator.
status  Inherited status.

void SdsId::Resize (  const long    ndims,
const unsigned long *    dims,
StatusType *const    status
)  [inline]
 

Change the dimensions of an SDS array.

This object must be an SDS array (either primitive or structured). This method resizes the arrary. Note that it does not move the data elements in the storage representing the array, so there is no guarantee that after resizing the array the same data will be found at the same array index positions as before resizing, though this will be the case for simple changes such as a change in the last dimension only.

If the size of a primitive array is increased the contents of the extra locations is undefined. Decreasing the size causes the data beyond the new limit to be lost.

If a structure array is extended the new elements created will be empty structures. If a structure array is decreased in size, the lost elements and all their components will be deleted.

See also:
SdsResize()
Parameters:
ndims  The number of dimensions
dims  The new dimensions
status  Inherited status.

void SdsId::SetDelete (    )  [inline]
 

Indicate the underlying SDS structure should be deleted when the SdsId object is destroyed.

See also:
SdsId::OutLive()

void SdsId::SetFree (    )  [inline]
 

Indicate the underlying SDS item should be free-ed when the SdsId object is destroyed.

See also:
SdsId::OutLive()

void SdsId::ShallowCopy (  const SdsIdType    source,
const bool    free = false,
const bool    del = false,
const bool    readfree = false
)  [inline]
 

Shallow copy from SdsIdType.

Copy an SdsIdType item into this object. The existing SDS ID refered to by this object is first tidied up correctly. After the copy, both the source and this object refer to the same SDS structure. The caller must indicate who has responsibility for cleaning up by setting appropiate flags.

See also:
SdsId::DeepCopy
Parameters:
source  The Sds object to copy.
free  If set true, this object will free the SDS id when it is destroyed.
del  If set true, this object will delete the underlying SDS object when it is destroyed.
readfree  If set true, this object will call SdsReadFree() when the object is destroyed.

void SdsId::ShallowCopy (  SdsId &    source,
const bool    outlives = true
)  [inline]
 

Shallow copy from SdsId.

Copy another SdsId item into this object. The existing SDS ID refered to by this object is first tidied up correctly. After the copy, both the source and this object refer to the same SDS structure. The outlives parameter must be set correctly to determine which one destroys the underlying SDS structure.

Note that if outlives is true, then write access is required to source - hence it cannot be const.

See also:
SdsId::DeepCopy
Parameters:
source  The Sds object to copy.
outlives  If true (default) this object is to outlive the source object.

void SdsId::Size (  unsigned long *const    bytes,
StatusType *const    status
)  const [inline]
 

Return the size of an SDS structure, as required for exporting.

See also:
SdsId::Export , SdsSize()
Parameters:
bytes  The number of bytes to allow for exporting this structure.
status  Inherited status.

void SdsId::SizeDefined (  unsigned long *const    bytes,
StatusType *const    status
)  const [inline]
 

Return the size of an SDS structure, as required for exporting defined.

See also:
SdsId::ExportDefined , SdsSizeDefined()
Parameters:
bytes  The number of bytes to allow for exporting this structure when all elements are defined.
status  Inherited status.

void SdsId::Write (  const char *const    filename,
StatusType *const    status
)  const [inline]
 

Write the contents of the structure to a file.

This method exports the SDS structure into a malloced buffer, before writing that buffer to a the specified file.

See also:
SdsWrite()
Parameters:
filename  The name of the file. Will be overwritten if it already exists.
status  Inherited status.

The documentation for this class was generated from the following file:

Click here for the DRAMA home page and here for the AAO home page.

For more information, contact tjf@aaoepp.aao.gov.au 

Generated on Tue Nov 3 09:09:56 2009 for AAO DRAMA C++ Interfaces by doxygen 1.2.18