NAME

VistaIOPackData, VistaIOUnpackData - pack or unpack a vector of values

SYNOPSIS

typedef enum { VistaIOLsbFirst, VistaIOMsbFirst } VistaIOPackOrder;

void VistaIOPackData (repn, nels, unpacked, order, plength, ppacked, palloced)

VistaIORepnKind repn;
size_t nels, *plength;
VistaIOPointer unpacked, *ppacked;
VistaIOPackOrder order;
VistaIOBoolean *palloced;

void VistaIOUnpackData (repn, nels, packed, order, plength, punpacked, palloced)

VistaIORepnKind repn;
size_t nels, *plength;
VistaIOPointer packed, *punpacked;
VistaIOPackOrder order;
VistaIOBoolean *palloced;

ARGUMENTS

repn: Specifies the representation of the values to be packed or unpacked.
nels: Specifies the number of values to be packed or unpacked.
unpacked: Specifies the location of the values to be packed.
packed: Specifies the location of the values to be unpacked.
order: Specifies the order in which values smaller than a byte are packed into a single byte, or values larger than a byte are split among multiple bytes.
plength: Specifies and returns the length of the (un)packed data, in bytes. The length is rounded up to the next whole byte.
ppacked: Specifies or returns the location of the packed data.
punpacked: Specifies or returns the location of the unpacked data.
palloced: If NULL, specifies that a buffer is being supplied to contain the results of (un)packing. Otherwise, returns TRUE if memory was allocated by the routine to contain the results, and FALSE otherwise.

DESCRIPTION

VistaIOPackData packs a vector of values into a block of contiguous bytes. Typically, it is used when preparing to output a series of values to a Vista data file. VistaIOUnpackData performs the inverse, unpacking a vector of values from a block of contiguous bytes. It is used when decoding a series of values read from a Vista data file.

Unpacked values reside in memory in a form dependent upon machine architecture. Packed values, on the other hand, are represented in a machine-independent manner using the fewest bits possible. If the values are of type VistaIOBit, for example, they might occupy one byte each in unpacked form, but in packed form each occupies a single bit. The types of values that can be (un)packed, and their form when packed, is as follows:

VistaIOBit: is packed as a single bit.
VistaIOUByte: is packed as an unsigned integer in a single 8-bit byte.
VistaIOSByte: is packed as a two's-complement integer in a single 8-bit byte.
VistaIOShort: is packed as a two's-complement integer in two 8-bit bytes.
VistaIOLong: is packed as a two's-complement integer in four 8-bit bytes.
VistaIOFloat: is packed as an IEEE-format floating-point number in four 8-bit bytes.
VistaIODouble: is packed as an IEEE-format floating-point number in eight 8-bit bytes.
VistaIOBoolean: is packed as a single bit.

The values to be (un)packed must all have one of these types, as specified by the repn argument.

The order argument specifies the order with which bits are packed into a byte, or multi-byte, packed values are separated into bytes. If the packed values each require a single bit, order specifies whether successive values are to be packed into a byte from least-significant bit to most significant (VistaIOLsbFirst), or vice versa (VistaIOMsbFirst). If the packed values each require multiple bytes, order specifies whether those bytes are to be packed from least-significant byte to most significant (VistaIOLsbFirst), or vice versa (VistaIOMsbFirst). Data in Vista data files is packed with order = VistaIOMsbFirst.

For a call to VistaIOPackData, nels specifies the number of values to be packed and unpacked points to a vector containing them. You can specify where to place the packed values in either of two ways:

You can supply your own buffer for the packed values by passing NULL in palloced, passing a pointer to the address of your buffer in ppacked, and passing a pointer to the length of your buffer in plength. On return, the actual length of the packed values will have been stored at *plength.
You can let VistaIOPackData determine the location of the packed values by passing in palloced a pointer to a VistaIOBoolean variable. VistaIOPackData then returns, via ppacked and plength, the location and length of the packed data. Depending on the type of values to be packed, their arrangement in memory, and order, actual packing may or may not be needed. That is, the packed and unpacked forms of the value may actually be identical. In this case, the returned location and length refer to the unpacked data, and palloced returns FALSE to indicate that no separate buffer for the packed data was allocated. If, however, the packed form differs from the unpacked form, VistaIOPackData will allocate memory for the packed data. The location and length of this memory are returned instead, and palloced returns TRUE to indicate that this memory should be freed when the packed values are no longer needed.

VistaIOUnpackData is called in an analogous manner. The nels argument specifies the number of values to be unpacked and packed points to a vector containing them. As for VistaIOPackData, you can specify where to place the unpacked values in either of two ways indicated by palloced.

RETURN VALUES

Both routines return TRUE if successful, and FALSE otherwise. In addition, they may set *plength, *ppacked, *punpacked, and *palloced as described above.

EXAMPLES

Here we pack a vector of bits, write the packed bits to a file, and free any storage used to represent the packed bits:

size_t nbits, length;
VistaIOBit *bits;
VistaIOPointer packed;
VistaIOBoolean alloced;
FILE *file;

...
VistaIOPackData (VistaIOBitRepn, nbits, bits, VistaIOMsbFirst, & length, & packed, & alloced);
fwrite ((char *) packed, 1, length, file);
if (alloced)

VistaIOFree (packed);

NOTES

Packing or unpacking can be done in place. For example, in a call to VistaIOPackData, unpacked and *ppacked can point to the same storage.

LIMITATIONS

The present implementation cannot pack values of type VistaIOUByte, VistaIOSByte, VistaIOShort, VistaIOLong, VistaIOFloat, or VistaIODouble if their packed and unpacked sizes differ.

DIAGNOSTICS

``Byte order not recognized.'': The routines trie to automatically detect whether the present machine stores multi-byte values from most-to-least significant byte, or vice versa. If this message is issued it means that a port to a new machine architecture was unsuccessful, in which case some additional programming is needed to support the new architecture.
``Insufficient space for (un)packed data.'': A buffer was supplied for the results of (un)packing, but the buffer is too small.
``(Un)packing type from mbits to nbits bits is not supported.'': The present implementation cannot (un)pack values of type VistaIOUByte, VistaIOSByte, VistaIOShort, VistaIOLong, VistaIOFloat, or VistaIODouble if their packed and unpacked sizes differ. If asked to do so the routine will abort the program with this message.

AUTHOR

Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>

21 January 1994

VistaIO Version 1.2.14