[Back to Interface] [Prev] [Next]

SDsetnbitdataset/sfsnbit

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

sds_id IN:

Data set identifier returned by SDcreate or SDselect

start_bit IN:

Leftmost bit of the field to be written

bit_len IN:

Length of the bit field to be written

sign_ext IN:

Sign extend specifier

fill_one IN:

Background bit specifier

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.

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



[Back to Interface] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF Reference Manual - 07/29/98, NCSA HDF Development Group.