|
Purpose
|
Specifies a non-standard bit length for the data set values. |
|
Return value
|
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise. |
|
Description
|
SDsetnbitdataset allows the HDF user to specify that the data set identified by the parameter sds_id contains data of a non-standard length defined by the parameters start_bit and bit_len. Additional information about the non-standard bit length decoding are specified in the parameters sign_ext and fill_one. |
|
|
Any length between 1 and 32 bits can be specified. After SDsetnbitdataset has been called for the data set array, any read or write operations will involve a conversion between the new data length of the data set array and the data length of the read or write buffer. |
|
|
Bit lengths of all data types are counted from the right of the bit field starting with 0. In a bit field containing the values 01111011, bits 2 and 7 are set to 0 and all the other bits are set to 1. |
|
|
The start_bit parameter specifies the leftmost position of the variable-length bit field to be written. For example, in the bit field described in the preceding paragraph a start_bit parameter set to 4 would correspond to the fourth bit value of 1 from the right. |
|
|
The bit_len parameter specifies the number of bits of the variable-length bit field to be written. This number includes the starting bit and the count proceeds toward the right end of the bit field - toward the lower-bit numbers. For example, starting at bit 5 and writing 4 bits of the bit field described in the preceding paragraph would result in the bit field 1110 being written to the data set. This would correspond to a start_bit value of 5 and a bit_len value of 4. |
|
|
The sign_ext parameter specifies whether to use the leftmost bit of the variable-length bit field to sign-extend to the leftmost bit of the data set data. For example, if 9-bit signed integer data is extracted from bits 17-25 and the bit in position 25 is 1, then when the data is read back from disk, bits 26-31 will be set to 1. Otherwise bit 25 will be 0 and bits 26-31 will be set to 0. The sign_ext parameter can be set to TRUE (or 1) or FALSE (or 0) - specify TRUE to sign-extend. |
|
|
The fill_one specifies whether to fill the "background" bits with the value 1 or 0. This parameter can also be set to TRUE or FALSE. |
|
|
The "background" bits of a variable-length data set are the bits that fall outside of the variable-length bit field stored on disk. For example, if five bits of an unsigned 16-bit integer data set located in bits 5 to 9 are written to disk with the fill_one parameter set to TRUE (or 1), then when the data is reread into memory bits 0 to 4 and 10 to 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 to 4 and 10 to 15 would be set to 0. |
|
|
This bit operation is performed before the sign-extend bit-filling. For example, using the sign_ext example above, bits 0 to 16 and 26 to 31 will first be set to the "background" bit value, and then bits 26 to 31 will be set to 1 or 0 based on the value of the 25th bit. |