Pack

Description: This function packs a set of module parameters or an array of values into a stream, and returns the number of items that were not packed.

Returns: Numeric

Usage: Script

Format: Pack(Data, Start, End, StreamVarPtr)

Parameters: Data { Object value or array } { required } { no default }

An object value or an array containing the data or the object value of the module whose parameters are to be packed. For example, if you have 5 numerics to pack, you would allocate a 1-dimensional array, 5 elements in length. You would then assign the 5 numerics to this array's elements, and pass the array to the Data parameter (i.e. the first parameter to Pack). You would specify that you wish to pack 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 pack.

End { numeric } { required } { no default }

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

StreamVarPtr { pointer } { required } { no default }

A pointer to a variable holding the stream into which the data will be packed. The variable can also hold Invalid - see Comments section below for more details.

Comments: StreamVar must be a pointer to a variable, not simply the name of a variable which holds a stream. This is because the Pack function will create a new stream under certain circumstances and store the packed data in it. If the variable that StreamVarPtr addresses contains a stream, then the data will be packed into that stream.

If the variable that StreamVarPtr addresses contains Invalid, Pack will create a new buffer stream, pack the data into it and store the new stream in the variable pointed at by StreamVarPtr.

If a buffer stream is supplied, or Pack creates a buffer stream, it will be replaced by a temporary file stream if the output stream exceeds 2Mb. This provides a balance between performance and memory use.

If a stream is provided, packing starts at the current stream position. After packing, the stream current position is left at the end of the packed data.

Only variables of numeric, text, or stream types will be packed. Arrays of those types, up to and including 3 dimensions, will also be packed.

Any illegal values are packed as Invalid. Further, the Pack function has been designed in such a way that multi-dimensional arrays that have one or more dimensions that have never had a value assigned can be handled. The correct number of Invalids for the unallocated array dimensions are written to the packed stream in place of the data values that would be there if the elements were allocated. Once the stream is unpacked, the array elements are allocated, but are assigned Invalid.

Generally called in the form:

Pack(Self(), 0, NParms(Self()), Stream);

This works because NParms(Self()) gives the total number, which is 1 higher than the highest index

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.