Compression for HDF SDS
    There are two new compression functions added to the SD interface in this
release, SDsetcompress and SDsetnbitdataset.   Both functions are used as
higher-level routines to access the HCcreate function (HCcreate is described
in the reference manual).  SDsetnbitdataset allows for the storage of 1-32 bit 
integer values (instead of being restricted to 8, 16 or 32-bit sizes) in a
scientific dataset. SDsetcompress can be used to compress a scientific dataset
through the SD interface instead of dropping down to the lower-level H
interface.

N-bit SDS using SDsetnbitdataset:

    The interface to SDsetnbitdataset is described below:

    intn SDsetnbitdataset(sds_id,start_bit,bit_len,sign_ext,fill_one); 

    int32 sds_id - The id of a scientific dataset returned from SDcreate or
        SDselect.
        
    intn start_bit - This value determines the bit position of the highest end
        of the n-bit data to write out. Bits in all number-types are counted
        from the right starting with 0. For example, in the following bit data,
        "01111011", bits 2 and 7 are set to 0 and all the other bits are set to
        one. 

    intn bit_len - The number of bits in the n-bit data to write, including the
        starting bit, counting towards the right (i.e. lower bit numbers). For
        example, starting at bit 5 and writing 4 bits from the following bit
        data, "01111011", would write out the bit data, "1110", to the dataset
        on disk. 

    intn sign_ext - Whether to use the top bit of the n-bit data to sign-extend
        to the highest bit in the memory representation of the data. For
        example, if 9-bit signed integer data is being extracted from bits
        17-25 (nt=DFNT_INT32, start_bit=25, bit_len=9, see below for full
        information about start_bit & bit_len parameters) and the bit in
        position 25 is a 1, then when the data is read back in from the disk,
        bits 26-31 will be set to a 1, otherwise bit 25 will be a zero and bits
        26-31 will be set to 0. This bit-filling takes higher precendence (i.e.
        is performed after) the fill_one (see below) bit-filling. 

    intn fill_one - Whether to fill the "background" bits with 1's or 0's.
        The "background" bits of a n-bit dataset are those bits in the
        in-memory representation which fall outside of the actual n-bit field
        stored on disk. For example, if 5 bits of an unsigned 16-bit integer
        (in-memory) dataset located in bits 5-9 are written to disk with the
        fill_one parameter set to TRUE (or 1), then when the data is read back
        into memory at a future time, bits 0-4 and 10-15 would be set to 1. If
        the same 5-bit data was written with a fill_one value of FALSE (or 0),
        then bits 0-4 and 10-15 would be set to 0.  This setting has a lower
        precedence (i.e. is performed first) than the sign_ext setting. For
        example, using the sign_ext example above, bits 0-16 and 26-31 will
        first be set to either 1 or 0 based on the fill_one parameter, and then
        bits 26-31 will be set to 1 or 0 based on bit-25's value. 
    
    RETURNS - SUCCEED (0) or FAIL (-1) for success/failure.

    The corresponding FORTRAN function name is sfsnbit which takes the
    same parameters in the same order.

    For example, to store an unsigned 12-bit integer (which is represented
    unpacked in memory as an unsigned 16-bit integer), with no sign extension
    or bit filling and which starts at bit 14 (counting from the right with bit
    zero being the lowest) the following setup & call would be appropriate: 

    intn sign_ext = FALSE; 
    intn fill_one = FALSE; 
    intn start_bit= 14; 
    intn bit_len = 12; 
    SDsetnbitdataset(sds_id,start_bit,bit_len,sign_ext,fill_one); 

    Further reads and writes to this dataset would transparently convert the
    16-bit unsigned integers from memory into 12-bit unsigned integers stored
    on disk.

    More details about this function can be found in the HDF library reference
    manual.

Compressed SDS data using SDsetcompress:

        The SDsetcompress function call contains a subset of the parameters to
the HCcreate function call described in compression.txt and performs the same
types of compression.

    The interface to SDsetcompress is described below:

    intn SDsetcompress(sds_id,comp_type,c_info);

    int32 sds_id - The id of a scientific dataset returned from SDcreate or
        SDselect.

    int32 comp_type - The type of compression to encode the dataset with.
        The values are the same as for HCcreate:
            COMP_CODE_NONE - for no compression
            COMP_CODE_RLE - for RLE encoding
            COMP_CODE_SKPHUFF - for adaptive Huffman
            COMP_CODE_DEFLATE - for gzip 'deflation'

    coder_info *c_info - Information needed for the encoding type chosen.
        For COMP_CODE_NONE and COMP_CODE_RLE, this is unused and can be set to
        NULL.  For COMP_CODE_SKPHUFF, the structure skphuff in this union needs
        information about the size of the data elements in bytes (see example
        below).  For COMP_CODE_DEFLATE, the structure deflate in this union
        need information about "effort" to try to compress with (see example
        below).  For more information about the types of compression and the
        coder information see the compression.txt document in this directory.

    RETURNS - SUCCEED (0) or FAIL (-1) for success/failure.

    Similarly to the HCcreate function, SDsetcompress can be used to create
    compressed dataset or to compress existing ones.

    For example, to compress unsigned 16-bit integer data using the adaptive
    Huffman algorithm, the following setup and call would be used:

    coder_info c_info;
    c_info.skphuff.skp_size=sizeof(uint16);
    SDsetcompress(sds_id,COMP_CODER_SKPHUFF,&c_info);

    Further reads and writes to this dataset would transparently convert the
    16-bit unsigned integers from memory into a compressed representation on
    disk.

    For example, to compress dataset using the gzip deflation algorithm, with
    the maximum effort to compress the data, the following setup and call would
    be used:

    coder_info c_info;
    c_info.deflate.level=9;
    SDsetcompress(sds_id,COMP_CODER_DEFLATE,&c_info);

    Currently, SDsetcompress is limited to creating new datasets or appending
    new slices/slabs onto existing datasets.  Overwriting existing data in a
    dataset will be supported at some point in the future.

    More details about this function can be found in the HDF library reference
    manual.

