Unpack

Description: Unpacks a set of values from a stream into a single dimensional array or a set of variables referenced by object parameters, and returns the number of items unpacked.

Returns: Numeric

Usage: Script

Format: Unpack(Data, Start, End, Stream[, TruncateAt, DataLength])

Parameters: Data { numeric } { required } { no default: }

An object value or an array containing the data or the object value of the module whose parameters address variables into which to store the data. For example, if you have 5 numerics to unpack, you would allocate a 1-dimensional array, 5 elements in length. You would pass this array to Unpack's Data parameter, and specify that you wish to unpack from subscript 1 to 5. Refer to the example section below for more information.

Start { numeric } { required } { no default: }

The starting array index (zero-based), or parameter number (one-based) of the data to unpack.

End { numeric } { required } { no default: }

The last array index, or parameter number of the data to unpack.

Stream { Stream } { required } { no default: }

A variable holding the stream that contains the data to be unpacked. The stream must have been generated with the Pack function.

TruncateAt { numeric } { optional } { no default: }

An optional parameter. If present specifies that all text values and stream values unpacked from the stream will be truncated after the number of bytes specified in this parameter.

DataLength { Array (return value) } { optional } { no default: }

An optional parameter. If present, specifies an array into which will be stored the length of each text and stream value unpacked from the source stream. Each length is stored at the array index corresponding to the index of the value itself. For example, if the value that would go in the destination array at index 5 were a text value, its length would be stored at index 5 in the array addressed by this parameter. Unpacked values of numeric type have Invalid stored in their entry in this array.

Comments: This function returns the number of values unpacked.

If the Data parameter is an array, the data from the stream will be unpacked into that array.

If the Data parameter is an object value, the parameters of that object must contain pointers to variables into which the data from the stream will be unpacked.

Example:

If you wish to pack 2 3-dimensional arrays, you would allocate a 1-dimensional array, 2 elements in length. You would then assign the 3-dimensional arrays to the 1-dimensional array elements, and then Pack the 1-dimensional array.

For example:

Array1D = New(2);

Array1D[0] = Array3D_1;

Array1D[1] = Array3D_2;

Pack(Array1D, 0, 1, &Stream);

Unpacking this is almost an identical operation:

Array1D = New(2);

UnPack(Array1D, 0, 2, Stream);

Array3D_1 = Array1D[0];

Array3D_2 = Array1D[1];

All you need to know is how many things you wish to pack and unpack, not the sizes or types of the things (a ValueType(Array1D[0]) will tell you the type). As the stream position is moved after each pack or unpack, you can simply unpack one item at a time and check the return value of UnPack.