Flattened Data

LabVIEW converts data from the format in memory to a form more suitable for writing to or reading from a file. This more suitable format is called flattened data.

Because LabVIEW stores strings, arrays, and paths in handles (pointers to pointers in separate regions of memory), clusters that contain these strings and arrays are noncontiguous. In general, LabVIEW stores data in tree form. For example, LabVIEW stores a cluster as a double-precision, floating-point number and a string as an 8-byte floating-point number followed by a 4-byte handle to the string. LabVIEW does not store the string data adjacent to the extended-precision, floating-point number in memory. Therefore, to write the cluster data to disk, LabVIEW must get the data from two different places. With a cluster that contains many strings, arrays, and/or paths, LabVIEW stores the data in many different places.

When you save data to a file, LabVIEW flattens the data into a single string before saving it. Flattening data makes the data from an arbitrarily complex cluster contiguous rather than stored in several places. When LabVIEW loads data from a file, LabVIEW must perform the reverse operation, reading a single string and unflattening it into its internal, possibly noncontiguous, form.

LabVIEW normalizes the flattened data to a standard form so VIs that run on any platform can use the data. LabVIEW stores flattened numeric data in big-endian form (most significant byte first), and stores flattened extended-precision, floating-point numbers as 16-byte quantities.

When writing data to a file for use by an application that was not created using LabVIEW or when reading data from a file produced by an application that was not created using LabVIEW, you can transform the data into little-endian (least significant byte first) or big-endian form after flattening or before unflattening. Windows-based applications typically expect numeric data to be in little-endian form.

Use the Flatten To String and Unflatten From String functions to flatten and unflatten data just as LabVIEW does internally when LabVIEW saves and loads data.

The flattened form of a piece of data does not encode the type of the data. LabVIEW stores this information in a type descriptor. The Unflatten From String function requires you to wire a data type as an input so the function can decode the string properly.

Use the variant data type to work with data independently of data type instead of flattening the data when you write to memory and unflattening the data when you read from memory. Use the Variant functions to create and manipulate variant data.

Note��If you use the Flatten To String function on variant data, LabVIEW will flatten the variant and all its contents, including attributes. However, if you use the Variant To Flattened String function, LabVIEW flattens only the variant and discards any attributes.

Booleans and Numeric Objects

The flattened form of any numeric type and Boolean type stores the data only in big-endian format. For example, a 32-bit integer with a value of �19 is flattened to FFFF FFED. A double-precision floating-point number with a value equal to 1/4 is flattened to 3FD0 0000 0000 0000. A Boolean value of TRUE is any nonzero value. A Boolean value of FALSE is 00.

The flattened form for extended-precision numbers is the 128-bit extended-precision, floating-point format. When you save extended-precision numbers to disk, LabVIEW stores them in this format.

Strings and Paths

Because strings and paths have variable sizes, a flattened 32-bit integer that records the length in bytes precedes the flattened form. For example, a string type with value ABC is flattened to 0000 0003 4142 43. For strings, the flattened format is similar to the format the string takes in memory.

However, paths do not have a length value preceding them when LabVIEW stores them in memory, so this value comes from the actual size of the data in memory and prefixes the value when LabVIEW flattens the data. This length is preceded by four characters: PTH0.

For example, a path with value C:\File is flattened to 5054 4830 0000 000B 0000 0002 0143 0466 696C 65.

5054 4830 indicates PTH0. 0000 000B indicates 11 bytes total. 0000 is the type. 0002 is the number of components. 0143 indicates the letter C as a Pascal string. 0466 696C 65 indicates the word File as a Pascal string.

Arrays

Flattened 32-bit integers that record the size, in elements, of each of the dimensions of an array precede the data for a flattened array. The slowest varying dimension is first, followed successively by the faster varying dimensions, just as the dimension sizes are stored in memory. The flattened data follows immediately after these dimension sizes in the same order in which LabVIEW stores them in memory. The following example shows a 2D array of six 8-bit integers.

{ {1, 2, 3}, {4, 5, 6} } is flattened to 0000 0002 0000 0003 0102 0304 0506.

The following example shows a flattened 1D array of Boolean variables.

{T, F, T, T} is flattened to 0000 0004 0100 0101. The preferred value for TRUE is 01.

Clusters

A flattened cluster is the concatenation, in cluster order, of the flattened data of its elements. For example, a flattened cluster of a 16-bit integer of value 4 (decimal) and a 32-bit integer of value 12 is 0004 0000 000C.

A flattened cluster of a string ABC and a 16-bit integer of value 4 is 0000 0003 4142 4300 04.

A flattened cluster of a 16-bit integer of value 7, a cluster of a 16-bit integer of value 8, and a 16-bit integer of value 9 is 0007 0008 0009.

Waveforms

LabVIEW flattens waveforms like clusters.

Refnums

LabVIEW stores the majority of flattened refnums as flattened 32-bit integers, which represent an internal LabVIEW data structure.

You can classify the remaining refnums by their refnum type code.

Type codes 0xE, 0xF and 0x15 are refnums that store their data as a flattened string. This string contains the value of the refnum tag, and can be empty (4 bytes of zero).

Type codes 0x1A, 0X1C, and 0x1D concatenate, in the following order:

1. A flattened string for the name in the refnum tag. This string is empty (4 bytes of zero) if the refnum does not have a tag.
2. A flattened string that contains information specific to the refnum. This string can be empty (4 bytes of zero).
3. A flattened string that contains information specific to the refnum. This string can be empty (4 bytes of zero).
4. A flattened 32-bit signed integer that contains information specific to the refnum.
5. A flattened string that contains information specific to the refnum. This string can be empty (4 bytes of zero).

Classes

LabVIEW flattens a LabVIEW class according to the following general format:

• level in hierarchy�4-byte unsigned integer representing the number of levels into the class hierarchy the class occurs. For example, if this value is 2, the class has one ancestor class between itself and LabVIEW Object.

  Note��If level in hierarchy is 0, the object is an instance of LabVIEW Object, and LabVIEW excludes the other three fields from the string.

• class name�A sequence of Pascal strings preceded by a single byte that indicates the length of the qualified name of the class. Each Pascal string, or sequence of bytes where the first byte indicates the length of the string and the remaining bytes are the text of the string, represents one segment of the qualified name. The last Pascal string is a length byte of zero. This section of the flattened string includes enough zero pad bytes to increase the class name section to a multiple of 4 bytes.
• version list�A series of clusters in which each cluster is four 2-byte unsigned integers that represent a version number. The first cluster in this list represents the version of class name, the second is the version of its parent, and so on. This list contains one version number for each level in hierarchy.

  Note��If level in hierarchy is 1 and the version is 0, the flattened data represents the default data of the class, and LabVIEW excludes the remaining field from the string.

• private data�A series of flattened clusters representing the private data of each level of the hierarchy. In reverse order of the version list, the first cluster in this series corresponds to the oldest ancestor class. Each flattened cluster begins with a 4-byte signed integer that represents the number of bytes in the data that follows. If this initial number is 0, the flattened cluster represents the default data for the corresponding class in the hierarchy. Otherwise, the following data uses the standard flattened cluster representation explained earlier in this topic. Each flattened cluster ends with enough pad bytes to increase the cluster to a multiple of 4 bytes.