SDS_CONVERT(3)

NAME

     sds_data_convert, sds_convert - data type conversion of  sds
     data

SYNOPSIS

     #include <soi_sds.h>
     int sds_data_convert(SDS *sds, int datatype)
     int sds_convert(SDS *sds, int datatype)

DESCRIPTION

     sds_data_convert  converts  the  sds  data  values  to   the
     selected  data type according to the rules set out in SOI-TN
     97-137, the sds/FITS interface document.

     sds_convert converts the sds data values with its own  rules
     for scaling and offsets.  In conversions from floating-point
     to fixed-point data types, or from types of greater range to
     types  of  lesser range, an arbitrary scaling and offset may
     be applied based on the actual data range.   These  will  be
     preserved  as the advisory scaling parameters, so conversion
     is  not  necessarily   symmetric.    In   conversions   from
     floating-point to fixed-point or from greater to lesser pre-
     cision fixed-point data types, the fill  value  is  uncondi-
     tionally set to the largest magnitude representable negative
     number.

DIAGNOSTICS

     If either the existing data type  or  the  requested  output
     data  type  is  not  among  those  implemented,  the  sds is
     unchanged,    sds_data_convert     returns     the     value
     UNSUPPORTED_DATATYPE  and  soi_errno  is  set  to the return
     value.   If  there  are  data  values  outside   the   range
     representable  by the output data type, they are replaced by
     the bit pattern encoding missing or  invalid  data  for  the
     output  type,  and  the  function returns DATA_OUT_OF_RANGE;
     otherwise the function returns 0.

     sds_convert returns either UNSUPPORTED_DATATYPE or 0.

FILES

SEE ALSO

BUGS

     sds_convert is obsolete; its use is discouraged.

     Only conversions among the data types SDS_DOUBLE, SDS_FLOAT,
     SDS_INT, SDS_SHORT, SDS_BYTE, and SDS_UBYTE are supported by
     sds_data_convert;  sds_convert   does   not   even   support
     SDS_UBYTE.

     Conversions  of   floating   to   fixed   point   types   by
     sds_data_convert  assume that the prevailing truncation mode
     is toward 0.
     No data rescaling is performed by sds_data_convert, so  loss
     of precision is possible.  For example, conversion of float-
     ing point data within the range (-0.5, 0.5)  to  fixed-point
     type  will  result  in  a  data  set  all 0's.  Data must be
     appropriately pre-scaled and/or offset before conversion  to
     avoid loss of information.

     In unusual circumstances it is possible for valid data to be
     converted  to  invalid  data  even  though  the  values  are
     representable in the output type.  For example,  in  conver-
     sion  of  short  integers  to  floating points when the FILL
     value is 32767, all values of 32767 will be converted to NaN
     and  all  values  of -32768 to -32768.0.  If the data set is
     then re-converted to short integers, both the  NaN's  (form-
     erly  32767)  and  values  of  -32768.0  will  be set to the
     default FILL value for short integers of -32768.  This prob-
     lem  will not occur if the default FILL values for the given
     data types are always used.

HISTORY

     1997-01-26     SOI V. 2.8