[Top]
[Prev]
[Next]
[Bottom]
SDsetnbitdataset/sfsnbit
intn SDsetnbitdataset(int32
sds_id
, intn
start_bit
, intn
bit_len
, intn
sign_ext
, intn
fill_one
)
sds_id
IN:
Dataset identifier returned from
SDselect
start_bit
IN:
Leftmost bit of the field to bewritten
bit_len
IN:
Length of the bit field to bewritten
sign_ext
IN:
Sign extend specifier
fill_one
IN:
Background bit specifier
Purpose
Specifies a non-standard bit length for SDS data.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
SDnbitdataset
allows the HDF user to specify that a particular SDS array contains data of a non-standard length. Any length between 1 and 32 bits can be specified. After
SDnbitdataset
has been called for the SDS array, any read or write operations will involve a conversion between the new data length of the SDS 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 preceeding paragraph a start_bit parameter set to 4 would correspond to the 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 preceeding paragraph would result in the bit field 1110 being written to the dataset. 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 dataset 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 is set to either TRUE or FALSE - specify TRUE to sign-extend.
The fill_one specifies whether to fill the "background" bits with the value 1 or 0. This parameter is also set to either TRUE or FALSE.
The "background" bits of a variable-length dataset 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 dataset 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.
FORTRAN
integer function sfsnbit(sds_id, start_bit, bit_len, sign_ext, fill_one)
integer sds_id, start_bit, bit_len, sign_ext, fill_one
[Top]
[Prev]
[Next]
[Bottom]
hdfhelp@ncsa.uiuc.edu
HDF User's Reference Manual, Draft 06/09/97, NCSA HDF Development Group.