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 Member Functions

 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()