SDS_STEAL_DATA(3)

NAME

     sds_construct  sds_make_sds   sds_replicate   sds_steal_data
     sds_copy_attr sds_copy_attrs sds_append_attrs

     -a set of functions to create a new sds filled from a set of
     parameters and pointers

SYNOPSIS

     #include <soi_sds.h>

     SDS *sds_construct (int rank, int *length, int datatype, void *fillval)
     SDS *sds_make_sds (int rank, int *length, int datatype, void *data
     SDS *sds_replicate (SDS *sdsptr);
     SDS *sds_steal_data (SDS *sdsptr);
     int sds_copy_attrs (SDS *sdsout, SDS *sdsin);
     int sds_append_attrs (SDS *sdsout, SDS *sdsin, char *key);
     int sds_copy_attr (SDS *sdsout, SDS *sdsin, char *key);

DESCRIPTION

     sds_construct() makes a  complete  sds  using  rank  as  the
     number  of  dimensions,  length as the array filled with the
     axis information and fillval as the valid pointer to a  word
     of type datatype. The data array is malloc'd and filled with
     *fillval.

     sds_make_sds() creates an sds with rank, length and datatype
     defined  as  in sds_construct.  data must be a valid pointer
     to a previously malloc'd data array.

     sds_replicate() copies the entire input sds to a new sds.

     sds_steal_data() copies the entire input sds to a  new  sds,
     but  also removes the data area from the input sds and makes
     it private to the new sds.  The data pointer  of  the  input
     sds is nulled.

     sds_copy_attrs() copies the entire attribute list  from  the
     input  sds  to  the output sds. It neither copies nor checks
     the datatype nor  dimension  information.   "sds_copy_attrs"
     should  be  used  with  caution since it replicates ALL key-
     words.  Important information  in  a  partially  constructed
     dataset can be damaged.  The preferred usage for moving key-
     words from an existing sds to a new  one  already  partially
     established is to use "sds_append_attrs".

     sds_append_attrs() is like sds_copy_attrs except  attributes
     already in the out SDS are NOT replaced, only new attributes
     are added.  COMMENT and HISTORY attributes are an  exception
     and  are  treated  as  in  sds_add_attribute(3).  It neither
     copies nor checks the datatype nor dimension information.

     sds_copy_attr() copies the attribute named by the  key  from
     the input sds to the output sds.

DIAGNOSTICS

     If a new sds is created and its pointer is returned, and  if
     the  pointer is null then soi_errno should contain pertinent
     information.

SEE ALSO

     sds_construct, sds_make_sds, sds_replicate

BUGS

     sds_copy_attrs() copies the  fill-value  attribute  blindly,
     even  if the data types of the input and output datasets are
     different.

     If given a NULL pointer for  fillval,  sds_construct()  will
     set  sds->fillvalue  to  a valid pointer to the default fill
     value for the dataype requested.  In order for the  data  in
     the  newly  constructed sds to test as valid, sds->fillvalue
     must be subsequently NULL'ed or set to  a  pointer  to  some
     other value.

HISTORY

     1998-01-22     SOI Version 2.8