.ds Vv 1.2.14 .TH VistaIOPackData 3 "21 January 1994" "VistaIO Version \*(Vv" .SH NAME VistaIOPackData, VistaIOUnpackData \- pack or unpack a vector of values .SH SYNOPSIS .nf .ft B typedef enum { VistaIOLsbFirst, VistaIOMsbFirst } VistaIOPackOrder; .HP 10n .na .nh .ft B void VistaIOPackData (\fIrepn\fP, \fInels\fP, \fIunpacked\fP, \ \fIorder\fP, \fIplength\fP, \fIppacked\fP, \fIpalloced\fP) .RS VistaIORepnKind \fIrepn\fP; size_t \fInels\fP, *\fIplength\fP; VistaIOPointer \fIunpacked\fP, *\fIppacked\fP; VistaIOPackOrder \fIorder\fP; VistaIOBoolean *\fIpalloced\fP; .RE .HP 10n .ft B void VistaIOUnpackData (\fIrepn\fP, \fInels\fP, \fIpacked\fP, \ \fIorder\fP, \fIplength\fP, \fIpunpacked\fP, \fIpalloced\fP) .RS VistaIORepnKind \fIrepn\fP; size_t \fInels\fP, *\fIplength\fP; VistaIOPointer \fIpacked\fP, *\fIpunpacked\fP; VistaIOPackOrder \fIorder\fP; VistaIOBoolean *\fIpalloced\fP; .hy .ad .fi .SH ARGUMENTS .IP \fIrepn\fP 10n Specifies the representation of the values to be packed or unpacked. .IP \fInels\fP Specifies the number of values to be packed or unpacked. .IP \fIunpacked\fP Specifies the location of the values to be packed. .IP \fIpacked\fP Specifies the location of the values to be unpacked. .IP \fIorder\fP 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. .IP \fIplength\fP Specifies and returns the length of the (un)packed data, in bytes. The length is rounded up to the next whole byte. .IP \fIppacked\fP Specifies or returns the location of the packed data. .IP \fIpunpacked\fP Specifies or returns the location of the unpacked data. .IP \fIpalloced\fP If .SB NULL\c , specifies that a buffer is being supplied to contain the results of (un)packing. Otherwise, returns .SB TRUE if memory was allocated by the routine to contain the results, and .SB FALSE otherwise. .SH DESCRIPTION \fBVistaIOPackData\fP 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. \fBVistaIOUnpackData\fP 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. .PP 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 \fBVistaIOBit\fP, 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: .RS .IP \fBVistaIOBit\fP 12n is packed as a single bit. .IP \fBVistaIOUByte\fP is packed as an unsigned integer in a single 8-bit byte. .IP \fBVistaIOSByte\fP is packed as a two's-complement integer in a single 8-bit byte. .IP \fBVistaIOShort\fP is packed as a two's-complement integer in two 8-bit bytes. .IP \fBVistaIOLong\fP is packed as a two's-complement integer in four 8-bit bytes. .IP \fBVistaIOFloat\fP is packed as an IEEE-format floating-point number in four 8-bit bytes. .IP \fBVistaIODouble\fP is packed as an IEEE-format floating-point number in eight 8-bit bytes. .IP \fBVistaIOBoolean\fP is packed as a single bit. .RE .PP The values to be (un)packed must all have one of these types, as specified by the \fIrepn\fP argument. .PP The \fIorder\fP 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, \fIorder\fP specifies whether successive values are to be packed into a byte from least-significant bit to most significant (\fBVistaIOLsbFirst\fP), or vice versa (\fBVistaIOMsbFirst\fP). If the packed values each require multiple bytes, \fIorder\fP specifies whether those bytes are to be packed from least-significant byte to most significant (\fBVistaIOLsbFirst\fP), or vice versa (\fBVistaIOMsbFirst\fP). Data in Vista data files is packed with \fIorder\fP\ =\ \fBVistaIOMsbFirst\fP. .PP For a call to \fBVistaIOPackData\fP, \fInels\fP specifies the number of values to be packed and \fIunpacked\fP points to a vector containing them. You can specify where to place the packed values in either of two ways: .RS 2n .IP \(bu 2n You can supply your own buffer for the packed values by passing .SB NULL in \fIpalloced\fP, passing a pointer to the address of your buffer in \fIppacked\fP, and passing a pointer to the length of your buffer in \fIplength\fP. On return, the actual length of the packed values will have been stored at *\fIplength\fP. .IP \(bu You can let \fBVistaIOPackData\fP determine the location of the packed values by passing in \fIpalloced\fP a pointer to a \fBVistaIOBoolean\fP variable. \fBVistaIOPackData\fP then returns, via \fIppacked\fP and \fIplength\fP, the location and length of the packed data. Depending on the type of values to be packed, their arrangement in memory, and \fIorder\fP, 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 \fIpalloced\fP returns .SB FALSE to indicate that no separate buffer for the packed data was allocated. If, however, the packed form differs from the unpacked form, \fBVistaIOPackData\fP will allocate memory for the packed data. The location and length of this memory are returned instead, and \fIpalloced\fP returns .SB TRUE to indicate that this memory should be freed when the packed values are no longer needed. .RE .PP \fBVistaIOUnpackData\fP is called in an analogous manner. The \fInels\fP argument specifies the number of values to be unpacked and \fIpacked\fP points to a vector containing them. As for \fBVistaIOPackData\fP, you can specify where to place the unpacked values in either of two ways indicated by \fIpalloced\fP. .SH "RETURN VALUES" Both routines return .SB TRUE if successful, and .SB FALSE otherwise. In addition, they may set *\fIplength\fP, *\fIppacked\fP, *\fIpunpacked\fP, and *\fIpalloced\fP as described above. .SH 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: .PP .RS .nf .ft B size_t nbits, length; VistaIOBit *bits; VistaIOPointer packed; VistaIOBoolean alloced; FILE *file; .PP \&... .ft B VistaIOPackData (VistaIOBitRepn, nbits, bits, VistaIOMsbFirst, & length, & packed, & alloced); fwrite ((char *) packed, 1, length, file); if (alloced) .RS VistaIOFree (packed); .RE .RE .fi .SH NOTES Packing or unpacking can be done in place. For example, in a call to \fBVistaIOPackData\fP, \fIunpacked\fP and *\fIppacked\fP can point to the same storage. .SH LIMITATIONS The present implementation cannot pack values of type \fBVistaIOUByte\fP, \fBVistaIOSByte\fP, \fBVistaIOShort\fP, \fBVistaIOLong\fP, \fBVistaIOFloat\fP, or \fBVistaIODouble\fP if their packed and unpacked sizes differ. .SH DIAGNOSTICS .IP "``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. .IP "``Insufficient space for (un)packed data.''" A buffer was supplied for the results of (un)packing, but the buffer is too small. .IP "``(Un)packing \fItype\fP from \fImbits\fP to \fInbits\fP bits is not supported.''" The present implementation cannot (un)pack values of type \fBVistaIOUByte\fP, \fBVistaIOSByte\fP, \fBVistaIOShort\fP, \fBVistaIOLong\fP, \fBVistaIOFloat\fP, or \fBVistaIODouble\fP if their packed and unpacked sizes differ. If asked to do so the routine will abort the program with this message. .SH AUTHOR Art Pope Adaption to vistaio: Gert Wollny