SDS_SET_SCALING(3)



NAME

     sds_get_fits   sds_put_fits   sds_read_fits   sds_write_fits
     sds_get_fits_head    sds_read_fits_head   sds_read_fits_data
     sds_set_scaling

     functions to  convert  between  a  SDS  and  its  FITS  file
     representation.


SYNOPSIS

     #include <stdio.h>
     #include <soi_sds.h>

     SDS *sds_get_fits (char *filename)
     SDS *sds_read_fits (char FILE *fp)
     int sds_put_fits (SDS *sds, char *filename)
     int sds_write_fits (SDS *sds, FILE *fp)
     SDS *sds_get_fits_head (char *filename)
     SDS *sds_read_fits_head (FILE *fp)
     int sds_read_fits_data (SDS *sds)
     int sds_set_scaling (SDS *sds, int bitpix, double bscale, double bzero)


DESCRIPTION

     These functions implement the sds/FITS interface  specifica-
     tion   of   SOI-TN   97-137.   They  replace  the  functions
     sds_get_one_fits   and   sds_put_one_fits,   as   well    as
     sds_get_fits_header,          sds_get_fits_data,         and
     sds_read_FITS_header.  sds_get_fits  and  sds_put_fits  (and
     sds_get_fits_head)  open  the named files for read or write;
     sds_read_fits and sds_write_fits require  previously  opened
     streams  and leave the file pointer positioned at the end of
     file  on  successful  completion.  sds_read_fits_head   also
     requires  a  previously  opened  stream;  it  leave the file
     pointer positioned at the beginning of the  FITS  data  sec-
     tion.  sds_read_fits_data assumes that sds->fp is positioned
     at the beginning of the data section; if the file pointer is
     positioned    at    the   beginning   of   the   FITS   file
     sds_read_fits_data will re-read the header and override  the
     data   type   and   organization   of  the  sds  as  needed.
     sds_get_fits and sds_get_fits_header  set  sds->filename  to
     their argument.

     sds_set_scaling sets the desired scaling  parameters  to  be
     used  when  writing  a  sds to a FITS file.  Valid values of
     bitpix are 0 (implying no  scaling),  8,  16,  and  32.  The
     advisory  scaling is only meaningful if the data internal to
     the sds are of floating-point type.  Any previously existing
     scaling parameters are ignored and over-written.



DIAGNOSTICS

     sds_get_fits and sds_read_fits return a valid pointer  to  a
     new sds structure filled with data on successful completion;
     otherwise they return a NULL.  If the sds cannot be created,
     soi_errno  is  set  to  MALLOC_FAILED.   soi_errno is set to
     FITS_ERROR and messages are appended to the error  stack  if
     the  FITS  file  does  not  conform to the standard; serious
     errors will result in a NULL sds sds pointer.

     sds_put_fits and sds_write_fits set and return various error
     codes if a stream or write error occurs.  An error condition
     will also be returned if an attempt is made to write data of
     an unsupported length.

     sds_set_scaling returns soi_errno = SDS_PTR_NULLR if the sds
     has not been mallocd.


FILES

     ~CM/include/soi_sds.h
     ~CM/src/libsds.d/sds_fits.c


SEE ALSO

     SOI Technical Note 97-137
     sds_get_one_fits(3) sds_get_fits_header(3)


BUGS

     The entire dataset is read or written in a single operation;
     this  may be very efficient for small datasets, but may lead
     to inefficiencies  or  even  unnecessary  limits  for  large
     datasets.

     No warnings are issued when  writing  sds's  of  data  types
     officially   unsupported   by  FITS  (SDS_BYTE,  SDS_USHORT,
     SDS_UINT, SDS_ULONG).  The data will be written in the  for-
     mats  specified in SOI-TN 97-137.  On machines which support
     64-bit integers, non-conforming FITS  files  involving  such
     integers  (SDS_LONG)  can  be  read and written with no more
     than a warning message on the error stack.  If the data type
     has  a  length  different from one of the supported lengths,
     the BITPIX field will be set to  8.   The  functions  assume
     that  the  machine architecture conforms with the IEEE stan-
     dard for numeric data representation.

     Data types SDS_STRING  and  SDS_COMPLEX  and  anything  else
     involving FITS tables are not supported.

     sds_set_scaling does not  refuse  a  bscale  value  of  0.0,
     although this will destroy the output information.


HISTORY

     1998-01-28     SOI V 2.8